DiaCanvasItem

DiaCanvasItem — Base class for objects placed in a DiaCanvas.

Synopsis




#define     DIA_CANVAS_ITEM                 (obj)
struct      DiaCanvasItem;
enum        DiaCanvasItemFlags;
DiaCanvasItem* dia_canvas_item_create       (GType type,
                                             const gchar *first_arg_name,
                                             ...);
void        dia_canvas_item_request_update  (DiaCanvasItem *item);
void        dia_canvas_item_update_now      (DiaCanvasItem *item);
void        dia_canvas_item_update_child    (DiaCanvasItem *item,
                                             DiaCanvasItem *child,
                                             gdouble affine[6]);
void        dia_canvas_item_affine_w2i      (DiaCanvasItem *item,
                                             gdouble affine[6]);
void        dia_canvas_item_affine_i2w      (DiaCanvasItem *item,
                                             gdouble affine[6]);
void        dia_canvas_item_affine_point_i2w
                                            (DiaCanvasItem *item,
                                             gdouble *x,
                                             gdouble *y);
void        dia_canvas_item_affine_point_w2i
                                            (DiaCanvasItem *item,
                                             gdouble *x,
                                             gdouble *y);
void        dia_canvas_item_select          (DiaCanvasItem *item);
void        dia_canvas_item_unselect        (DiaCanvasItem *item);
void        dia_canvas_item_focus           (DiaCanvasItem *item);
void        dia_canvas_item_unfocus         (DiaCanvasItem *item);
void        dia_canvas_item_grab            (DiaCanvasItem *item);
void        dia_canvas_item_ungrab          (DiaCanvasItem *item);
void        dia_canvas_item_visible         (DiaCanvasItem *item);
void        dia_canvas_item_invisible       (DiaCanvasItem *item);
void        dia_canvas_item_identity        (DiaCanvasItem *item);
void        dia_canvas_item_scale           (DiaCanvasItem *item,
                                             gdouble sx,
                                             gdouble sy);
void        dia_canvas_item_rotate          (DiaCanvasItem *item,
                                             gdouble degrees);
void        dia_canvas_item_shear_x         (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy);
void        dia_canvas_item_shear_y         (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy);
void        dia_canvas_item_move            (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy);
void        dia_canvas_item_move_interactive
                                            (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy);
void        dia_canvas_item_flip            (DiaCanvasItem *item,
                                             gboolean horz,
                                             gboolean vert);
void        dia_canvas_item_expand_bounds   (DiaCanvasItem *item,
                                             gdouble d);
gboolean    dia_canvas_item_get_shape_iter  (DiaCanvasItem *item,
                                             DiaCanvasIter *iter);
gboolean    dia_canvas_item_shape_next      (DiaCanvasItem *item,
                                             DiaCanvasIter *iter);
DiaShape*   dia_canvas_item_shape_value     (DiaCanvasItem *item,
                                             DiaCanvasIter *iter);
gboolean    dia_canvas_item_connect         (DiaCanvasItem *item,
                                             DiaHandle *handle);
gboolean    dia_canvas_item_disconnect      (DiaCanvasItem *item,
                                             DiaHandle *handle);
gboolean    dia_canvas_item_disconnect_handles
                                            (DiaCanvasItem *item);
void        dia_canvas_item_bb_affine       (DiaCanvasItem *item,
                                             gdouble affine[6],
                                             gdouble *x1,
                                             gdouble *y1,
                                             gdouble *x2,
                                             gdouble *y2);
void        dia_canvas_item_update_handles_i2w
                                            (DiaCanvasItem *item);
void        dia_canvas_item_update_handles_w2i
                                            (DiaCanvasItem *item);
void        dia_canvas_item_preserve_property
                                            (DiaCanvasItem *item,
                                             const gchar *property_name);
#define     DIA_CANVAS_ITEM_VISIBLE         (obj)
#define     DIA_CANVAS_ITEM_NEED_UPDATE     (obj)
#define     DIA_CANVAS_ITEM_FOCUS           (obj)
#define     DIA_CANVAS_ITEM_GRAB            (obj)
#define     DIA_CANVAS_ITEM_SELECT          (obj)

