Re: [gtk-list] Re: Documenting GTK

[Raph Levien <raph acm org>]

> Well, I certainly would like to help.  At the moment, I'm writing some
> programs using gtk and the main difficulty is to understand some of the
> basic concepts.  For instance, I haven't figured out what mapping and
> realizing is.  If someone can help me out to gain some overall insights,
> it would be great.  From there on, I can figure out what I need and
> document it at the same time.  The format is no problem, I can write it
> in Texinfo, html or anything you want (except Ms word :-).  I'm also
> willing to (help) coordinate this.  

I'll try to tackle this one.

Realizing and mapping are part of the widget's "lifecycle". In general, 
allocating X resources happens in the realize stage (creating the X 
window if the widget has its own window, loading pixmaps, etc.). When the 
widget is to actually be made visible on the display, the map method is 
called. Again, for widgets with their own windows, this generally 
translates into a call to gdk_window_show (), which itself is a wrapper 
for XMapWindow. Widgets without their own windows usually just get drawn.

The complete lifecycle for a widget looks something like this: new, init, 
more initialization code in the new() method of the widget itself, 
size_allocate, size_request, realize, map, events (any number of times), 
unmap, unrealize, destroy. Actually, the whole sequence from map to unmap 
can be repeated any number of times if gtk_widget_show and 
gtk_widget_hide are used -- that's one reason why the distinction between 
realize and map exists. 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 hope this is helpful. I definitely agree that this area of GTK could 
stand to use some real documentation.

Raph