canvas item docs

[Havoc Pennington <hp redhat com>]

Hi,

This is a useful document Federico gave me once, I don't know if it's
in CVS anywhere. I'm cleaning out my home directory (after setting it
as my desktop) and deleting the file so wanted to post it for
archival. Maybe someone can stick it in the docs if it isn't there.

Havoc

The proper sequence for queueing updates and redraws is this:

	1. A state change happens in a canvas item, usually from
           direct manipulation through the user interface.

	2. The canvas item stores an internal flag saying that it
           needs to change one of its attributes, and also stores the
           necessary information to change that attribute.

	3. The canvas item then queues an update from the canvas using
           gnome_canvas_item_request_update().  The canvas installs an
           idle handler on the GTK+ main loop.

	4. The application keeps running, possibly requesting updates
           for other items, until it finishes its work and all its
           interaction-related tasks, and gets back to the idle loop.

	5. The idle handler for the canvas is run.  The canvas calls
           the ::update() method of each item that requested an
           update.

	6. The ::update() method for an item needs to call the same
           method in the item's parent class.  It should recalculate
           its internal state based on the flags it set in step 2.  It
           should then queue a redraw from the canvas based on its new
           state, by using any of these functions:

		gnome_canvas_request_redraw_uta()
		gnome_canvas_request_redraw()
		gnome_canvas_item_request_redraw_svp()

	   The item should turn off the flags that say what it needs
	   to update, of course.

	7. After all items that need it have been updated, and as such
           they have recomputed their bounding boxes and queued the
           appropriate redraws, the canvas calls the ::draw() or
           ::render() methods of items that need it.

	8. The canvas is now fully updated and redrawn, and the
           application continues to run.

Canvas item behavior:

	* Items should try to delay all updates until their ::update()
          method.  They should do this by storing internal flags that
          say that a particular attribute needs updating, and also the
          data that is required to update that attribute.  

	  For example, an item could have a flag called
          "need_color_update", and also a color specifier.  The
          ::update() method would do the expensive operations like
          asking the X server to allocate that color.

	* Canvas items should queue a redraw, not an update, upon
          destruction.  This could be done automatically by the canvas
          by requesting an update for the whole child's bounding box,
          but it is not done like this.  Rationale:  complex items may
          have big "holes" in them, which the canvas may not need to
          update at all, and so it is the item who knows the minimal
          area that needs to be repainted if it disappears as a result
          of being destroyed.

	* The way a redraw is queued when a canvas item is destroyed
          is very similar to the way it is queued when the item's
          ::update() method gets called with the
          GNOME_CANVAS_UPDATE_VISIBILITY flag.

Notes:

	* gnome_canvas_group_child_bounds() is deprecated.  The
          ::update() method of canvas groups now rebuilds the group's
          bounding box as it calls the ::update() method of children
          that need it.  This keeps bounding boxes tight all the time,
          and removes the need for upwards propagation.

	* gnome_canvas_item_show() and hide() need to set the object
          GNOME_CANVAS_ITEM_VISIBLE flag as appropriate, and queue an
          update with the GNOME_CANVAS_ITEM_NEED_VIS flag.  When the
          item's ::update() method is called, it will get a
          GNOME_CANVAS_UPDATE_VISIBILITY flag.  It should look at the
          object flags to see the new visibility state.

	* The bounding box of an item is stored in world coordinates
          and is aligned with the world coordinate axes.

	* The update cycle is not reentrant.  That is, the ::update()
          method of items should not emit signals that could cause the
          handlers to do something that would trigger an update
          request.