<!-- ##### SECTION Title ##### -->
MateCanvasItem

<!-- ##### SECTION Short_Description ##### -->
Base class for all canvas items

<!-- ##### SECTION Long_Description ##### -->
<para>
This is the base class for all canvas items. Canvas items are the drawing
elements of a #MateCanvas. Example items include lines,
ellipses, polygons, images, text, curves and even arbitrary GTK+ widgets.
</para>

<para>
Canvas items use the GObject property system to query and set parameters.
Properties are inherited so, for example, a #MateCanvasPolygon has
a "fill-color" property that is inherited from its parent class object
#MateCanvasShape. So be sure to check the parent classes of #MateCanvasItem
objects when looking for item properties. More information on GObject
properties can be found in the glib library GObject API reference
documentation.
</para>

<para>
To create a new canvas item call mate_canvas_item_new() which takes a
parent #MateCanvasGroup, GType of the item to create, and a NULL terminated
list of name/value GObject properties to set for the new item.
</para>

<para>
To change an existing canvas item's properties call mate_canvas_item_set(),
or g_object_set() can also be used.
</para>

<para>
There are several functions to change the drawing stacking order of an item.
Call mate_canvas_item_raise() to raise an item a specified number of
positions or mate_canvas_item_lower() to lower it. To raise an item to the
top call mate_canvas_item_raise_to_top(). The
mate_canvas_item_lower_to_bottom() function will put it at the bottom.
</para>

<para>
To show an item call mate_canvas_item_show(). Note that canvas item's are
shown by default and so do not need to be explicitly shown after creation
(contrary to GTK+ widget behavior). Call mate_canvas_item_hide() to hide an
item.
</para>

<para>
To move an item relative to its current position (item coordinates) call
mate_canvas_item_move() or mate_canvas_item_affine_relative() for more
complex transforms. mate_canvas_item_affine_absolute() can be used to
set an item's transform to specific values (not offsets).
</para>

<para>
To convert between world and item coordinate systems call
mate_canvas_item_w2i(), and to convert in the other direction call
mate_canvas_item_i2w(). To get the transform for converting from item
to world coordinates use mate_canvas_item_i2w_affine() or for converting
item to canvas coordinates, mate_canvas_item_i2c_affine().
</para>

<para>
Handling user input for interactive items is accomplished through a
few functions and the "event" signal. To grab the mouse cursor call
mate_canvas_item_grab(), it can be ungrabbed with
mate_canvas_item_ungrab() (see gdk_pointer_grab() of the GTK+ library
for details). To grab keyboard focus call
mate_canvas_item_grab_focus().  Received events will be signaled via
the "event" signal.
</para>

<para>
Some other useful functions include a reparenting routine,
mate_canvas_item_reparent(), and a function to query the bounding
box of an item (a minumum rectangular area containing all parts of the item),
mate_canvas_item_get_bounds().
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### STRUCT MateCanvasItem ##### -->
<para>
This structure should not be accessed directly. Use the object's properties
and functions for querying or changing its parameters.
</para>


<!-- ##### SIGNAL MateCanvasItem::event ##### -->
<para>
Signals mouse button clicks, motion, enter/leave, and key press events
on canvas items. Use this signal to create user interactive items.
The <structfield>x</structfield> and <structfield>y</structfield>
coordinates of the @event structure have been converted to canvas world
coordinates.
</para>

@canvasitem: the object which received the signal.
@event: A GdkEvent structure containing the event that occurred.
@Returns: Signal handlers should return %TRUE to stop signal emission or %FALSE
to allow other signal handlers to process this event.

<!-- ##### ARG MateCanvasItem:parent ##### -->
<para>
Parent #MateCanvasGroup that contains the item.
</para>

<!-- ##### STRUCT MateCanvasItemClass ##### -->
<para>
The internals of this class structure are of interest to those creating
objects derived from #MateCanvasItem.
</para>

@parent_class: Parent derived class.
@update: Update method called to tell the item to update itself.
@realize: Realize an item (create graphics contexts, etc).
@unrealize: Unrealize an item.
@map: Map an item - normally only needed by items with their own GdkWindows.
@unmap: Unmap an item.
@coverage: Return the microtile coverage of the item.
@draw: Draw an item of this type.
@render: Render the item for anti-aliased canvases.
@point: Calculate the distance from an item to a point.
@bounds: Fetch the item's bounding box (rectangular area it occupies).
@event: The class signal method for the "event" signal.
@spare_vmethods: Reserved.

<!-- ##### FUNCTION mate_canvas_item_new ##### -->
<para>

</para>

@parent: 
@type: 
@first_arg_name: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION mate_canvas_item_construct ##### -->
<para>

</para>

@item: 
@parent: 
@first_arg_name: 
@args: 


<!-- ##### FUNCTION mate_canvas_item_set ##### -->
<para>

</para>

@item: 
@first_arg_name: 
@Varargs: 


<!-- ##### FUNCTION mate_canvas_item_set_valist ##### -->
<para>

</para>

@item: 
@first_arg_name: 
@args: 


<!-- ##### FUNCTION mate_canvas_item_move ##### -->
<para>

</para>

@item: 
@dx: 
@dy: 


<!-- ##### FUNCTION mate_canvas_item_affine_relative ##### -->
<para>

</para>

@item: 
@affine: 


<!-- ##### FUNCTION mate_canvas_item_affine_absolute ##### -->
<para>

</para>

@item: 
@affine: 


<!-- ##### FUNCTION mate_canvas_item_raise ##### -->
<para>

</para>

@item: 
@positions: 


<!-- ##### FUNCTION mate_canvas_item_lower ##### -->
<para>

</para>

@item: 
@positions: 


<!-- ##### FUNCTION mate_canvas_item_raise_to_top ##### -->
<para>

</para>

@item: 


<!-- ##### FUNCTION mate_canvas_item_lower_to_bottom ##### -->
<para>

</para>

@item: 


<!-- ##### FUNCTION mate_canvas_item_show ##### -->
<para>

</para>

@item: 


<!-- ##### FUNCTION mate_canvas_item_hide ##### -->
<para>

</para>

@item: 


<!-- ##### FUNCTION mate_canvas_item_grab ##### -->
<para>

</para>

@item: 
@event_mask: 
@cursor: 
@etime: 
@Returns: 


<!-- ##### FUNCTION mate_canvas_item_ungrab ##### -->
<para>

</para>

@item: 
@etime: 


<!-- ##### FUNCTION mate_canvas_item_w2i ##### -->
<para>

</para>

@item: 
@x: 
@y: 


<!-- ##### FUNCTION mate_canvas_item_i2w ##### -->
<para>

</para>

@item: 
@x: 
@y: 


<!-- ##### FUNCTION mate_canvas_item_i2w_affine ##### -->
<para>

</para>

@item: 
@affine: 


<!-- ##### FUNCTION mate_canvas_item_i2c_affine ##### -->
<para>

</para>

@item: 
@affine: 


<!-- ##### FUNCTION mate_canvas_item_reparent ##### -->
<para>

</para>

@item: 
@new_group: 


<!-- ##### FUNCTION mate_canvas_item_grab_focus ##### -->
<para>

</para>

@item: 


<!-- ##### FUNCTION mate_canvas_item_get_bounds ##### -->
<para>

</para>

@item: 
@x1: 
@y1: 
@x2: 
@y2: 


<!-- ##### FUNCTION mate_canvas_item_request_update ##### -->
<para>

</para>

@item: 


