Re: [gtk-list] Re: Documenting GTK

[Owen Taylor <owt1 cornell edu>]

> [ ... ] Events include all kinds of things, including 
> mouse and keyboard, expose, focus, etc. Draw and paint also fit in 
> somewhere, but I'm not too clear on the precise distinction between draw, 
> paint, and expose.

I'll try to follow up here, and explain a bit, though I won't claim
to know all the subtlities myself:

A widget can learn about the need to redraw itself in two ways:

1) A "expose_event" signal is sent to the widget when part of the
   window is uncovered. (For instance, when an obscuring window is
   moved or the window is initially mapped.) This typically comes
   from an X Expose event.

2) Either the toolkit or the application may call 
   gtk_widget_draw(GtkWidget *widget, GdkRectangle *area) to indicate
   that some part (or all, if area=NULL) of the widget needs to 
   be redrawn. This then triggers the sending of a "draw" signal
   to the widget.

Note that the default handler for the "draw" signal is generate an
"expose_event" signal for the affected area, so a simple widget which
doesn't care about the difference (for instance, child classes of
GtkMisc, such as GtkLabel, or GtkArrow), can simply have a handler
for the "expose_event" signal.

Descendants of GtkContainer however, need to send the proper type
of signal to any child widgets which intersect the affected area.
Thus, they need handlers for both types of event. If the container
widget does not simply contain its child widgets, but also adds 
additional ornamentation, then, to avoid duplicating the code that
draws the ornamentation between the "draw" and "expose_event"
handlers, it is of often useful to put that code into a separate
subroutine, typically called gtk_foo_paint.
   
----

My original objections to the scheme of web based documentation were
two-fold: first it seemed that the chunk of documentation was a bit
too small - I'm not sure you can document the typical widget
coherently by _just_ writing separate descriptions of its member
functions, signals, and options, and there is a lot of work to be done
just to figure out what these are. Second, there is a lot of work to
be done to go from a plain text form to the final form (adding markup,
and editing each widget). Both of these boil down to seeing the scheme
as being a lot of work for the maintainer, so if Jay thinks he can
handle it, I'm not going to complain.

But it might still be nice to have the option of allowing potential
documentors to submit larger chunks (in TexInfo?). I'd much rather
write a couple of pages in a text editor than spend an hour online
filling in boxes on web forms.

Regards,
                                        Owen