z177.html

gtk_text program sample&eg

          "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 gint
item_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>