|  |  |  | GNOME Canvas Library Reference Manual | 
|---|
| gnome-canvas-utilgnome-canvas-util — Canvas utility functions | 
#include <libgnomecanvas/libgnomecanvas.h>
            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().
typedef struct {
	double *coords;
	int num_points;
	int ref_count;
} GnomeCanvasPoints;
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 |