mate-canvas-path-def

## mate-canvas-path-def mate-canvas-path-def — Container and functions for manipulating ArtBpaths |

## Synopsis

    #include <libmatecanvas/libmatecanvas.h>

                        MateCanvasPathDef;
    MateCanvasPathDef *  mate_canvas_path_def_new         (void);
    MateCanvasPathDef *  mate_canvas_path_def_new_sized   (gint length);
    MateCanvasPathDef *  mate_canvas_path_def_new_from_bpath
                                                            (ArtBpath *bpath);
    MateCanvasPathDef *  mate_canvas_path_def_new_from_static_bpath
                                                            (ArtBpath *bpath);
    MateCanvasPathDef *  mate_canvas_path_def_new_from_foreign_bpath
                                                            (ArtBpath *bpath);
    void                mate_canvas_path_def_ref           (MateCanvasPathDef *path);
    void                mate_canvas_path_def_finish        (MateCanvasPathDef *path);
    void                mate_canvas_path_def_ensure_space  (MateCanvasPathDef *path,
                                                             gint space);
    void                mate_canvas_path_def_copy          (MateCanvasPathDef *dst,
                                                             const MateCanvasPathDef *src);
    MateCanvasPathDef *  mate_canvas_path_def_duplicate   (const MateCanvasPathDef *path);
    MateCanvasPathDef *  mate_canvas_path_def_concat      (const GSList *list);
    GSList *            mate_canvas_path_def_split         (const MateCanvasPathDef *path);
    MateCanvasPathDef *  mate_canvas_path_def_open_parts  (const MateCanvasPathDef *path);
    MateCanvasPathDef *  mate_canvas_path_def_closed_parts
                                                            (const MateCanvasPathDef *path);
    MateCanvasPathDef *  mate_canvas_path_def_close_all   (const MateCanvasPathDef *path);
    void                mate_canvas_path_def_unref         (MateCanvasPathDef *path);
    void                mate_canvas_path_def_reset         (MateCanvasPathDef *path);
    void                mate_canvas_path_def_moveto        (MateCanvasPathDef *path,
                                                             gdouble x,
                                                             gdouble y);
    void                mate_canvas_path_def_lineto        (MateCanvasPathDef *path,
                                                             gdouble x,
                                                             gdouble y);
    void                mate_canvas_path_def_lineto_moving (MateCanvasPathDef *path,
                                                             gdouble x,
                                                             gdouble y);
    void                mate_canvas_path_def_curveto       (MateCanvasPathDef *path,
                                                             gdouble x0,
                                                             gdouble y0,
                                                             gdouble x1,
                                                             gdouble y1,
                                                             gdouble x2,
                                                             gdouble y2);
    void                mate_canvas_path_def_closepath     (MateCanvasPathDef *path);
    void                mate_canvas_path_def_closepath_current
                                                            (MateCanvasPathDef *path);
    ArtBpath *          mate_canvas_path_def_bpath         (const MateCanvasPathDef *path);
    gint                mate_canvas_path_def_length        (const MateCanvasPathDef *path);
    gboolean            mate_canvas_path_def_is_empty      (const MateCanvasPathDef *path);
    gboolean            mate_canvas_path_def_has_currentpoint
                                                            (const MateCanvasPathDef *path);
    void                mate_canvas_path_def_currentpoint  (const MateCanvasPathDef *path,
                                                             ArtPoint *p);
    ArtBpath *          mate_canvas_path_def_last_bpath    (const MateCanvasPathDef *path);
    ArtBpath *          mate_canvas_path_def_first_bpath   (const MateCanvasPathDef *path);
    gboolean            mate_canvas_path_def_any_open      (const MateCanvasPathDef *path);
    gboolean            mate_canvas_path_def_all_open      (const MateCanvasPathDef *path);
    gboolean            mate_canvas_path_def_any_closed    (const MateCanvasPathDef *path);
    gboolean            mate_canvas_path_def_all_closed    (const MateCanvasPathDef *path);

## Description

Convenient container and functions for manipulating ArtBpaths, which are paths defined by line and curve segments.

## Details

### MateCanvasPathDef

    typedef struct _MateCanvasPathDef MateCanvasPathDef;

