CrItem

CrItem — The base class for all canvas items and groups.

Synopsis

                    CrItem;
CrItem*             cr_item_new                         (CrItem *parent,
                                                         GType type,
                                                         const gchar *first_arg_name,
                                                         ...);
void                cr_item_add                         (CrItem *item,
                                                         CrItem *child);
void                cr_item_remove                      (CrItem *item,
                                                         CrItem *child);
void                cr_item_move                        (CrItem *item,
                                                         double dx,
                                                         double dy);
void                cr_item_set_z_relative              (CrItem *item,
                                                         CrItem *child,
                                                         int positions);
void                cr_item_set_z                       (CrItem *item,
                                                         CrItem *child,
                                                         int position);
void                cr_item_hide                        (CrItem *item);
void                cr_item_show                        (CrItem *item);
cairo_matrix_t*     cr_item_get_matrix                  (CrItem *item);
cairo_matrix_t*     cr_item_get_inverse_matrix          (CrItem *item);
void                cr_item_cancel_matrix               (CrItem *item);
void                cr_item_request_update              (CrItem *item);
gboolean            cr_item_get_bounds                  (CrItem *item,
                                                         double *x1,
                                                         double *y1,
                                                         double *x2,
                                                         double *y2);
gboolean            cr_item_get_device_bounds           (CrItem *item,
                                                         CrDeviceBounds *device);
gboolean            cr_item_calculate_bounds            (CrItem *item,
                                                         CrBounds *bounds,
                                                         CrDeviceBounds *device_bounds);
void                cr_item_invoke_paint                (CrItem *item,
                                                         cairo_t *ct,
                                                         gboolean all,
                                                         double x1,
                                                         double y1,
                                                         double x2,
                                                         double y2);
CrItem*             cr_item_invoke_test                 (CrItem *item,
                                                         cairo_t *c,
                                                         double x,
                                                         double y);
gboolean            cr_item_find_child                  (CrItem *item,
                                                         cairo_matrix_t *matrix,
                                                         CrItem *child);
void                cr_item_report_old_bounds           (CrItem *item,
                                                         cairo_t *ct,
                                                         gboolean all);
void                cr_item_report_new_bounds           (CrItem *item,
                                                         cairo_t *ct,
                                                         gboolean all);
gboolean            cr_item_invoke_event                (CrItem *item,
                                                         GdkEvent *event,
                                                         cairo_matrix_t *matrix,
                                                         CrItem *pick_item);
CrContext*          cr_item_make_temp_cairo             (void);

Object Hierarchy

  GObject
   +----CrItem
         +----CrPath
         +----CrInverse
         +----CrText
         +----CrPixbuf
         +----CrBlit

Properties

  "avoid-test"               gboolean              : Read / Write
  "matrix"                   CrMatrix*             : Read / Write
  "test-rectangle"           gboolean              : Read / Write
  "visible"                  gboolean              : Read / Write
  "x"                        gdouble               : Read / Write
  "y"                        gdouble               : Read / Write

Signals

  "added"                                          : Run First
  "calculate-bounds"                               : Run Last
  "event"                                          : Run Last
  "invalidate"                                     : Run Last
  "paint"                                          : Run Last
  "removed"                                        : Run First
  "request-update"                                 : Run Last
  "test"                                           : Run Last

Description

The base class for all canvas items. This class can be used as a painting object, or as a grouping object, or as both.

To use this as a painting object, connect to or redefine the "paint" and "calculate-bounds" signals.

To use it as a grouping object, call cr_item_add and cr_item_remove. To move the group around, make changes to its matrix (cr_item_get_matrix) and call cr_item_request_update.

Details

CrItem

typedef struct {
        /*
         * The list of child items may be accessed for reading directly.
         * It should only be modified via the cr_item_add/remove methods.
         */
        GList *items;
        CrBounds *bounds;
        CrDeviceBounds *device;
        cairo_matrix_t *matrix, *matrix_i, *matrix_p;
        guint32 flags;
} CrItem;


cr_item_new ()

CrItem*             cr_item_new                         (CrItem *parent,
                                                         GType type,
                                                         const gchar *first_arg_name,
                                                         ...);

A factory method to create a new CrItem and add it to a group in one step.

parent :

The parent item.

type :

The type of item to create.

first_arg_name :

A list of object argument name/value pairs, NULL-terminated, used to configure the item.

... :

Returns :

The newly created item. You must call g_object_ref if you intend to use this reference outside the local scope.

cr_item_add ()

