| | | GNOME Canvas Library Reference Manual |
|---|
gnome-canvas-util — Canvas utility functions
#include <libgnomecanvas/libgnomecanvas.h> struct GnomeCanvasPoints; GnomeCanvasPoints* gnome_canvas_points_new (int num_points); GnomeCanvasPoints* gnome_canvas_points_ref (GnomeCanvasPoints *points); #define gnome_canvas_points_unref void gnome_canvas_points_free (GnomeCanvasPoints *points); int gnome_canvas_get_miter_points (double x1, double y1, double x2, double y2, double x3, double y3, double width, double *mx1, double *my1, double *mx2, double *my2); void gnome_canvas_get_butt_points (double x1, double y1, double x2, double y2, double width, int project, double *bx1, double *by1, double *bx2, double *by2); double gnome_canvas_polygon_to_point (double *poly, int num_points, double x, double y); void gnome_canvas_render_svp (GnomeCanvasBuf *buf, ArtSVP *svp, guint32 rgba); void gnome_canvas_update_svp (GnomeCanvas *canvas, ArtSVP **p_svp, ArtSVP *new_svp); void gnome_canvas_update_svp_clip (GnomeCanvas *canvas, ArtSVP **p_svp, ArtSVP *new_svp, ArtSVP *clip_svp); void gnome_canvas_item_reset_bounds (GnomeCanvasItem *item); void gnome_canvas_item_update_svp (GnomeCanvasItem *item, ArtSVP **p_svp, ArtSVP *new_svp); void gnome_canvas_item_update_svp_clip (GnomeCanvasItem *item, ArtSVP **p_svp, ArtSVP *new_svp, ArtSVP *clip_svp); void gnome_canvas_item_request_redraw_svp (GnomeCanvasItem *item, const ArtSVP *svp); void gnome_canvas_update_bbox (GnomeCanvasItem *item, int x1, int y1, int x2, int y2); void gnome_canvas_buf_ensure_buf (GnomeCanvasBuf *buf); ArtPathStrokeJoinType gnome_canvas_join_gdk_to_art (GdkJoinStyle gdk_join); ArtPathStrokeCapType gnome_canvas_cap_gdk_to_art (GdkCapStyle gdk_cap);
Some useful canvas utility functions.
The GnomeCanvasPoints structure manages an array of points (X and Y coordinates) and is used by GnomeCanvasLine and GnomeCanvasPolygon canvas items.
To create a GnomeCanvasPoints structure call gnome_canvas_points_new() and when finished using it call gnome_canvas_points_free().
Of note is that the GnomeCanvasPoints structure is actually managed by a reference count, so it won't be freed until this count reaches 0. To increment its reference count call gnome_canvas_points_ref() and to decrement it call gnome_canvas_points_unref().
struct GnomeCanvasPoints {
double *coords;
int num_points;
int ref_count;
};
A structure to manage an array of points (X and Y coordinates). The memory management of this structure is handled with functions below, but the point coordinates are meant to be written directly into the array pointed to by the coords field.
| double *coords | Array of coordinates (num_points * 2 in size), X coordinates are stored in the even-numbered indices, and Y coordinates are stored in the odd-numbered indices. |
| int num_points | Read-only - Number of points in this array. |
| int ref_count | Read-only - Count of references to this array of points |
GnomeCanvasPoints* gnome_canvas_points_new (int num_points);
Creates a structure that should be used to pass an array of points to items.
| num_points : | The number of points to allocate space for in the array. |
| Returns : | A newly-created array of points. It should be filled in by the user. |
GnomeCanvasPoints* gnome_canvas_points_ref (GnomeCanvasPoints *points);
Increases the reference count of the specified points structure.
| points : | A canvas points structure. |
| Returns : | The canvas points structure itself. |
#define gnome_canvas_points_unref
A synonym for gnome_canvas_points_free(). It decrements a GnomeCanvasPoints reference by 1 and frees it when there are no more references.
void gnome_canvas_points_free (GnomeCanvasPoints *points);
Decreases the reference count of the specified points structure. If it reaches zero, then the structure is freed.
| points : | A canvas points structure. |
int gnome_canvas_get_miter_points (double x1,
double y1,
double x2,
double y2,
double x3,
double y3,
double width,
double *mx1,
double *my1,
double *mx2,
double *my2);Given three points forming an angle, computes the coordinates of the inside and outside points of the mitered corner formed by a line of a given width at that angle.
| x1 : | X coordinate of the first point |
| y1 : | Y coordinate of the first point |
| x2 : | X coordinate of the second (angle) point |
| y2 : | Y coordinate of the second (angle) point |
| x3 : | X coordinate of the third point |
| y3 : | Y coordinate of the third point |
| width : | Width of the line |
| mx1 : | The X coordinate of the first miter point is returned here. |
| my1 : | The Y coordinate of the first miter point is returned here. |
| mx2 : | The X coordinate of the second miter point is returned here. |
| my2 : | The Y coordinate of the second miter point is returned here. |
| Returns : | FALSE if the angle is less than 11 degrees (this is the same threshold as X uses. If this occurs, the return points are not modified. Otherwise, returns TRUE. |
void gnome_canvas_get_butt_points (double x1,
double y1,
double x2,
double y2,
double width,
int project,
double *bx1,
double *by1,
double *bx2,
double *by2);Computes the butt points of a line segment.
| x1 : | X coordinate of first point in the line |
| y1 : | Y cooordinate of first point in the line |
| x2 : | X coordinate of second point (endpoint) of the line |
| y2 : | Y coordinate of second point (endpoint) of the line |
| width : | Width of the line |
| project : | Whether the butt points should project out by width/2 distance |
| bx1 : | X coordinate of first butt point is returned here |
| by1 : | Y coordinate of first butt point is returned here |
| bx2 : | X coordinate of second butt point is returned here |
| by2 : | Y coordinate of second butt point is returned here |
double gnome_canvas_polygon_to_point (double *poly,
int num_points,
double x,
double y);Computes the distance between a point and a polygon.
| poly : | Vertices of the polygon. X coordinates are in the even indices, and Y coordinates are in the odd indices |
| num_points : | Number of points in the polygon |
| x : | X coordinate of the point |
| y : | Y coordinate of the point |
| Returns : | The distance from the point to the polygon, or zero if the point is inside the polygon. |
void gnome_canvas_render_svp (GnomeCanvasBuf *buf, ArtSVP *svp, guint32 rgba);
Render the svp over the buf.
| buf : | the canvas buffer to render over |
| svp : | the vector path to render |
| rgba : | the rgba color to render |
void gnome_canvas_update_svp (GnomeCanvas *canvas, ArtSVP **p_svp, ArtSVP *new_svp);
Sets the svp to the new value, requesting repaint on what's changed. This function takes responsibility for freeing new_svp.
| canvas : | the canvas containing the svp that needs updating. |
| p_svp : | a pointer to the existing svp |
| new_svp : | the new svp |
void gnome_canvas_update_svp_clip (GnomeCanvas *canvas, ArtSVP **p_svp, ArtSVP *new_svp, ArtSVP *clip_svp);
Sets the svp to the new value, clipping if necessary, and requesting repaint on what's changed. This function takes responsibility for freeing new_svp.
| canvas : | the canvas containing the svp that needs updating. |
| p_svp : | a pointer to the existing svp |
| new_svp : | the new svp |
| clip_svp : | a clip path, if non-null |
void gnome_canvas_item_reset_bounds (GnomeCanvasItem *item);
Resets the bounding box of a canvas item to an empty rectangle.
| item : | A canvas item |
void gnome_canvas_item_update_svp (GnomeCanvasItem *item, ArtSVP **p_svp, ArtSVP *new_svp);
Sets the svp to the new value, requesting repaint on what's changed. This function takes responsibility for freeing new_svp. This routine also adds the svp's bbox to the item's.
| item : | the canvas item containing the svp that needs updating. |
| p_svp : | a pointer to the existing svp |
| new_svp : | the new svp |
void gnome_canvas_item_update_svp_clip
(GnomeCanvasItem *item,
ArtSVP **p_svp,
ArtSVP *new_svp,
ArtSVP *clip_svp);Sets the svp to the new value, clipping if necessary, and requesting repaint on what's changed. This function takes responsibility for freeing new_svp.
| item : | the canvas item containing the svp that needs updating. |
| p_svp : | a pointer to the existing svp |
| new_svp : | the new svp |
| clip_svp : | a clip path, if non-null |
void gnome_canvas_item_request_redraw_svp
(GnomeCanvasItem *item,
const ArtSVP *svp);Request redraw of the svp if in aa mode, or the entire item in in xlib mode.
| item : | the item containing the svp |
| svp : | the svp that needs to be redrawn |
void gnome_canvas_update_bbox (GnomeCanvasItem *item, int x1, int y1, int x2, int y2);
Sets the bbox to the new value, requesting full repaint.
| item : | the canvas item needing update |
| x1 : | Left coordinate of the new bounding box |
| y1 : | Top coordinate of the new bounding box |
| x2 : | Right coordinate of the new bounding box |
| y2 : | Bottom coordinate of the new bounding box |
void gnome_canvas_buf_ensure_buf (GnomeCanvasBuf *buf);
Ensure that the buffer is in RGB format, suitable for compositing.
| buf : | the buf that needs to be represened in RGB format |
ArtPathStrokeJoinType gnome_canvas_join_gdk_to_art
(GdkJoinStyle gdk_join);Convert from GDK line join specifier to libart.
| gdk_join : | a join type, represented in GDK format |
| Returns : | The line join specifier in libart format. |
ArtPathStrokeCapType gnome_canvas_cap_gdk_to_art
(GdkCapStyle gdk_cap);Convert from GDK line cap specifier to libart.
| gdk_cap : | a cap type, represented in GDK format |
| Returns : | The line cap specifier in libart format. |
| << gnome-canvas-path-def |