Re: GTK+ ref docs - extra introductory sections

[Havoc Pennington <rhp zirx pair com>]

On Fri, 11 Jun 1999, Damon Chaplin wrote:
> 
> Possible sections:
> 
>   The GTK+ object system -
> 	how the structs fit together.
>         the class functions, and how they relate to signals.
>         the standard macros for using objects e.g. GTK_WIDGET ()
>           (I need to update gtk-doc so it adds these to each widget's page as
>            well, with a link to the standard description)
> 	reference counting.
> 
>   Signals -
> 	how they are emitted.
> 	what happens during an emission.
> 	how it relates to events from X Windows.
> 	stopping emissions.
>

Most of this stuff is in my book, which will be under a free license it
appears. The book itself won't appear until late August or so, and most
likely the electronic copy will appear at the same time - but, there will
be a couple of "preview chapters" and they might happen to include this
information.:-)

There might be licensing problems with putting this text in the RDP
stuff, I don't know - I'm sure other people can write better text about it
anyway. But, just so you know that this exists (or in practical terms, so
you know it will exist in a couple months).

I'll be making an announcement that the book exists and have exact license
terms and an outline, probably on Monday.
 
>   Widget layout -
>         how sizes are calculated - size_request/size_allocate, set_usize(),
> 	  default window size.
>         how dynamic changes take place - queuing resizes, the idle function.
>         what is stored in widget->allocation & widget->requisition.
>         how widgets relate to X windows (and maybe MS Windows eventually).
> 	related signals - size_request, size_allocate, configure_event.
>

My book describes the "size negotiation" process, allocation and request,
but I haven't delved into the details of queuing resizes, etc. and I have
no real idea how that works. So this is something that will still need
covering.
 
>   Widget redrawing -
> 	queuing redraws, queuing clears, APP_PAINTABLE flag,
>         related signals - expose, draw, draw_default, draw_focus.
> 	how it relates to styles & themes.
>

I've covered some of this, but not all that well. So it would be
worthwhile to re-cover. (In fact I didn't talk about redraw vs. clear, or
APP_PAINTABLE, or styles very much - the hazards of a 5-month book.)
 
>   Keyboard handling -
> 	what happens to keyboard events.
> 	keyboard focus & the default widget.
> 	how it relates to keyboard accelerators & bindings.
>

I've covered this some too, but it could be more in-depth; I glossed over
accelerators and bindings, so sections on that are still needed.
 
> I think these sections are probably more important than most of the other docs.
> Once people understand the underlying architecture, everything else becomes much
> easier to understand. (Having recently understood how the main GLib event loop
> works, I myself feel a lot more confident with GTK+.)
> 

And I didn't cover the main loop in too much depth either.

Anyway, I would say that I have said almost everything you could think of
to say about the object system and quite a bit about signal emissions and
their relationship to events. But the rest of the stuff you mentioned
isn't really in there. Well, I hit the highlights but that's all.

The book is mostly a Gnome tutorial, but it has an object system/signals
chapter and a Gdk/events chapter that are fairly in-depth. It doesn't
overlap with the glib/Gdk/Gtk reference to any significant extent. The
book is sort of a sequel to the Gtk tutorial and a conceptual supplement
to the reference guide.

If you wanted, you could put conceptual stuff in my book rather than the
reference guide; it might be nicer, since I think the reference guide is
intended to be included with books? I don't know. I think there's
something to be said for separating the book-type stuff and the
reference-type stuff.

I do feel bad offering this, because the book won't be available for
hacking for a couple months still. At the same time, I hate to see you
write something I've already written, because we are planning to put it
under a license that RMS and Miguel are happy with. So, take this for
whatever it's worth to you.

Havoc