void                cr_item_add                         (CrItem *item,
                                                         CrItem *child);

The child item is added under management of the parent item such that the rendering (z-order) of the child will be more forward than the parent. The parent will add a reference to the child. The child can be unref'd by the user after adding.

item :

The parent item.

child :

The child item.

cr_item_remove ()

void                cr_item_remove                      (CrItem *item,
                                                         CrItem *child);

Removes and unref's child from the item's list or and sublist under item. The child need not be a direct descended of the parent item. This means you can call this function with the canvas root item if necessary. The tree will be searched until the child is found.

item :

The parent canvas item.

child :

The child canvas item.

cr_item_move ()

void                cr_item_move                        (CrItem *item,
                                                         double dx,
                                                         double dy);

Moves the item to a position relative to where it is now.

item :

dx :

The distance in item units to move in the x direction.

dy :

The distance in item units to move in the y direction.

cr_item_set_z_relative ()

void                cr_item_set_z_relative              (CrItem *item,
                                                         CrItem *child,
                                                         int positions);

Moves the child item in height relative to its siblings by the number of places given in positions.

item :

The group holding the item.

child :

The item to move.

positions :

Number positions to move by. Positive goes up. Negative goes down.

cr_item_set_z ()

void                cr_item_set_z                       (CrItem *item,
                                                         CrItem *child,
                                                         int position);

Sets the child item height relative to its siblings to be the absolute position given by position. Zero is the bottom, -1 is the top.

item :

The group holding the item.

child :

The item to move.

position :

Absolute position. Positive is places from the bottom. Negative is places from the top.

cr_item_hide ()

void                cr_item_hide                        (CrItem *item);

Hides the item. If the item is a parent, then all children will be hidden as well.

item :


cr_item_show ()

void                cr_item_show                        (CrItem *item);

Shows the item. If the item is a parent, then the children may or may not be shown depending on their visible property.

item :


cr_item_get_matrix ()

cairo_matrix_t*     cr_item_get_matrix                  (CrItem *item);

Creates an identity matrix if one does not exist. Otherwise returns the current matrix. If you modify the matrix in any way, you must call request_update in order to see the results.

item :

Returns :

The canvas item transformation matrix.

cr_item_get_inverse_matrix ()

cairo_matrix_t*     cr_item_get_inverse_matrix          (CrItem *item);

Creates an identity matrix if one does not exist. Otherwise returns the current inverse matrix. If you modify the matrix in any way, you must call request_update in order to see the results.

item :

Returns :

The canvas item inverse transformation matrix.

cr_item_cancel_matrix ()

void                cr_item_cancel_matrix               (CrItem *item);

Removes any transformations from this canvas item and request an update if necessary.

item :


cr_item_request_update ()

void                cr_item_request_update              (CrItem *item);

Propagates request up through the canvas item tree, to let the canvas know that a screen refresh is required.

item :


cr_item_get_bounds ()

gboolean            cr_item_get_bounds                  (CrItem *item,
                                                         double *x1,
                                                         double *y1,
                                                         double *x2,
                                                         double *y2);

The bounds are returned in the world coordinate system of item. Note that this routine will return the last set of bounds reported by the item during a canvas update. If no updates have occurred then FALSE is returned. Use cr_item_calculate_bounds if you need to know the bounds immediately.

item :

x1 :

Leftmost edge of the bounding box (return value).

y1 :

Upper edge of the bounding box (return value).

x2 :

Rightmost edge of the bounding box (return value).

y2 :

Lower edge of the bounding box (return value).

Returns :

FALSE if the bounds are not available for this item.

cr_item_get_device_bounds ()

gboolean            cr_item_get_device_bounds           (CrItem *item,
                                                         CrDeviceBounds *device);

The device bounds report any space the item uses that is device based. This space is anchored to the item bounds reported by cr_item_get_bounds. Note that this routine will return the last set of bounds reported by the item during a canvas update. If no updates have occurred then FALSE is returned. Use cr_item_calculate_bounds if you need to know the bounds immediately.

item :

device :

A structure representing the items device-based boundaries (if any). If this return returns TRUE, the structure will be filled with the item's device based boundaries.

Returns :

TRUE if this item has any device based space. FALSE if not.

cr_item_calculate_bounds ()

gboolean            cr_item_calculate_bounds            (CrItem *item,
                                                         CrBounds *bounds,
                                                         CrDeviceBounds *device_bounds);