This structure should not be accessed directly. Use the functions defined below.

### mate_canvas_path_def_new ()

    MateCanvasPathDef *  mate_canvas_path_def_new         (void);

This function creates a new empty mate_canvas_path_def.

Returns : | the new canvas path definition.

### mate_canvas_path_def_new_sized ()

    MateCanvasPathDef *  mate_canvas_path_def_new_sized   (gint length);

This function creates a new mate_canvas_path_def with `length` number of points allocated. It is useful, if you know the exact number of points in path, so you can avoid automatic point array reallocation.

`length` : | number of points to allocate for the path
Returns : | the new canvas path definition

### mate_canvas_path_def_new_from_bpath ()

    MateCanvasPathDef *  mate_canvas_path_def_new_from_bpath
                                                            (ArtBpath *bpath);

This function constructs a new mate_canvas_path_def and uses the passed `bpath` as the contents. The passed bpath should not be static as the path definition is editable when constructed with this function. Also, passed bpath will be freed with art_free, if path is destroyed, so use it with caution. For constructing a mate_canvas_path_def from (non-modifiable) bpath use mate_canvas_path_def_new_from_static_bpath.

`bpath` : | libart bezier path
Returns : | the new canvas path definition that is populated with the passed bezier path, if the `bpath` is bad NULL is returned.

### mate_canvas_path_def_new_from_static_bpath ()

    MateCanvasPathDef *  mate_canvas_path_def_new_from_static_bpath
                                                            (ArtBpath *bpath);

This function constructs a new mate_canvas_path_def and references the passed `bpath` as its contents. The mate_canvas_path_def returned from this function is to be considered static and non-editable (meaning you cannot change the path from what you passed in `bpath`). The bpath will not be freed, if path will be destroyed, so use it with caution.

`bpath` : | libart bezier path
Returns : | the new canvas path definition that references the passed `bpath`, or if the path is bad NULL is returned.

### mate_canvas_path_def_new_from_foreign_bpath ()

    MateCanvasPathDef *  mate_canvas_path_def_new_from_foreign_bpath
                                                            (ArtBpath *bpath);

This function constructs a new mate_canvas_path_def and duplicates the contents of the passed `bpath` in the definition.

`bpath` : | libart bezier path
Returns : | the newly created mate_canvas_path_def or NULL if the path is invalid.

### mate_canvas_path_def_ref ()

    void                mate_canvas_path_def_ref           (MateCanvasPathDef *path);

Increment the reference count of the MateCanvasPathDef.

`path` : | a MateCanvasPathDef

### mate_canvas_path_def_finish ()

    void                mate_canvas_path_def_finish        (MateCanvasPathDef *path);

Trims dynamic point array to exact length of path.

`path` : | a MateCanvasPathDef

### mate_canvas_path_def_ensure_space ()

    void                mate_canvas_path_def_ensure_space  (MateCanvasPathDef *path,
                                                             gint space);

This function ensures that enough space for `space` points is allocated at the end of the path.

`path` : | a MateCanvasPathDef
`space` : | number of points to guarantee are allocated at the end of the path.

### mate_canvas_path_def_copy ()

    void                mate_canvas_path_def_copy          (MateCanvasPathDef *dst,
                                                             const MateCanvasPathDef *src);

This function copies the contents `src` to `dest`. The old `dest` path array is freed and `dest` is marked as non-static (editable), regardless of the status of `src`.

`dst` : | a MateCanvasPathDef where the contents of `src` will be stored.
`src` : | a MateCanvasPathDef whose contents will be copied it `src`.

### mate_canvas_path_def_duplicate ()

    MateCanvasPathDef *  mate_canvas_path_def_duplicate   (const MateCanvasPathDef *path);

This function duplicates the passed `path`. The new path is marked as non-static regardless of the state of original.

`path` : | a MateCanvasPathDef to duplicate
Returns : | a MateCanvasPathDef which is a duplicate of `path`.

### mate_canvas_path_def_concat ()

    MateCanvasPathDef *  mate_canvas_path_def_concat      (const GSList *list);