Object Hierarchy


  GObject
   +----DiaCanvasItem

Properties


  "affine"               DiaCanvasItemAffine  : Read / Write
  "connect"              DiaHandle            : Write
  "disconnect"           DiaHandle            : Write
  "handles"              DiaCanvasItemHandles : Read / Write
  "parent"               DiaCanvasItem        : Read / Write
  "visible"              gboolean             : Read / Write

Signal Prototypes


"connect"   gboolean    user_function      (DiaCanvasItem *diacanvasitem,
                                            DiaHandle *arg1,
                                            gpointer user_data);
"disconnect"
            gboolean    user_function      (DiaCanvasItem *diacanvasitem,
                                            DiaHandle *arg1,
                                            gpointer user_data);
"event"     gboolean    user_function      (DiaCanvasItem *diacanvasitem,
                                            gpointer arg1,
                                            gpointer user_data);
"move"      void        user_function      (DiaCanvasItem *diacanvasitem,
                                            gdouble arg1,
                                            gdouble arg2,
                                            gboolean arg3,
                                            gpointer user_data);
"need-update"
            void        user_function      (DiaCanvasItem *diacanvasitem,
                                            gpointer user_data);
"state-changed"
            void        user_function      (DiaCanvasItem *diacanvasitem,
                                            gint arg1,
                                            gpointer user_data);
"z-order"   void        user_function      (DiaCanvasItem *diacanvasitem,
                                            gint arg1,
                                            gpointer user_data);

Description

DiaCanvasItem is the base class for all objects added to a DiaCanvas. For those of you who know the GnomeCanvasItem: it's quite similar. This class defines a list of handles on the object, a list of shapes and a transformation matrix. The handles are used to modify the item (e.g. resize or rotate). The shapes define what the object looks like.

To make custom behavior possible a few callback functions are defined in the DiaCanvasItemClass:

Details

DIA_CANVAS_ITEM()

#define DIA_CANVAS_ITEM(obj)		(G_TYPE_CHECK_INSTANCE_CAST ((obj), DIA_TYPE_CANVAS_ITEM, DiaCanvasItem))

obj :

struct DiaCanvasItem

struct DiaCanvasItem;

DiaCanvasItem is the base class for all objects that are displayed in a DiaCanvasView. DiaCanvasItems are held by a DiaCanvas. Since a DiaCanvas can have more than one view, every view holds some custom information in a DiaCanvasViewItem. If a DiaCanvasView is provided with a DiaHandleLayer, the canvas is able to view the handle and sent events to the handles.


enum DiaCanvasItemFlags

typedef enum {
	DIA_VISIBLE	= 1,
	DIA_INTERACTIVE = 1 << 1,
	DIA_COMPOSITE	= 1 << 2,
	DIA_NEED_UPDATE	= 1 << 3,
	DIA_UPDATE_ALL	= 1 << 4,
	DIA_SELECT	= 1 << 8,
	DIA_FOCUS	= 1 << 9,
	DIA_GRAB	= 1 << 10
} DiaCanvasItemFlags;

Flags that can be set on a DiaCanvasItem.

DIA_VISIBLE If true, the item is visible. (default=TRUE)
DIA_INTERACTIVE If true, the item has interactive capabilities (it can handle events). (Default=TRUE).
DIA_COMPOSITE The item is an aggregate of it's parent. This means that if the item is selected or gets the focus, the parent will act and draw as if it was selected itself. (Default=FALSE)
DIA_NEED_UPDATE The item's update method should be executed. This flag is set by dia_canvas_item_request_update(). It should not be set in the constructor.
DIA_UPDATE_ALL Tell that all child objects (if any) have been requesting an update. This flag is used to optimize update requests.
DIA_SELECT The canvas is selected. This flag is set before the event handler is called. This flag is view specific. Note that a DiaCanvasItem is stateless, so you can not rely on this flag (nor DIA_FOCUS or DIA_GRAB) outside the event handler.
DIA_FOCUS The item has the focus. Same constraints as DIA_SELECT.
DIA_GRAB The item grabs all events. Same constraints as DIA_SELECT.

