|
|
|
crcanvas: A GTK/Cairo Canvas Widget | |
|---|---|---|---|---|
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);
GObject +----CrItem +----CrPath +----CrInverse +----CrText +----CrPixbuf +----CrBlit
"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
"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
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.
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;
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.
|
The parent item. |
|
The type of item to create. |
|
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. |
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.
|
The parent item. |
|
The child item. |
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.
|
The parent canvas item. |
|
The child canvas item. |
void cr_item_move (CrItem *item, double dx, double dy);
Moves the item to a position relative to where it is now.
|
|
|
The distance in item units to move in the x direction. |
|
The distance in item units to move in the y direction. |
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.
|
The group holding the item. |
|
The item to move. |
|
Number positions to move by. Positive goes up. Negative goes down. |
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.
|
The group holding the item. |
|
The item to move. |
|
Absolute position. Positive is places from the bottom. Negative is places from the top. |
void cr_item_hide (CrItem *item);
Hides the item. If the item is a parent, then all children will be hidden as well.
|
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.
|
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.
|
|
Returns : |
The canvas item transformation 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.
|
|
Returns : |
The canvas item inverse transformation matrix. |
void cr_item_cancel_matrix (CrItem *item);
Removes any transformations from this canvas item and request an update if necessary.
|
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.
|
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.
|
|
|
Leftmost edge of the bounding box (return value). |
|
Upper edge of the bounding box (return value). |
|
Rightmost edge of the bounding box (return value). |
|
Lower edge of the bounding box (return value). |
Returns : |
FALSE if the bounds are not available for this item.
|
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.
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.
|
|
|
Bounding box in item coordinates. |
|
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.
|
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.
|
|
|
cairo context to paint with. |
|
|
|
Left coord of the rectangle to be painted in pre-item units. |
|
Top coord of the rectangle to be painted in pre-item units. |
|
Right coord of the rectangle to be painted in pre-item units. |
|
Bottom coordinate of the rectangle to be painted in pre-item units. |
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.
|
|
|
The cairo context with its transformation matrix set to reflect all transformations higher in the item tree. |
|
The point to be tested in device coordinates. |
|
The point to be tested in device coordinates. |
Returns : |
The first canvas item in the z-order to test TRUE. |
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.
|
|
|
A cairo_matrix_t that should be set to identity at the start of the search. |
|
The item to be found. |
Returns : |
TRUE if the item was found. |
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.
|
|
|
The cairo context transformed to be relative to the device coordinates for this item. |
|
Used to tell children to re-report theit 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.
|
|
|
The cairo context transformed to be relative to the device coordinates for this item. |
|
Used to tell children to re-report theit bounds. |
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.
|
|
|
The event with coordinates in device units |
|
The cumulative matrix from device to this 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. |
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. |
"avoid-test" property"avoid-test" gboolean : Read / Write
Prevents item and children from being cursor tested.
Default value: FALSE
"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
"visible" property"visible" gboolean : Read / Write
Whether the item is visible.
Default value: TRUE
"x" property"x" gdouble : Read / Write
The matrix translation in the x direction in item units.
Default value: 0
"y" property"y" gdouble : Read / Write
The matrix translation in the y direction in item units.
Default value: 0
"added" signalvoid user_function (CrItem *critem, CrItem *arg1, gpointer user_data) : Run First
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |
"calculate-bounds" signalgboolean 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.
|
|
|
Cairo context with transformation set to match the current item. |
|
Bounding box in item coordinates. |
|
A structure for specifying device coordinate boundaries (if any) |
|
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.
|
"event" signalgboolean 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.
|
|
|
Gdk Event structure with coordinates in item units. |
|
Use this only if you want to get back to device coordinates. |
|
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 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.
|
"invalidate" signalvoid 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.
|
|
|
Some combination of INVALIDATE_OLD, INVALIDATE_NEW, and INVALIDATE_UPDATE |
|
Leftmost bound. |
|
Rightmost bound. |
|
Rightmost bound. |
|
Bottommost bound. |
|
A structure for specifying device coordinate boundaries (if any). |
|
user data set when the signal handler was connected. |
"paint" signalvoid 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.
|
|
|
The cairo context used to draw the item. |
|
user data set when the signal handler was connected. |
"removed" signalvoid user_function (CrItem *critem, CrItem *arg1, gpointer user_data) : Run First
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |
"request-update" signalvoid user_function (CrItem *critem, gpointer user_data) : Run Last
|
the object which received the signal. |
|
user data set when the signal handler was connected. |
"test" signalCrItem* 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.
|
|
|
Cairo context with tranformation set to match the current item. |
|
The coordinate in the item's user space. |
|
The coordinate in the item's user space. |
|
user data set when the signal handler was connected. |