<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="goocanvas-creating-items">
  <refmeta>
    <refentrytitle>Creating New Items</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>GOOCANVAS Library</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>Creating New Items</refname>
    <refpurpose>how to create new canvas items.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>How to Create New Canvas Items</title>
    <para>
    There are 3 ways to create new canvas items, listed here in increasing
    order of complexity:
    <itemizedlist>
    <listitem><para>
	<link linkend="creating-simple-subclass">
	Creating a simple subclass of GooCanvasItemSimple.</link>
    </para></listitem><listitem><para>
	<link linkend="creating-regular-subclass">
	Creating a regular subclass of GooCanvasItemSimple.</link>
    </para></listitem><listitem><para>
	<link linkend="implementing-interface">
	Implementing the GooCanvasItem interface.</link>
    </para></listitem>
    </itemizedlist>
    These will be discussed in turn below. (It is also possible to create
    new container items by subclassing #GooCanvasGroup, but that is not
    covered here.)
    </para>
    <para>
      The final part of this section covers
      <link linkend="creating-models">creating item models</link>.
    </para>

    <refsect2 id="creating-simple-subclass">
      <title>Creating a Simple Subclass of GooCanvasItemSimple</title>
      <para>
	For items that consist of a simple graphic element such
	as a line, rectangle or circle, it is possible to create a subclass
	of #GooCanvasItemSimple and override just one method,
	simple_create_path(). (This method is used for the #GooCanvasEllipse
	and #GooCanvasPath items.)
      </para>
      <para>
	The simple_create_path() method should create a path using the given
	cairo context. The path will be drawn using the stroke, fill and
	other painting properties from #GooCanvasItemSimple.
      </para>
      <para>
	This example shows the simple_create_path() method for a simple
	rectangular item, MyItem:
	<informalexample><programlisting>
  static void
  my_item_simple_create_path (GooCanvasItemSimple *simple,
                              cairo_t             *cr)
  {
    MyItem *item = (MyItem*) simple;

    cairo_rectangle (cr, item->x, item->y, item->width, item->height);
  }
	</programlisting></informalexample>
      </para>
      <para>
	Whenever the item is changed in some way it should call
	goo_canvas_item_simple_changed(), passing a boolean value indicating
	whether the item's bounds need to be recalculated or if it only needs
	to be repainted. The #GooCanvasItemSimple code will take care of
	updating the item and repainting the appropriate parts of the canvas.
      </para>
    </refsect2>

    <refsect2 id="creating-regular-subclass">
      <title>Creating a Regular Subclass of GooCanvasItemSimple</title>
      <para>
	Most items will need more than a simple line or rectangle, so they
	will need to create a subclass of #GooCanvasItemSimple and override
	three methods, simple_update(), simple_paint() and simple_is_item_at().
      </para>
      <para>
	The simple_update() method should compute the bounds of the item, in the
	item's coordinate space, and place them in the bounds member of
	#GooCanvasItemSimple-struct. Note that the cairo context passed to
	this function may have transformations applied to it, so
	cairo_identity_matrix() should be called before using it.
      </para>
      <para>
	The simple_paint() method should paint the item using the given cairo
	context. To use the stroke and fill properties from #GooCanvasItemSimple
	to paint parts of the item call goo_canvas_style_set_stroke_options()
	and goo_canvas_style_set_fill_options() before calling cairo_stroke()
	and cairo_fill(). (The item's style can be found in
	GOO_CANVAS_ITEM_SIMPLE (item)->simple_data->style).
      </para>
      <para>
	The simple_is_item_at() method should return %TRUE if the
	given coordinate (in the item's coordinate space) is inside the item.
	(The is_pointer_event argument can be ignored for most purposes since
	the #GooCanvasItemSimple code will take care of it.)
      </para>
      <para>
	This example code shows the simple_update(), simple_paint() and
	simple_is_item_at() methods for a rectangular item (the complete
	item's source code can be found in the GooCanvas demo directory, in
	demo-item.h and demo-item.c):
	<informalexample><programlisting>
  static void
  goo_demo_item_update  (GooCanvasItemSimple *simple,
                         cairo_t             *cr)
  {
    GooDemoItem *demo_item = (GooDemoItem*) simple;
  
    /&ast; Compute the new bounds. &ast;/
    simple-&gt;bounds.x1 = demo_item-&gt;x;
    simple-&gt;bounds.y1 = demo_item-&gt;y;
    simple-&gt;bounds.x2 = demo_item-&gt;x + demo_item-&gt;width;
    simple-&gt;bounds.y2 = demo_item-&gt;y + demo_item-&gt;height;
  }
  
  
  static void
  goo_demo_item_paint (GooCanvasItemSimple   *simple,
                       cairo_t               *cr,
                       const GooCanvasBounds *bounds)
  {
    GooDemoItem *demo_item = (GooDemoItem*) simple;
  
    cairo_move_to (cr, demo_item-&gt;x, demo_item-&gt;y);
    cairo_line_to (cr, demo_item-&gt;x, demo_item-&gt;y + demo_item-&gt;height);
    cairo_line_to (cr, demo_item-&gt;x + demo_item-&gt;width,
                   demo_item-&gt;y + demo_item-&gt;height);
    cairo_line_to (cr, demo_item-&gt;x + demo_item-&gt;width, demo_item-&gt;y);
    cairo_close_path (cr);
    goo_canvas_style_set_fill_options (simple-&gt;simple_data-&gt;style, cr);
    cairo_fill (cr);
  }
  
  
  static gboolean
  goo_demo_item_is_item_at (GooCanvasItemSimple *simple,
                            gdouble              x,
                            gdouble              y,
                            cairo_t             *cr,
                            gboolean             is_pointer_event)
  {
    GooDemoItem *demo_item = (GooDemoItem*) simple;
  
    if (x &lt; demo_item-&gt;x || (x &gt; demo_item-&gt;x + demo_item-&gt;width)
        || y &lt; demo_item-&gt;y || (y &gt; demo_item-&gt;y + demo_item-&gt;height))
      return FALSE;
  
    return TRUE;
  }
	</programlisting></informalexample>
      </para>
      <para>
	As with the simple #GooCanvasItemSimple subclass, the item should
	call goo_canvas_item_simple_changed() whenever it is changed, to
	ensure that the item's bounds are recomputed and it is repainted
	if necessary.
      </para>
    </refsect2>

    <refsect2 id="implementing-interface">
      <title>Implementing the GooCanvasItem Interface</title>
      <para>
	The most complicated way to create new canvas items is to implement
	the #GooCanvasItem interface directly. This should not be needed in
	most cases, but may be desired if the developer wants to avoid the
	memory and processor overheads associated with the #GooCanvasItemSimple
	class, or if the developer wants to turn an existing application object
	into a canvas item.
      </para>

      <para>
	At a minimum the canvas item must implement these 6 methods:
	<itemizedlist>
	  <listitem><para>
	      get_parent() - the item's parent should be returned.
	  </para></listitem><listitem><para>
	      set_parent() - the item's parent should be stored (though it
	      should not add a reference to the parent).
	  </para></listitem><listitem><para>
	      get_bounds() - returns the bounds of the item, in device space.
	      The item should ensure that the bounds are up-to-date before
	      returning them, calling goo_canvas_item_ensure_updated() if
	      necessary.
	  </para></listitem><listitem><para>
	      update() - if the item has been changed since the last update,
	      or if the entire_tree flag is %TRUE, the item's bounds should
	      be recomputed (in device space). It should also request a redraw
	      of the old bounds and the new bounds, so the display is updated
	      appropriately. The new bounds should be returned in the bounds
	      argument.
	  </para></listitem><listitem><para>
	      paint() - if the item's bounds intersect the given bounds then
	      the item should be painted on the given cairo context.
	      The scale parameter is only used to check if the item should be
	      visible, according to the item's #GooCanvasItem:visibility and
	      #GooCanvasItem:visibility-threshold property settings.
	  </para></listitem><listitem><para>
	      get_items_at() - if the given point is inside the item then
	      a pointer to the item should be added to the start of the list
	      of found items. The list is then returned.
	  </para></listitem>
	</itemizedlist>
      </para>

      <para>
	The canvas item must also implement the
	#GooCanvasItem:parent, #GooCanvasItem:title,
	#GooCanvasItem:description,
	#GooCanvasItem:visibility, #GooCanvasItem:visibility-threshold,
	#GooCanvasItem:transform and #GooCanvasItem:pointer-events properties.
	(The last 4 properties can simply be ignored if the application
	doesn't intend to use them.)
      </para>

      <para>
	If the canvas item will be used within a container that does item
	layout, such as #GooCanvasTable, it must implement the first two
	methods here at least:
	<itemizedlist>
	  <listitem><para>
	      get_requested_area() - returns the requested area of the item,
	      in the parent's coordinate space.
	  </para></listitem><listitem><para>
	      allocate_area() - allocates the item's area, in the parent's
	      coordinate space.
	  </para></listitem><listitem><para>
	      get_requested_height() - returns the requested height of the
	      item, given a particular allocated width, in the parent's
	      coordinate space. (This only needed for items that change height
	      as their width is changed, such as text items.)
	  </para></listitem>
	</itemizedlist>
      </para>

      <para>
	If the canvas item supports a transformation matrix it must implement:
	<itemizedlist>
	  <listitem><para>
	      get_transform() - returns the item's transformation matrix.
	  </para></listitem><listitem><para>
	      set_transform() - sets the item's transformation matrix.
	  </para></listitem>
	</itemizedlist>
      </para>

      <para>
	If the canvas item supports a #GooCanvasStyle setting, it must
	implement:
	<itemizedlist>
	  <listitem><para>
	      get_style() - returns the item's style.
	  </para></listitem><listitem><para>
	      set_style() - sets the item's style.
	  </para></listitem>
	</itemizedlist>
      </para>

      <para>
	Since #GooCanvasItemSimple implements most of the above methods and
	properties its source code is a good place to look for help.
      </para>
    </refsect2>

    <refsect2 id="creating-item-models">
      <title>Creating Item Models</title>
      <para>
	As with creating canvas items, to create item models it
	is possible to subclass #GooCanvasItemModelSimple or to
	implement the #GooCanvasItemModel interface directly.
      </para>
      <para>
	Subclassing #GooCanvasItemModelSimple is very easy, since only one
	method from the #GooCanvasItemModel interface must be implemented -
	create_item(). This should return a new canvas item for viewing the
	item model in a canvas. (It may be called multiple times if multiple
	canvases are viewing the same canvas model.)
      </para>
      <para>
	The #GooCanvasItemModelSimple subclass should emit the "changed"
	signal whenever it has changed, with a boolean flag indicating if
	the bounds need to be recomputed. The canvas items will connect to
	this signal and request an update or a redraw as appropriate.
      </para>
      <para>
	To implement the #GooCanvasItemModel interface directly, the class
	must implement the get_parent(), set_parent() and create_item()
	methods. It may also implement get_transform(), set_transform(),
	get_style() and set_style() methods if desired.
      </para>
      <para>
	The class must also implement the
	#GooCanvasItemModel:parent, #GooCanvasItemModel:title,
	#GooCanvasItemModel:description, #GooCanvasItemModel:can-focus,
	#GooCanvasItemModel:visibility,
	#GooCanvasItemModel:visibility-threshold,
	#GooCanvasItemModel:transform and #GooCanvasItemModel:pointer-events
	properties.
	(The last 4 properties can simply be ignored if the application
	doesn't intend to use them.)
      </para>
    </refsect2>

  </refsect1>
</refentry>