This function concatenates a list of MateCanvasPathDefs into one newly created MateCanvasPathDef.

`list` : | a GSList of MateCanvasPathDefs to concatenate into one new path.
Returns : | a new MateCanvasPathDef

### mate_canvas_path_def_split ()

    GSList *            mate_canvas_path_def_split         (const MateCanvasPathDef *path);

This function splits the passed `path` into a list of MateCanvasPathDefs which represent each segment of the origional path. The path is split when ever an ART_MOVETO or ART_MOVETO_OPEN is encountered. The closedness of resulting paths is set accordingly to closedness of corresponding segment.

`path` : | a MateCanvasPathDef
Returns : | a list of MateCanvasPathDef(s).

### mate_canvas_path_def_open_parts ()

    MateCanvasPathDef *  mate_canvas_path_def_open_parts  (const MateCanvasPathDef *path);

This function creates a new MateCanvasPathDef that contains all of the open segments on the passed `path`.

`path` : | a MateCanvasPathDef
Returns : | a new MateCanvasPathDef that contains all of the open segemtns in `path`.

### mate_canvas_path_def_closed_parts ()

    MateCanvasPathDef *  mate_canvas_path_def_closed_parts
                                                            (const MateCanvasPathDef *path);

This function returns a new MateCanvasPathDef that contains the all of close parts of passed `path`.

`path` : | a MateCanvasPathDef
Returns : | a new MateCanvasPathDef that contains all of the closed parts of passed `path`.

### mate_canvas_path_def_close_all ()

    MateCanvasPathDef *  mate_canvas_path_def_close_all   (const MateCanvasPathDef *path);

This function closes all of the open segments in the passed path and returns a new MateCanvasPathDef.

`path` : | a MateCanvasPathDef
Returns : | a MateCanvasPathDef that contains the contents of `path` but has modified the path is fully closed

### mate_canvas_path_def_unref ()

    void                mate_canvas_path_def_unref         (MateCanvasPathDef *path);

Decrease the reference count of the passed `path`. If the reference count is < 1 the path is deallocated.

`path` : | a MateCanvasPathDef

### mate_canvas_path_def_reset ()

    void                mate_canvas_path_def_reset         (MateCanvasPathDef *path);

This function clears the contents of the passed `path`.

`path` : | a MateCanvasPathDef

### mate_canvas_path_def_moveto ()

    void                mate_canvas_path_def_moveto        (MateCanvasPathDef *path,
                                                             gdouble x,
                                                             gdouble y);

This function adds starts new subpath on `path`, and sets its starting point to `x` and `y`. If current subpath is empty, it simply changes its starting coordinates to new values.

`path` : | a MateCanvasPathDef
`x` : | x coordinate
`y` : | y coordinate

### mate_canvas_path_def_lineto ()

    void                mate_canvas_path_def_lineto        (MateCanvasPathDef *path,
                                                             gdouble x,
                                                             gdouble y);

This function add a line segment to the passed `path` with the specified `x` and `y` coordinates.

`path` : | a MateCanvasPathDef
`x` : | x coordinate
`y` : | y coordinate

### mate_canvas_path_def_lineto_moving ()

    void                mate_canvas_path_def_lineto_moving (MateCanvasPathDef *path,
                                                             gdouble x,
                                                             gdouble y);

This functions adds a new line segment with loose endpoint to the path, or if endpoint is already loose, changes its coordinates to `x`, `y`. You can change the coordinates of loose endpoint as many times as you want, the last ones set will be fixed, if you continue line. This is useful for handling drawing with mouse.

`path` : | a MateCanvasPathDef
`x` : | x coordinate
`y` : | y coordinate

### mate_canvas_path_def_curveto ()

    void                mate_canvas_path_def_curveto       (MateCanvasPathDef *path,
                                                             gdouble x0,
                                                             gdouble y0,
                                                             gdouble x1,
                                                             gdouble y1,
                                                             gdouble x2,
                                                             gdouble y2);

This function adds a bezier curve segment to the path definition.

`path` : | a MateCanvasPathDef
`x0` : | first control point x coordinate
`y0` : | first control point y coordinate
`x1` : | second control point x coordinate
`y1` : | second control point y coordinate
`x2` : | end of curve x coordinate
`y2` : | end of curve y coordinate