dia_canvas_item_create ()

DiaCanvasItem* dia_canvas_item_create       (GType type,
                                             const gchar *first_arg_name,
                                             ...);

Create a new canvas item. You can assign addional properties to the item.

type : Type of the new item, should be a DiaCanvasItem child.
first_arg_name :
... :
Returns : A newly created canvas item.

dia_canvas_item_request_update ()

void        dia_canvas_item_request_update  (DiaCanvasItem *item);

Schedule an update for the item. If the item has children, they are scheduled for an update too.

item : item that needs an update

dia_canvas_item_update_now ()

void        dia_canvas_item_update_now      (DiaCanvasItem *item);

Force an update of the item.

item : Item to update

dia_canvas_item_update_child ()

void        dia_canvas_item_update_child    (DiaCanvasItem *item,
                                             DiaCanvasItem *child,
                                             gdouble affine[6]);

This function can be used in the item's update to trigger updates of a subitem (child).

item : Canvas item
child : Canvas item, a child of item
affine : transformation matrix of item

dia_canvas_item_affine_w2i ()

void        dia_canvas_item_affine_w2i      (DiaCanvasItem *item,
                                             gdouble affine[6]);

Return the affine transformation needed to convert world coordinates to item relative coordinates.

item :
affine : OUT

dia_canvas_item_affine_i2w ()

void        dia_canvas_item_affine_i2w      (DiaCanvasItem *item,
                                             gdouble affine[6]);

Calculate the affine transformation that is nessesary to convert a point from item coordinates to world coordinates.

item :
affine : OUT

dia_canvas_item_affine_point_i2w ()

void        dia_canvas_item_affine_point_i2w
                                            (DiaCanvasItem *item,
                                             gdouble *x,
                                             gdouble *y);

Convert a point (x, y) from item to world coordinates.

item :
x :
y :

dia_canvas_item_affine_point_w2i ()

void        dia_canvas_item_affine_point_w2i
                                            (DiaCanvasItem *item,
                                             gdouble *x,
                                             gdouble *y);

Convert a point (x, y) from world coordinates to item relative coordinates.

item :
x :
y :

dia_canvas_item_select ()

void        dia_canvas_item_select          (DiaCanvasItem *item);

Select item. More than one item can be selected (usualy by holding the SHIFT or CONTROL button while selecting an item). The root item can not be selected.

item :

dia_canvas_item_unselect ()

void        dia_canvas_item_unselect        (DiaCanvasItem *item);

Unselect item.

item :

dia_canvas_item_focus ()

void        dia_canvas_item_focus           (DiaCanvasItem *item);

item becomes the focused item. A focused item is also selected, but it has the privilege of being the last object that was selected.

item :

dia_canvas_item_unfocus ()

void        dia_canvas_item_unfocus         (DiaCanvasItem *item);

Unfocus the focused object.

item :

dia_canvas_item_grab ()

void        dia_canvas_item_grab            (DiaCanvasItem *item);

Make item the grabbed item. The grabbed item is also selected and also has the focus. A grabbed item will recieve all events send to the canvas, even if the event is not even near item.

item :

dia_canvas_item_ungrab ()

void        dia_canvas_item_ungrab          (DiaCanvasItem *item);

Ungrab the item. Inverse of dia_canvas_grab().

item :

dia_canvas_item_visible ()

void        dia_canvas_item_visible         (DiaCanvasItem *item);

Make item visible.

item :

dia_canvas_item_invisible ()

void        dia_canvas_item_invisible       (DiaCanvasItem *item);

Make item invisible.

item :

dia_canvas_item_identity ()

void        dia_canvas_item_identity        (DiaCanvasItem *item);

Remove all transformations from item.

item :

dia_canvas_item_scale ()

void        dia_canvas_item_scale           (DiaCanvasItem *item,
                                             gdouble sx,
                                             gdouble sy);