Run the "calculate_bounds" bounds signal and virtual method on the item using a temporary cairo context and report the results. The results are not retained by this object. This function is provided as a user convenience and is not run as part of normal canvas operation. The reason a user might want to call this is to know the bounds in advance of the first canvas update. The cr_item_get_bounds and cr_item_get_device_bounds methods will return FALSE unless the canvas has been updated at least once. The disadvantage to using this is that in some extreme cases the bounds reported by a temporary cairo context may differ from the bounds reported by the cairo context being used by the canvas device. So this routine really will give only an approximation of what the bounds will be when the item is rendered to the screen.

item :

bounds :

Bounding box in item coordinates.

device_bounds :

A structure for specifying device coordinate boundaries (if any)

Returns :

TRUE if the the bounds are defined even if the are 0, 0, 0, 0.

cr_item_invoke_paint ()

void                cr_item_invoke_paint                (CrItem *item,
                                                         cairo_t *ct,
                                                         gboolean all,
                                                         double x1,
                                                         double y1,
                                                         double x2,
                                                         double y2);

This is normally called only by CrCanvas or CrItem.

item :

ct :

cairo context to paint with.

all :

x1 :

Left coord of the rectangle to be painted in pre-item units.

y1 :

Top coord of the rectangle to be painted in pre-item units.

x2 :

Right coord of the rectangle to be painted in pre-item units.

y2 :

Bottom coordinate of the rectangle to be painted in pre-item units.

cr_item_invoke_test ()

CrItem*             cr_item_invoke_test                 (CrItem *item,
                                                         cairo_t *c,
                                                         double x,
                                                         double y);

This is normally called only by CrCanvas or CrItem. It is used to run the test method or emit a test signal on the derived canvas items.

item :

c :

The cairo context with its transformation matrix set to reflect all transformations higher in the item tree.

x :

The point to be tested in device coordinates.

y :

The point to be tested in device coordinates.

Returns :

The first canvas item in the z-order to test TRUE.

cr_item_find_child ()

gboolean            cr_item_find_child                  (CrItem *item,
                                                         cairo_matrix_t *matrix,
                                                         CrItem *child);

An Internal method. This will search the item tree for a child item that was previously found using invoke_test. When the item is found the cairo matrix will be set to reflect the transformation between this item and the found item.

item :

matrix :

A cairo_matrix_t that should be set to identity at the start of the search.

child :

The item to be found.

Returns :

TRUE if the item was found.

cr_item_report_old_bounds ()

void                cr_item_report_old_bounds           (CrItem *item,
                                                         cairo_t *ct,
                                                         gboolean all);

This is normally called only by the canvas widget or canvas item. It is used to report back invalidated regions to the canvas or device.

item :

ct :

The cairo context transformed to be relative to the device coordinates for this item.

all :

Used to tell children to re-report theit bounds.

cr_item_report_new_bounds ()

void                cr_item_report_new_bounds           (CrItem *item,
                                                         cairo_t *ct,
                                                         gboolean all);

This is normally called only by the canvas widget or canvas item. It is used to trigger calculate_bounds in derived canvas items and to report back invalidated regions to the canvas or device.

item :

ct :

The cairo context transformed to be relative to the device coordinates for this item.

all :

Used to tell children to re-report theit bounds.

cr_item_invoke_event ()

gboolean            cr_item_invoke_event                (CrItem *item,
                                                         GdkEvent *event,
                                                         cairo_matrix_t *matrix,
                                                         CrItem *pick_item);

This is normally called only by the device. It is used to trigger the derived canvas item 'event' signal.

item :

event :

The event with coordinates in device units

matrix :

The cumulative matrix from device to this item.

pick_item :

The item the cursor is on. This may be different from item if the event is caught on a non-leaf node.

Returns :

TRUE to stop propagation of the event. FALSE to continue.

cr_item_make_temp_cairo ()

CrContext*          cr_item_make_temp_cairo             (void);

A convenience procedure used by some implementations to create a path. In order to use this, the scale must set the scale to be roughly "ball-park" to the scale where the canvas item will be painted.

Returns :

A cairo context. Call cairo_destroy on this reference when finished.

Property Details

The "avoid-test" property

  "avoid-test"               gboolean              : Read / Write

Prevents item and children from being cursor tested.

Default value: FALSE


The "matrix" property

  "matrix"                   CrMatrix*             : Read / Write

Cairo matrix used to transform this item.


The "test-rectangle" property

  "test-rectangle"           gboolean              : Read / Write

If the point test routine should ignore any details about the item and just test the enclosing rectangle. For CrPath based items the test-fill property may be more appropriate.

