Re: [gtk-list] [FAQ] O'Caml - gtk bindings

[Tim Janik <Tim Janik Hamburg Netsurf DE>]

On Tue, 27 Jan 1998, David Monniaux wrote:

> [ O'Caml page: http://pauillac.inria.fr/ocaml
>   ML-family functional language with imperative features, parameterized
>   modules and objects.
> ]
> 
> I've started a gtk-O'Caml binding system.
> The basics of the system, including callbacks, work fine.

cool

> I've got tons of problems with the lack of documentation of widgets,
> especially signals. It is difficult, in particular, to deal with
> widgets passing pointers as arguments to signal handlers.
> 
> IMHO, a prerequisite for efficient work on this topic is that widgets
> should be documented. :-)  I don't ask for tons of text; a terse
> description of functions, the type and name of their arguments and some
> remarks about caveats and nonintuitive behaviours should be sufficient.

well, as you might have guessed this is not caused by bad will of the widget
programmers (mainly peter) but by a certain lack of time on the developer
side. since gtk+ is getting more and more attention and new contributors
pop up about every week, most of them took the learning curve (as you do)
but didn't comment on it in some form of documentation. rhis is sad but
understandable (i did so as well ;( ).

since we got new maintainers for the faq/tutorial this might change soon,
depending on their amount of time and motivation.

as a general rule, the signal names newly introduced by a widget class can be
looked up at the beginning of its source file in an enum, e.g. gtkcontainer.c:
enum {
  ADD,
  REMOVE,
  NEED_RESIZE,
  FOREACH,
  FOCUS,
  LAST_SIGNAL
};

then you look for the signal names in the corresponding class definition (*.h
files) gtkcontainer.h:

  void (* add)         (GtkContainer     *container,
                        GtkWidget        *widget);
  void (* remove)      (GtkContainer     *container,
                        GtkWidget        *widget);
  gint (* need_resize) (GtkContainer     *container);
  void (* foreach)     (GtkContainer     *container,
                        GtkCallback       callback,
                        gpointer          callbabck_data);
  gint (* focus)       (GtkContainer     *container,
                        GtkDirectionType  direction);

now you get the function semantics by appending a gpointer func_data
parameter, which makes up the following prototypes for your application:

void MyContainerSignal_add (GtkContainer     *container,
                            GtkWidget        *widget,
                            gpointer           func_data);
void MyContainerSignal_remove (GtkContainer     *container,
                               GtkWidget        *widget,
                               gpointer          func_data);
gint MyContainerSignal_need_resize) (GtkContainer     *container,
                                     gpointer          func_data);
void MyContainerSignal_foreach (GtkContainer     *container,
                                GtkCallback       callback,
                                gpointer          callbabck_data,
                                gpointer          func_data);
gint MyContainerSignal_focus (GtkContainer     *container,
			      GtkDirectionType  direction,
                              gpointer          func_data);



> [in particular: move_resize seems to be called only once, when the window
> is created, and with first two args pointers on integers -1; isn't it
> supposed to be called on each resizing? and what is the use of its boolean
> return value?]

i haven't dug into the code deep enough to answer when exactly the signal
gets invoked, but for the return value i can tell that it indicates wether
a further resize is needed or not (e.g. if you change the windows width/height
values in the callback func, you should return true). the container (window)
will then be added to the resizing queue again.

> 
> regards, David
> 

---
ciaoTJ