Scale the object. The objects center of its bounding box will not move.

item :
sx :
sy :

dia_canvas_item_rotate ()

void        dia_canvas_item_rotate          (DiaCanvasItem *item,
                                             gdouble degrees);

Rotate item around the center of its bounding box.

item :
degrees :

dia_canvas_item_shear_x ()

void        dia_canvas_item_shear_x         (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy);

Shear the object.

item :
dx :
dy :

dia_canvas_item_shear_y ()

void        dia_canvas_item_shear_y         (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy);

Like dia_canvas_item_shear_x(), but now for the y axis.

item :
dx :
dy :

dia_canvas_item_move ()

void        dia_canvas_item_move            (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy);

Move item. Use dia_canvas_item_move_interactive() in event handlers.

item :
dx :
dy :

dia_canvas_item_move_interactive ()

void        dia_canvas_item_move_interactive
                                            (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy);

Move item. This function raises the DiaCanvas::move signal, which is caught by the active DiaCanvasView. The view will request all selected objects to move.

This function should be used in event handlers.

item :
dx :
dy :

dia_canvas_item_flip ()

void        dia_canvas_item_flip            (DiaCanvasItem *item,
                                             gboolean horz,
                                             gboolean vert);

Flip item around its horizontal and/or vertical axis.

item :
horz :
vert :

dia_canvas_item_expand_bounds ()

void        dia_canvas_item_expand_bounds   (DiaCanvasItem *item,
                                             gdouble d);

Expand the bounding box of item in all four directions. This is convenient if you have drawn a shape that comes out of the bounding box a little bit.

item :
d : number to expand the bounding box with

dia_canvas_item_get_shape_iter ()

gboolean    dia_canvas_item_get_shape_iter  (DiaCanvasItem *item,
                                             DiaCanvasIter *iter);

item :
iter :
Returns : The first shape to be drawn.

dia_canvas_item_shape_next ()

gboolean    dia_canvas_item_shape_next      (DiaCanvasItem *item,
                                             DiaCanvasIter *iter);

item :
iter :
Returns :

dia_canvas_item_shape_value ()

DiaShape*   dia_canvas_item_shape_value     (DiaCanvasItem *item,
                                             DiaCanvasIter *iter);

item :
iter :
Returns : The value that corresponds with the values of the iterator.

dia_canvas_item_connect ()

gboolean    dia_canvas_item_connect         (DiaCanvasItem *item,
                                             DiaHandle *handle);

Connect handle to item. Item should not be the owner of handle. If the "connect" signal returns FALSE, the object will not be connected.

During the connection process, a position for handle is calculated and the handle is moved to that position (so it is not nessesary to do a glue() before connecting).

item :
handle :
Returns : TRUE on success, FALSE otherwise.

dia_canvas_item_disconnect ()

gboolean    dia_canvas_item_disconnect      (DiaCanvasItem *item,
                                             DiaHandle *handle);

Disconnect handle from item. handle->connected_to should be the same object as item.

item : item the handle is connected too.
handle : handle to be disconnected from item.
Returns : TRUE on success, FALSE of failure.

dia_canvas_item_disconnect_handles ()

gboolean    dia_canvas_item_disconnect_handles
                                            (DiaCanvasItem *item);

Disconnect all handles of item. Note that this function disconnects all handles that belong to item, while dia_canvas_item_disconnect() disconnects a handle that is connected to an item!

item :
Returns : TRUE if no handles are connected, FALSE otherwise.

dia_canvas_item_bb_affine ()

void        dia_canvas_item_bb_affine       (DiaCanvasItem *item,
                                             gdouble affine[6],
                                             gdouble *x1,
                                             gdouble *y1,
                                             gdouble *x2,
                                             gdouble *y2);

Calculate the bounding box of item after a affine transformation.

item :
affine :
x1 : OUT
y1 : OUT
x2 : OUT
y2 : OUT

dia_canvas_item_update_handles_i2w ()

void        dia_canvas_item_update_handles_i2w
                                            (DiaCanvasItem *item);

