"FUNCTION">gnome_canvas_item_new()</tt> creates a new          instance of the type with <tt class="FUNCTION">          gtk_type_new()</tt>, adds the item to its <span class=           "STRUCTNAME">GnomeCanvasGroup</span>, and schedules it to          be redrawn.        </p>        <p>          To destroy an item and remove it from the canvas, simply          call <tt class="FUNCTION">gtk_object_destroy()</tt>. You          can also use the standard reference counting mechanism          with canvas items.        </p>        <p>          You can set an item's affine using <tt class="FUNCTION">          gnome_canvas_item_affine_absolute()</tt>, or compose a          new affine with the item's existing affine using <tt          class="FUNCTION">          gnome_canvas_item_affine_relative()</tt>. These functions          can be used to translate, scale, or rotate a canvas item          (however, scaling and rotation only work in antialiased          mode).        </p>        <p>          Items in a group are normally stacked in the order you          add them, with the most recently-added item "on top" and          the oldest item on the bottom. You can manipulate the          stacking order with <tt class="FUNCTION">          gnome_canvas_item_raise()</tt> and <tt class="FUNCTION">          gnome_canvas_item_lower()</tt>. These move an item up or          down by the given number of positions. It is safe to pass          in a too-large value for <span class="STRUCTNAME">          positions</span>; the item will be moved as far as          possible and no more. You can also request that an item          is moved to one extreme or the other, using <tt class=           "FUNCTION">gnome_canvas_item_raise_to_top()</tt> and <tt          class="FUNCTION">gnome_canvas_item_lower_to_bottom</tt>.        </p>        <p>          Items can be shown and hidden; hidden items are not          rendered by the canvas and do not receive events. All          items are visible by default. The routines are <tt class=           "FUNCTION">gnome_canvas_item_show()</tt> and <tt class=           "FUNCTION">gnome_canvas_item_hide()</tt>.        </p>        <p>          Reparenting a canvas item is straightforward; the only          rule is that the new group must be on the same canvas as          the old group.        </p>        <p>          <tt class="FUNCTION">gnome_canvas_item_grab_focus()</tt>          is analagous to <tt class="FUNCTION">          gtk_widget_grab_focus()</tt>; it sends all key events to          the item with the grab. It also sends focus change events          to the item (when the item gains or loses the focus).        </p>        <p>          Canvas items can grab and ungrab the mouse pointer just          as a <span class="STRUCTNAME">GdkWindow</span> can; the          arguments to <tt class="FUNCTION">          gnome_canvas_item_grab()</tt> are exactly analagous to          those of <tt class="FUNCTION">gdk_pointer_grab()</tt>          (see <a href="cha-gdk.html">the chapter called <i>GDK          Basics</i></a>). While a canvas item has the pointer          grabbed, no other item receives events. Behind the          scenes, <tt class="CLASSNAME">GnomeCanvas</tt> uses <tt          class="FUNCTION">gdk_pointer_grab()</tt> to implement <tt          class="FUNCTION">gnome_canvas_item_grab()</tt>, so an          item grabbing the mouse away from other items implies the          canvas grabbing the mouse away from other widgets.        </p>        <p>          The visual properties of canvas items are manipulated          almost entirely via object arguments. If you skipped <a          href="cha-objects.html">the chapter called <i>The GTK+          Object and Type System</i></a>, go back and read the          section on object arguments now. Two functions are used          to set canvas item properties: <tt class="FUNCTION">          gnome_canvas_item_set()</tt> and <tt class="FUNCTION">          gnome_canvas_item_setv()</tt>. These are almost but not          quite equivalent to <tt class="FUNCTION">          gtk_object_set()</tt> and <tt class="FUNCTION">          gtk_object_setv()</tt>---they set object arguments in the          same way, but they also mark the canvas item to be          redrawn. So you should prefer them to the <span class=           "STRUCTNAME">GtkObject</span> variants. (This is          something of a design bug, and future canvas versions          will most likely allow you to use <tt class="FUNCTION">          gtk_object_set()</tt>.)        </p>        <p>          <tt class="FUNCTION">          gnome_canvas_item_request_update()</tt> marks the canvas          item as "dirty" and queues it to be redrawn. Internally,          the canvas uses a one-shot idle function to perform          redraws; that is, it waits until no more GTK+ events are          pending, then redraws itself a single time. It does this          by installing an idle function with <tt class="FUNCTION">          gtk_idle_add()</tt> and removing it after it runs once.          Thus <tt class="FUNCTION">          gnome_canvas_item_request_update()</tt> can be called          many times without creating an efficiency problem---it          pretty much does nothing at all if an update is already          pending.        </p>        <div class="FIGURE">          <a name="FL-CANVASITEMS"></a>          <div class="FUNCSYNOPSIS">            <a name="FL-CANVASITEMS.SYNOPSIS"></a>            <table border="0" bgcolor="#E0E0E0" width="100%">              <tr>                <td><pre class="FUNCSYNOPSISINFO">       #include &lt;libgnomeui/gnome-canvas.h&gt;      </pre>                </td>              </tr>            </table>            <p>              <code><code class="FUNCDEF">GnomeCanvasItem* <tt              class="FUNCTION">              gnome_canvas_item_new</tt></code>(GnomeCanvasGroup*              <tt class="PARAMETER"><i>parent</i></tt>, GtkType <tt              class="PARAMETER"><i>type</i></tt>, const gchar* <tt              class="PARAMETER"><i>first_arg_name</i></tt>, <tt              class="PARAMETER"><i>...</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">GnomeCanvasItem* <tt              class="FUNCTION">              gnome_canvas_item_newv</tt></code>(GnomeCanvasGroup*              <tt class="PARAMETER"><i>parent</i></tt>, GtkType <tt              class="PARAMETER"><i>type</i></tt>, guint <tt class=               "PARAMETER"><i>nargs</i></tt>, GtkArg* <tt class=               "PARAMETER"><i>args</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_set</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, const gchar*              <tt class="PARAMETER"><i>first_arg_name</i></tt>, <tt              class="PARAMETER"><i>...</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_setv</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, guint <tt              class="PARAMETER"><i>nargs</i></tt>, GtkArg* <tt              class="PARAMETER"><i>args</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_affine_relative</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, const double              <tt class="PARAMETER"><i>affine[6]</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_affine_absolute</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, const double              <tt class="PARAMETER"><i>affine[6]</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_raise</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, int <tt              class="PARAMETER"><i>positions</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_lower</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, int <tt              class="PARAMETER"><i>positions</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_raise_to_top</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_lower_to_bottom</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_show</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_hide</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_reparent</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>,              GnomeCanvasGroup* <tt class="PARAMETER"><i>              new_group</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_grab_focus</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">int <tt class="FUNCTION">              gnome_canvas_item_grab</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, unsigned int              <tt class="PARAMETER"><i>event_mask</i></tt>,              GdkCursor* <tt class="PARAMETER"><i>cursor</i></tt>,              guint32 <tt class="PARAMETER"><i>              etime</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_ungrab</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, guint32 <tt              class="PARAMETER"><i>etime</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_get_bounds</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>, double* <tt              class="PARAMETER"><i>x1</i></tt>, double* <tt class=               "PARAMETER"><i>y1</i></tt>, double* <tt class=               "PARAMETER"><i>x2</i></tt>, double* <tt class=               "PARAMETER"><i>y2</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gnome_canvas_item_request_update</tt></code>(GnomeCanvasItem*              <tt class="PARAMETER"><i>item</i></tt>);</code>            </p>          </div>          <p>            <b>Figure 8. Using <span class="STRUCTNAME">            GnomeCanvasItem</span></b>          </p>        </div>      </div>      <div class="SECT2">        <h2 class="SECT2">          <a name="Z181">Canvas Items and Events</a>        </h2>        <p>          The standard Gnome canvas items have only one signal,          <span class="SYMBOL">"event"</span>, which is emitted for          <i class="EMPHASIS">all</i> types of event. The canvas          widget preprocesses all GDK events that it receives, and          forwards some of them to canvas items. It also sythesizes          certain events. Remember that X sends events only to X          windows (<span class="STRUCTNAME">GdkWindow</span>s), and          canvas items do not have an associated <span class=           "STRUCTNAME">GdkWindow</span>. Thus the canvas widget          must act as intermediary. Here are some of the actions it          takes:        </p>        <ul>          <li>            <p>              Coordinates are automatically converted to canvas              world coordinates. For example, if a canvas item              receives an event of type <span class="STRUCTNAME">              GDK_BUTTON_PRESS</span>, the <span class=              "STRUCTNAME">x</span> and <span class="STRUCTNAME">              y</span> fields of the event will be in world              coordinates. (The raw event was received on the              canvas's <span class="STRUCTNAME">GdkWindow</span>              and thus had window coordinates.)            </p>          </li>          <li>            <p>              Enter/leave events are synthesized for canvas items              as the mouse pointer moves across the canvas.            </p>          </li>          <li>            <p>              Events are propagated up the canvas item hierarchy,              until some item's <span class="SYMBOL">"event"</span>              signal handler returns <span class="STRUCTNAME">              TRUE</span>. This works just as it does with <tt              class="CLASSNAME">GtkWidget</tt>; events are first              sent to the bottommost or leaf canvas item, and              eventually make it up to the root item.            </p>          </li>          <li>            <p>              Only user-generated events are sent to canvas items;              many events you might expect to receive on a <span              class="STRUCTNAME">GdkWindow</span>, such as expose              and configure events, are not forwarded to canvas              items.            </p>          </li>        </ul>        <p>          The canvas does this work behind the scenes, so item          events work intuitively and much like normal GDK events.        </p>        <p>          A canvas item event callback looks like this:        </p>        <table border="0" bgcolor="#E0E0E0" width="100%">          <tr>            <td><pre class="PROGRAMLISTING">&#13;static gintitem_event_callback(GnomeCanvasItem* item,                     GdkEvent* event,                     gpointer data){  switch (event-&gt;type) {    case GDK_BUTTON_PRESS:      break;    case GDK_MOTION_NOTIFY:      break;    case GDK_BUTTON_RELEASE:      break;    default:      break;  }  /* Returning FALSE propagates the event to parent items;   * returning TRUE ends event propagation.    */  return FALSE;}      </pre>            </td>