### mate_canvas_path_def_closepath ()

    void                mate_canvas_path_def_closepath     (MateCanvasPathDef *path);

This function closes the last subpath of `path`, adding a ART_LINETO to subpath starting point, if needed and changing starting pathcode to ART_MOVETO

`path` : | a MateCanvasPathDef

### mate_canvas_path_def_closepath_current ()

    void                mate_canvas_path_def_closepath_current
                                                            (MateCanvasPathDef *path);

This function closes the last subpath by setting the coordinates of the endpoint of the last segment (line or curve) to starting point.

`path` : | a MateCanvasPathDef

### mate_canvas_path_def_bpath ()

    ArtBpath *          mate_canvas_path_def_bpath         (const MateCanvasPathDef *path);

This function returns a ArtBpath that consists of the path definition.

`path` : | a MateCanvasPathDef
Returns : | ArtBpath

### mate_canvas_path_def_length ()

    gint                mate_canvas_path_def_length        (const MateCanvasPathDef *path);

This function returns the length of the path definition. Not Euclidian length of the path but rather the number of points on the path.

`path` : | a MateCanvasPathDef
Returns : | integer, number of points on the path.

### mate_canvas_path_def_is_empty ()

    gboolean            mate_canvas_path_def_is_empty      (const MateCanvasPathDef *path);

This function is a boolean test to see if the path is empty, meaning containing no line segments.

`path` : | a MateCanvasPathDef
Returns : | boolean, indicating if the path is empty.

### mate_canvas_path_def_has_currentpoint ()

    gboolean            mate_canvas_path_def_has_currentpoint
                                                            (const MateCanvasPathDef *path);

This function is a boolean test checking to see if the path has a current point defined. Current point will be set by line operators, and cleared by closing subpath.

`path` : | a MateCanvasPathdef
Returns : | boolean, indicating if the path has a current point defined.

### mate_canvas_path_def_currentpoint ()

    void                mate_canvas_path_def_currentpoint  (const MateCanvasPathDef *path,
                                                             ArtPoint *p);

Stores the current point of the path definition in the passed ArtPoint `p`.

`path` : | a MateCanvasPathDef
`p` : | a ArtPoint where to store the current point

### mate_canvas_path_def_last_bpath ()

    ArtBpath *          mate_canvas_path_def_last_bpath    (const MateCanvasPathDef *path);

This function returns pointer to the last ArtBpath segment in the path definition.

`path` : | a MateCanvasPathDef
Returns : | ArtBpath, being the last segment in the path definition or null if no line segments have been defined.

### mate_canvas_path_def_first_bpath ()

    ArtBpath *          mate_canvas_path_def_first_bpath   (const MateCanvasPathDef *path);

This function returns the first ArtBpath point in the definition.

`path` : | a MateCanvasPathDef
Returns : | ArtBpath being the first point in the path definition or null if no points are defined

### mate_canvas_path_def_any_open ()

    gboolean            mate_canvas_path_def_any_open      (const MateCanvasPathDef *path);

This function returns a boolean value indicating if the path has any open segments.

`path` : | a MateCanvasPathDef
Returns : | boolean, indicating if the path has any open segments.

### mate_canvas_path_def_all_open ()

    gboolean            mate_canvas_path_def_all_open      (const MateCanvasPathDef *path);

This function returns a boolean value indicating if the path only contains open segments.

`path` : | a MateCanvasPathDef
Returns : | boolean, indicating if the path has all open segments.

### mate_canvas_path_def_any_closed ()

    gboolean            mate_canvas_path_def_any_closed    (const MateCanvasPathDef *path);

This function returns a boolean valid indicating if the path has any closed segements.

`path` : | a MateCanvasPathDef
Returns : | boolean, indicating if the path has any closed segments.

### mate_canvas_path_def_all_closed ()

    gboolean            mate_canvas_path_def_all_closed    (const MateCanvasPathDef *path);

This function returns a boolean value indicating if the path only contains closed segments.

`path` : | a MateCanvasPathDef
Returns : | boolean, indicating if the path has all closed segments.