Sync the world coordinates and the item coordinates for all handles of item.

item :

dia_canvas_item_update_handles_w2i ()

void        dia_canvas_item_update_handles_w2i
                                            (DiaCanvasItem *item);

Sync all handles item coordinates to their world coordinates.

item :

dia_canvas_item_preserve_property ()

void        dia_canvas_item_preserve_property
                                            (DiaCanvasItem *item,
                                             const gchar *property_name);

Shorthand for dia_canvas_preserve_property(). It adds a property to the canvas' undo stack.

item :
property_name :

DIA_CANVAS_ITEM_VISIBLE()

#define DIA_CANVAS_ITEM_VISIBLE(obj) ((DIA_CANVAS_ITEM_FLAGS (obj) & DIA_VISIBLE) != 0)

obj :

DIA_CANVAS_ITEM_NEED_UPDATE()

#define DIA_CANVAS_ITEM_NEED_UPDATE(obj) ((DIA_CANVAS_ITEM_FLAGS (obj) & DIA_NEED_UPDATE) != 0)

obj :

DIA_CANVAS_ITEM_FOCUS()

#define DIA_CANVAS_ITEM_FOCUS(obj) ((DIA_CANVAS_ITEM_FLAGS (obj) & DIA_FOCUS) != 0)

obj :

DIA_CANVAS_ITEM_GRAB()

#define DIA_CANVAS_ITEM_GRAB(obj) ((DIA_CANVAS_ITEM_FLAGS (obj) & DIA_GRAB) != 0)

obj :

DIA_CANVAS_ITEM_SELECT()

#define DIA_CANVAS_ITEM_SELECT(obj) ((DIA_CANVAS_ITEM_FLAGS (obj) & DIA_SELECT) != 0)

obj :

Properties

"affine" (DiaCanvasItemAffine : Read / Write)

"connect" (DiaHandle : Write)

"disconnect" (DiaHandle : Write)

"handles" (DiaCanvasItemHandles : Read / Write)

"parent" (DiaCanvasItem : Read / Write)

"visible" (gboolean : Read / Write)

Signals

The "connect" signal

gboolean    user_function                  (DiaCanvasItem *diacanvasitem,
                                            DiaHandle *arg1,
                                            gpointer user_data);

diacanvasitem :the object which received the signal.
arg1 :
user_data :user data set when the signal handler was connected.
Returns :

The "disconnect" signal

gboolean    user_function                  (DiaCanvasItem *diacanvasitem,
                                            DiaHandle *arg1,
                                            gpointer user_data);

diacanvasitem :the object which received the signal.
arg1 :
user_data :user data set when the signal handler was connected.
Returns :

The "event" signal

gboolean    user_function                  (DiaCanvasItem *diacanvasitem,
                                            gpointer arg1,
                                            gpointer user_data);

diacanvasitem :the object which received the signal.
arg1 :
user_data :user data set when the signal handler was connected.
Returns :

The "move" signal

void        user_function                  (DiaCanvasItem *diacanvasitem,
                                            gdouble arg1,
                                            gdouble arg2,
                                            gboolean arg3,
                                            gpointer user_data);

diacanvasitem :the object which received the signal.
arg1 :
arg2 :
arg3 :
user_data :user data set when the signal handler was connected.

The "need-update" signal

void        user_function                  (DiaCanvasItem *diacanvasitem,
                                            gpointer user_data);

diacanvasitem :the object which received the signal.
user_data :user data set when the signal handler was connected.

The "state-changed" signal

void        user_function                  (DiaCanvasItem *diacanvasitem,
                                            gint arg1,
                                            gpointer user_data);

diacanvasitem :the object which received the signal.
arg1 :
user_data :user data set when the signal handler was connected.

The "z-order" signal

void        user_function                  (DiaCanvasItem *diacanvasitem,
                                            gint arg1,
                                            gpointer user_data);

diacanvasitem :the object which received the signal.
arg1 :
user_data :user data set when the signal handler was connected.

See Also

DiaCanvas, DiaHandle, DiaShape, DiaEvent.