DiaCanvasItem

Name

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:

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

This function is used to update the object's internal state. It is called during idle time. A canvas item should try to do as much work as possible here and not in, for example, the event() handler or the handle_motion() callback.

gboolean    get_shape_iter                  (DiaCanvasItem *item,
                                             DiaCanvasIter *iter)
gboolean    shape_next                      (DiaCanvasItem *item,
                                             DiaCanvasIter *iter)
DiaShape*   shape_value                     (DiaCanvasItem *item,
                                             DiaCanvasIter *iter)

Iterate shapes that belong to a DiaCanvasItem. The caller should first call dia_canvas_item_get_shape_iter() to set the iterator to point to the first shape and call dia_canvas_item_shape_value() to retrieve the shape the iterator points to. Call dia_canvas_item_shape_next() to set the iterator to point to the next shape. FALSE is returned if there are no more shapes.

gdouble     point                           (DiaCanvasItem *item,
                                             gdouble x,
                                             gdouble y)

This function is used to determine the precise distance from point (x, y) to the closest point on the object. The distance to the object is returned.

void        move                            (DiaCanvasItem *item,
                                             gdouble dx,
                                             gdouble dy)

Move the object. This function usually doesn't need to be overwritten. This function is used to move the object. Moving is assigned a special callback, since is it common practice for programs to allow movement of multiple objects at one.

void        handle_motion                   (DiaCanvasItem *item,
                                             DiaHandle *handle,
                                             gdouble *wx,
                                             gdouble *wy,
                                             DiaEventMask mask)

If a handle is moved this function is called before doing the actual movement. Point (wx, wy) is the handles new position in world (canvas) relative coordinates. This function is allowed to change the values. For example, if a handle may only be moved horizontal you could set wy to zero. Mask is the button mask that is used during the move (for example DiaCanvasElement also uses this function to rotate the object).

void        glue                            (DiaCanvasItem *item,
                                             DiaHandle *handle,
                                             gdouble *wx,
                                             gdouble *wy)

If a handle is near an object, that object is asked if it wants to connect the handle. Gluing is the first step: the item calculates the point where the handle should connect and the distance between the handles current position and the connection point is returned. Once the handle is released (the mouse button is released) the handle will request a connection to the item by calling dia_canvas_item_connect(), which will emit the connect() signal. Handle is the handle that wants to connect. (wx, wy) is the point where the cursor is currently (in world coordinates). The object should determine the position where the handle could connect and place it's coordinates in (wx, wy). Just like the point() callback, the distance from the point to the connection point (the new (wx, wy)) is returned.

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)

Set a complete transformation matrix at once.

"connect" (DiaHandle : Write)

Connect a handle to the item.

"disconnect" (DiaHandle : Write)

Disconnect a handle from the item.

"handles" (DiaCanvasItemHandles : Read / Write)

Get a list of all handles held by the item.

"parent" (DiaCanvasItem : Read / Write)

Set the parent object.

"visible" (gboolean : Read / Write)

Set the item visible or invisible. Invisible objects are not drawn on the canvas and can not receive events.

Signals

The "connect" signal

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

This signal is emitted if a handle is connected to item. note that item is the object the handle is connected to, not the handles owner!

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);

If a handle no longer wants to be connected to the item, this signal is emitted.

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);

An event is emitted.

diacanvasitem :

the object which received the signal.

arg1 :

the event of type DiaEvent.

user_data :

user data set when the signal handler was connected.

Returns :

TRUE if the event is handled, FALSE otherwise


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);

This signal is mainly used to inform view items that they need to update.

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);

This signal is emitted to notify the view items that the Z order has changed.

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.