GTK+ ref docs - extra introductory sections

[Damon Chaplin <damon karuna freeserve co uk>]

I think the GTK+ reference documentation needs a couple of extra introductory
sections to give an overview of the main features of GTK+.

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.

  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.

  Widget redrawing -
	queuing redraws, queuing clears, APP_PAINTABLE flag,
        related signals - expose, draw, draw_default, draw_focus.
	how it relates to styles & themes.

  Keyboard handling -
	what happens to keyboard events.
	keyboard focus & the default widget.
	how it relates to keyboard accelerators & bindings.



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+.)

Any comments? Any other 'basic architecture' sections that should be considered?

How many people besides Owen & Tim understand all of the above?? :)

Damon