Default value: FALSE


The "visible" property

  "visible"                  gboolean              : Read / Write

Whether the item is visible.

Default value: TRUE


The "x" property

  "x"                        gdouble               : Read / Write

The matrix translation in the x direction in item units.

Default value: 0


The "y" property

  "y"                        gdouble               : Read / Write

The matrix translation in the y direction in item units.

Default value: 0

Signal Details

The "added" signal

void                user_function                      (CrItem  *critem,
                                                        CrItem  *arg1,
                                                        gpointer user_data)      : Run First

critem :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "calculate-bounds" signal

gboolean            user_function                      (CrItem         *item,
                                                        CrContext      *c,
                                                        CrBounds       *bounds,
                                                        CrDeviceBounds *device,
                                                        gpointer        user_data)      : Run Last

Defining this method is optional but strongly recommended. If it is not provided, then the device (canvas widget) must be run in repaint mode or else this item won't be painted. In most cases the device can be ignored. If some portion of the item is tied to device space then the anchor should be filled to reflect what part of the item bounding box the device bounding box should be measured from. An anchor to a corner means the device space is measured from that corner. An anchor to a center means the device space is measured to either side of the item unit bounding box.

item :

c :

Cairo context with transformation set to match the current item.

bounds :

Bounding box in item coordinates.

device :

A structure for specifying device coordinate boundaries (if any)

user_data :

user data set when the signal handler was connected.

Returns :

TRUE if the the bounds are defined even if the are 0, 0, 0, 0. Any implementation of this method should always return TRUE.

The "event" signal

gboolean            user_function                      (CrItem   *item,
                                                        GdkEvent *event,
                                                        CrMatrix *matrix,
                                                        CrItem   *pick_item,
                                                        gpointer  user_data)      : Run Last

In most cases applications will connect to this signal. This method need only be defined if your canvas item has some type of pointer behavior. If test is not defined, this method will never be called.

Since release 0.11, the coordinates returned in the event structure represent the current user coordinates for the item being signaled. The typical way to use the event signal is to connect to the item which is to be manipulated. During the button press save initial event coordinates. During the motion event manipulate the item by comparing the event structure coordinates against the saved off initial coordinates.

item :

event :

Gdk Event structure with coordinates in item units.

matrix :

Use this only if you want to get back to device coordinates.

pick_item :

Actual item the cursor is on. The can sometimes be different from item if the event is caught on a non-leaf node.

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop the event. FALSE to allow the event to propagate to other items higher in the tree.

The "invalidate" signal

void                user_function                      (CrItem         *item,
                                                        gint            mask,
                                                        gdouble         x1,
                                                        gdouble         y1,
                                                        gdouble         x2,
                                                        gdouble         y2,
                                                        CrDeviceBounds *device,
                                                        gpointer        user_data)      : Run Last

This is an internal method. The invalidate signal is propagated up through the hierarchy so that multiple devices (canvases) may receive this signal in their respective coordinate systems. The anchor and device width and heights (if any) must be added when the invalidate signal reaches its final destination.

item :

mask :

Some combination of INVALIDATE_OLD, INVALIDATE_NEW, and INVALIDATE_UPDATE

x1 :

Leftmost bound.

y1 :

Rightmost bound.

x2 :

Rightmost bound.

y2 :

Bottommost bound.

device :

A structure for specifying device coordinate boundaries (if any).

user_data :

user data set when the signal handler was connected.

The "paint" signal

void                user_function                      (CrItem    *item,
                                                        CrContext *c,
                                                        gpointer   user_data)      : Run Last

Item implementations should override this and use it to draw to the cairo surface.

item :

c :

The cairo context used to draw the item.

user_data :

user data set when the signal handler was connected.

The "removed" signal

void                user_function                      (CrItem  *critem,
                                                        CrItem  *arg1,
                                                        gpointer user_data)      : Run First

critem :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "request-update" signal

void                user_function                      (CrItem  *critem,
                                                        gpointer user_data)      : Run Last

critem :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "test" signal

CrItem*             user_function                      (CrItem    *item,
                                                        CrContext *c,
                                                        gdouble    x,
                                                        gdouble    y,
                                                        gpointer   user_data)      : Run Last

This signal is optional. If you don't need interaction with the pointing device, then there is no need to provide it.

item :

c :

Cairo context with tranformation set to match the current item.

x :

The coordinate in the item's user space.

y :

The coordinate in the item's user space.

user_data :

user data set when the signal handler was connected.