template: LibGlabels 3.0 Reference Manual

## template template |

## Functions

lglTemplate * | lgl_template_new ()
lglTemplate * | lgl_template_new_from_equiv ()
lglTemplate * | lgl_template_dup ()
void | lgl_template_free ()
void | lgl_template_add_category ()
void | lgl_template_add_frame ()
gchar * | lgl_template_get_name ()
gboolean | lgl_template_do_templates_match ()
gboolean | lgl_template_does_brand_match ()
gboolean | lgl_template_does_page_size_match ()
gboolean | lgl_template_does_category_match ()
gboolean | lgl_template_are_templates_identical ()
lglTemplateFrame * | lgl_template_frame_rect_new ()
lglTemplateFrame * | lgl_template_frame_ellipse_new ()
lglTemplateFrame * | lgl_template_frame_round_new ()
lglTemplateFrame * | lgl_template_frame_cd_new ()
lglTemplateFrame * | lgl_template_frame_dup ()
void | lgl_template_frame_free ()
void | lgl_template_frame_add_layout ()
void | lgl_template_frame_add_markup ()
void | lgl_template_frame_get_size ()
gint | lgl_template_frame_get_n_labels ()
lglTemplateOrigin * | lgl_template_frame_get_origins ()
gchar * | lgl_template_frame_get_layout_description ()
gchar * | lgl_template_frame_get_size_description ()
lglTemplateLayout * | lgl_template_layout_new ()
lglTemplateLayout * | lgl_template_layout_dup ()
void | lgl_template_layout_free ()
lglTemplateMarkup * | lgl_template_markup_margin_new ()
lglTemplateMarkup * | lgl_template_markup_line_new ()
lglTemplateMarkup * | lgl_template_markup_circle_new ()
lglTemplateMarkup * | lgl_template_markup_rect_new ()
lglTemplateMarkup * | lgl_template_markup_ellipse_new ()
lglTemplateMarkup * | lgl_template_markup_dup ()
void | lgl_template_markup_free ()
void | lgl_template_print ()

## Types and Values

struct | lglTemplate
enum | lglTemplateFrameShape
union | lglTemplateFrame
struct | lglTemplateFrameAll
struct | lglTemplateFrameRect
struct | lglTemplateFrameEllipse
struct | lglTemplateFrameRound
struct | lglTemplateFrameCD
struct | lglTemplateLayout
enum | lglTemplateMarkupType
union | lglTemplateMarkup
struct | lglTemplateMarkupMargin
struct | lglTemplateMarkupLine
struct | lglTemplateMarkupCircle
struct | lglTemplateMarkupRect
struct | lglTemplateMarkupEllipse
struct | lglTemplateOrigin

## Includes

    #include <libglabels/lgl-template.h>

## Description

## Functions

### lgl_template_new ()

    lglTemplate *
    lgl_template_new (const gchar *brand,
                      const gchar *part,
                      const gchar *description,
                      const gchar *paper_id,
                      gdouble page_width,
                      gdouble page_height);

Create a new template structure, with the given top-level attributes. The created template will have no initial categories, or frames associated with it. See `lgl_template_add_category()` and `lgl_template_add_frame()` to add these.

#### Parameters

brand | Template brand |
part | Template part name/number |
description | Template descriptions |
paper_id | Page size id |
page_width | Page width in points, set to zero unless paper_id="Other" |
page_height | Page height in points, set to zero unless paper_id="Other" |

#### Returns

pointer to a newly allocated lglTemplate structure.

### lgl_template_new_from_equiv ()

    lglTemplate *
    lgl_template_new_from_equiv (const gchar *brand,
                                 const gchar *part,
                                 const gchar *equiv_part);

Create a new template structure based on an existing template. The created template will be a duplicate of the original template, except with the new part name/number.

#### Parameters

brand | Template brand |
part | Template part name/number |
equiv_part | Name of equivalent part to base template on |

#### Returns

pointer to a newly allocated lglTemplate structure.

### lgl_template_dup ()

    lglTemplate *
    lgl_template_dup (const lglTemplate *orig_template);

This function duplicates a template structure.

#### Parameters

orig_template | Template to duplicate. |

#### Returns

a newly allocated lglTemplate structure.

### lgl_template_free ()

    void
    lgl_template_free (lglTemplate *template);

This function frees all memory associated with given template structure.

#### Parameters

template | Template to free. |

### lgl_template_add_category ()

    void
    lgl_template_add_category (lglTemplate *template,
                               const gchar *category_id);

This function adds the given category ID to a templates category list.

#### Parameters

template | Pointer to template structure |
category_id | Category ID string |

### lgl_template_add_frame ()

    void
    lgl_template_add_frame (lglTemplate *template,
                            lglTemplateFrame *frame);

This function adds the given frame structure to the template. Once added, the frame structure belongs to the given template; do not attempt to free it.

Note: Currently glabels only supports a single frame per template.

#### Parameters

template | Pointer to template structure |
frame | Pointer to frame structure |

### lgl_template_get_name ()

    gchar *
    lgl_template_get_name (const lglTemplate *template);

This function returns the name of the given template. The name is the concetenation of the brand and part name/number.

#### Parameters

template | Pointer to template structure to test |

#### Returns

A pointer to a newly allocated name string. Should be freed with `g_free()`.

### lgl_template_do_templates_match ()

    gboolean
    lgl_template_do_templates_match (const lglTemplate *template1,
                                     const lglTemplate *template2);

This function tests if the given templates match. This is a simple test that only tests the brand and part name/number. It does not test if they are actually identical.

#### Parameters

template1 | Pointer to 1st template structure to test |
template2 | Pointer to 2nd template structure to test |

#### Returns

TRUE if the two templates match.

### lgl_template_does_brand_match ()

    gboolean
    lgl_template_does_brand_match (const lglTemplate *template,
                                   const gchar *brand);

This function tests if the brand of the template matches the given brand.

#### Parameters

template | Pointer to template structure to test |
brand | Brand string |

#### Returns

TRUE if the template matches the given brand.

### lgl_template_does_page_size_match ()

    gboolean
    lgl_template_does_page_size_match (const lglTemplate *template,
                                       const gchar *paper_id);

This function tests if the page size of the template matches the given ID.

#### Parameters

template | Pointer to template structure to test |
paper_id | Page size ID string |

#### Returns

TRUE if the template matches the given page size ID.

### lgl_template_does_category_match ()

    gboolean
    lgl_template_does_category_match (const lglTemplate *template,
                                      const gchar *category_id);

This function tests if the given template belongs to the given category ID.

#### Parameters

template | Pointer to template structure to test |
category_id | Category ID string |

#### Returns

TRUE if the template matches the given category ID.

### lgl_template_are_templates_identical ()

    gboolean
    lgl_template_are_templates_identical (const lglTemplate *template1,
                                          const lglTemplate *template2);

This function tests if the given templates have identical size and layout properties.

#### Parameters

template1 | Pointer to 1st template structure to test |
template2 | Pointer to 2nd template structure to test |

#### Returns

TRUE if the two templates are identical.

### lgl_template_frame_rect_new ()

    lglTemplateFrame *
    lgl_template_frame_rect_new (const gchar *id,
                                 gdouble w,
                                 gdouble h,
                                 gdouble r,
                                 gdouble x_waste,
                                 gdouble y_waste);

This function creates a new template frame for a rectangular label or card.

#### Parameters

id | ID of frame. (This should currently always be "0"). |
w | width of frame in points. |
h | height of frame in points. |
r | radius of rounded corners in points. (Should be 0 for square corners.) |
x_waste | Amount of overprint to allow in the horizontal direction. |
y_waste | Amount of overprint to allow in the vertical direction. |

#### Returns

Pointer to newly allocated lglTemplateFrame structure.

### lgl_template_frame_ellipse_new ()

    lglTemplateFrame *
    lgl_template_frame_ellipse_new (const gchar *id,
                                    gdouble w,
                                    gdouble h,
                                    gdouble waste);

This function creates a new template frame for an elliptical label or card.

#### Parameters

id | ID of frame. (This should currently always be "0"). |
w | width of frame in points. |
h | height of frame in points. |
waste | Amount of overprint to allow in points. |

#### Returns

Pointer to newly allocated lglTemplateFrame structure.

### lgl_template_frame_round_new ()

    lglTemplateFrame *
    lgl_template_frame_round_new (const gchar *id,
                                  gdouble r,
                                  gdouble waste);

This function creates a new template frame for a round label.

#### Parameters

id | ID of frame. (This should currently always be "0"). |
r | radius of label in points. |
waste | Amount of overprint to allow. |

#### Returns

Pointer to newly allocated lglTemplateFrame structure.

### lgl_template_frame_cd_new ()

    lglTemplateFrame *
    lgl_template_frame_cd_new (const gchar *id,
                               gdouble r1,
                               gdouble r2,
                               gdouble w,
                               gdouble h,
                               gdouble waste);

This function creates a new template frame for a CD/DVD label.

#### Parameters

id | ID of frame. (This should currently always be "0"). |
r1 | outer radius of label in points. |
r2 | radius of center hole in points. |
w | clip width of frame in points for business card CDs. Should be 0 for no clipping. |
h | clip height of frame in points for business card CDs. Should be 0 for no clipping. |
waste | Amount of overprint to allow. |

#### Returns

Pointer to newly allocated lglTemplateFrame structure.

### lgl_template_frame_dup ()

    lglTemplateFrame *
    lgl_template_frame_dup (const lglTemplateFrame *orig_frame);

This function duplicates a template frame structure.

#### Parameters

orig_frame | Frame to duplicate. |

#### Returns

a newly allocated lglTemplateFrame structure.

### lgl_template_frame_free ()

    void
    lgl_template_frame_free (lglTemplateFrame *frame);

This function frees all memory associated with given template frame structure.

#### Parameters

frame | Frame to free. |

### lgl_template_frame_add_layout ()

    void
    lgl_template_frame_add_layout (lglTemplateFrame *frame,
                                   lglTemplateLayout *layout);

This function adds a layout structure to the given template frame.

#### Parameters

frame | Pointer to template frame to add layout to. |
layout | Pointer to layout structure to add to frame. |

### lgl_template_frame_add_markup ()

    void
    lgl_template_frame_add_markup (lglTemplateFrame *frame,
                                   lglTemplateMarkup *markup);

This function adds a markup structure to the given template frame.

#### Parameters

frame | Pointer to template frame to add markup to. |
markup | Pointer to markup structure to add to frame. |

### lgl_template_frame_get_size ()

    void
    lgl_template_frame_get_size (const lglTemplateFrame *frame,
                                 gdouble *w,
                                 gdouble *h);

Get size (width and height) of given lglTemplateFrame in points.

#### Parameters

frame | lglTemplateFrame structure to query |
w | pointer to location to receive width of frame |
h | pointer to location to receive height of frame |

### lgl_template_frame_get_n_labels ()

    gint
    lgl_template_frame_get_n_labels (const lglTemplateFrame *frame);

Get total number of labels per sheet corresponding to the given frame.

#### Parameters

frame | lglTemplateFrame structure to query |

#### Returns

number of labels per sheet.

### lgl_template_frame_get_origins ()

    lglTemplateOrigin *
    lgl_template_frame_get_origins (const lglTemplateFrame *frame);

Get an array of label origins for the given frame. These origins represent the upper left hand corner of each label on a page corresponding to the given frame. The origins will be ordered geometrically left to right and then top to bottom. The array should be freed using `g_free()`.

#### Parameters

frame | lglTemplateFrame structure to query |

#### Returns

A newly allocated array of lglTemplateOrigin structures.

### lgl_template_frame_get_layout_description ()

    gchar *
    lgl_template_frame_get_layout_description
                                   (const lglTemplateFrame *frame);

Get a description of the label layout including number of labels per sheet.

#### Parameters

frame | lglTemplateFrame structure to query |

#### Returns

a newly allocation description string.

### lgl_template_frame_get_size_description ()

    gchar *
    lgl_template_frame_get_size_description
                                   (const lglTemplateFrame *frame,
                                    lglUnits units);

Get a description of the label size.

#### Parameters

frame | lglTemplateFrame structure to query |
units | lglUnits |

#### Returns

a newly allocation description string.

### lgl_template_layout_new ()

    lglTemplateLayout *
    lgl_template_layout_new (gint nx,
                             gint ny,
                             gdouble x0,
                             gdouble y0,
                             gdouble dx,
                             gdouble dy);

This function creates a new layout structure with the given parameters.

#### Parameters

nx | Number of labels across. |
ny | Number of labels down. |
x0 | X coordinate of the top-left corner of the top-left label in the layout in points. |
y0 | Y coordinate of the top-left corner of the top-left label in the layout in points. |
dx | Horizontal pitch in points. This is the distance from left-edge to left-edge. |
dy | Vertical pitch in points. This is the distance from top-edge to top-edge. |

#### Returns

a newly allocated lglTemplateLayout structure.

### lgl_template_layout_dup ()

    lglTemplateLayout *
    lgl_template_layout_dup (const lglTemplateLayout *orig_layout);

This function duplicates a template layout structure.

#### Parameters

orig_layout | Layout to duplicate. |

#### Returns

a newly allocated lglTemplateLayout structure.

### lgl_template_layout_free ()

    void
    lgl_template_layout_free (lglTemplateLayout *layout);

This function frees all memory associated with given template layout structure.

#### Parameters

layout | Layout to free. |

### lgl_template_markup_margin_new ()

    lglTemplateMarkup *
    lgl_template_markup_margin_new (gdouble size);

This function creates a new margin markup structure.

#### Parameters

size | margin size in points. |

#### Returns

a newly allocated lglTemplateMarkup structure.

### lgl_template_markup_line_new ()

    lglTemplateMarkup *
    lgl_template_markup_line_new (gdouble x1,
                                  gdouble y1,
                                  gdouble x2,
                                  gdouble y2);

This function creates a new line markup structure.

#### Parameters

x1 | x coordinate of first endpoint. |
y1 | y coordinate of first endpoint. |
x2 | x coordinate of second endpoint. |
y2 | y coordinate of second endpoint. |

#### Returns

a newly allocated lglTemplateMarkup structure.

### lgl_template_markup_circle_new ()

    lglTemplateMarkup *
    lgl_template_markup_circle_new (gdouble x0,
                                    gdouble y0,
                                    gdouble r);

This function creates a new circle markup structure.

#### Parameters

x0 | x coordinate of center of circle. |
y0 | y coordinate of center of circle. |
r | radius of circle. |

#### Returns

a newly allocated lglTemplateMarkup structure.

### lgl_template_markup_rect_new ()

    lglTemplateMarkup *
    lgl_template_markup_rect_new (gdouble x1,
                                  gdouble y1,
                                  gdouble w,
                                  gdouble h,
                                  gdouble r);

This function creates a new rectangle markup structure.

#### Parameters

x1 | x coordinate of top-left corner of rectangle. |
y1 | y coordinate of top-left corner of rectangle. |
w | width of rectangle. |
h | height of rectangle. |
r | radius of rounded corner. |

#### Returns

a newly allocated lglTemplateMarkup structure.

### lgl_template_markup_ellipse_new ()

    lglTemplateMarkup *
    lgl_template_markup_ellipse_new (gdouble x1,
                                     gdouble y1,
                                     gdouble w,
                                     gdouble h);

This function creates a new ellipse markup structure.

#### Parameters

x1 | x coordinate of top-left corner of ellipse. |
y1 | y coordinate of top-left corner of ellipse. |
w | width of ellipse. |
h | height of ellipse. |

#### Returns

a newly allocated lglTemplateMarkup structure.

### lgl_template_markup_dup ()

    lglTemplateMarkup *
    lgl_template_markup_dup (const lglTemplateMarkup *orig_markup);

This function duplicates a template markup structure.

#### Parameters

orig_markup | Markup to duplicate. |

#### Returns

a newly allocated lglTemplateMarkup structure.

### lgl_template_markup_free ()

    void
    lgl_template_markup_free (lglTemplateMarkup *markup);

This function frees all memory associated with given template markup structure.

#### Parameters

markup | Markup to free. |

### lgl_template_print ()

    void
    lgl_template_print (const lglTemplate *template);

Print template details (for debugging purposes).

#### Parameters

template | template |

## Types and Values

### struct lglTemplate

    struct lglTemplate {
            gchar               *brand;
            gchar               *part;
            gchar               *equiv_part;

            gchar               *description;
            gchar               *paper_id;
            gdouble              page_width;
            gdouble              page_height;

            /* Meta information. */
            gchar               *product_url;   /* URL to manufacturer's product website. */
            GList               *category_ids;  /* List of (gchar *) category ids. */

            /* List of (lglTemplateFrame *) label frame structures.
             * Currently glabels only supports a single label frame per
             * template. */
            GList               *frames;
    };

### enum lglTemplateFrameShape

#### Members

LGL_TEMPLATE_FRAME_SHAPE_RECT |  |
LGL_TEMPLATE_FRAME_SHAPE_ELLIPSE |  |
LGL_TEMPLATE_FRAME_SHAPE_ROUND |  |
LGL_TEMPLATE_FRAME_SHAPE_CD |  |

### union lglTemplateFrame

### struct lglTemplateFrameAll

    struct lglTemplateFrameAll {
            /* Begin Common Fields */
            lglTemplateFrameShape shape;

            gchar                *id;       /* Id, currently always "0" */
            GList                *layouts;  /* List of lglTemplateLayouts */
            GList                *markups;  /* List of lglTemplateMarkups */
            /* End Common Fields */
    };

### struct lglTemplateFrameRect

    struct lglTemplateFrameRect {
            /* Begin Common Fields */
            lglTemplateFrameShape shape;    /* Always LGL_TEMPLATE_FRAME_SHAPE_RECT. */

            gchar                *id;       /* Id, currently always "0" */
            GList                *layouts;  /* List of lglTemplateLayouts */
            GList                *markups;  /* List of lglTemplateMarkups */
            /* End Common Fields */

            gdouble               w;        /* Width */
            gdouble               h;        /* Height */
            gdouble               r;        /* Corner radius */
            gdouble               x_waste;  /* Amount of horiz overprint allowed. */
            gdouble               y_waste;  /* Amount of vert overprint allowed. */
    };

### struct lglTemplateFrameEllipse

    struct lglTemplateFrameEllipse {
            /* Begin Common Fields */
            lglTemplateFrameShape shape;    /* Always LGL_TEMPLATE_FRAME_SHAPE_ELLIPSE. */

            gchar                *id;       /* Id, currently always "0" */
            GList                *layouts;  /* List of lglTemplateLayouts */
            GList                *markups;  /* List of lglTemplateMarkups */
            /* End Common Fields */

            gdouble               w;        /* Width */
            gdouble               h;        /* Height */
            gdouble               waste;    /* Amount of overprint allowed. */
    };

### struct lglTemplateFrameRound

    struct lglTemplateFrameRound {
            /* Begin Common Fields */
            lglTemplateFrameShape shape;    /* Always LGL_TEMPLATE_FRAME_SHAPE_ROUND. */

            gchar                *id;       /* Id, currently always "0" */
            GList                *layouts;  /* List of lglTemplateLayouts */
            GList                *markups;  /* List of lglTemplateMarkups */
            /* End Common Fields */

            gdouble               r;      /* Radius */
            gdouble               waste;  /* Amount of overprint allowed. */
    };

### struct lglTemplateFrameCD

    struct lglTemplateFrameCD {
            /* Begin Common Fields */
            lglTemplateFrameShape shape;    /* Always LGL_TEMPLATE_FRAME_SHAPE_CD. */

            gchar                *id;       /* Id, currently always "0" */
            GList                *layouts;  /* List of lglTemplateLayouts */
            GList                *markups;  /* List of lglTemplateMarkups */
            /* End Common Fields */

            gdouble               r1;     /* Outer radius */
            gdouble               r2;     /* Inner radius (hole) */
            gdouble               w;      /* Clip width, business card CDs */
            gdouble               h;      /* Clip height, business card CDs */
            gdouble               waste;  /* Amount of overprint allowed. */
    };

### struct lglTemplateLayout

    struct lglTemplateLayout {
            gint                  nx;  /* Number of labels across */
            gint                  ny;  /* Number of labels up and down */

            gdouble               x0;  /* Left of grid from left edge of paper */
            gdouble               y0;  /* Top of grid from top edge of paper */

            gdouble               dx;  /* Horizontal pitch of grid */
            gdouble               dy;  /* Vertical pitch of grid */
    };

### enum lglTemplateMarkupType

#### Members

LGL_TEMPLATE_MARKUP_MARGIN |  |
LGL_TEMPLATE_MARKUP_LINE |  |
LGL_TEMPLATE_MARKUP_CIRCLE |  |
LGL_TEMPLATE_MARKUP_RECT |  |
LGL_TEMPLATE_MARKUP_ELLIPSE |  |

### union lglTemplateMarkup

### struct lglTemplateMarkupMargin

    struct lglTemplateMarkupMargin {
            lglTemplateMarkupType  type;  /* Always LGL_TEMPLATE_MARKUP_MARGIN */

            gdouble                size;  /* Margin size */
    };

### struct lglTemplateMarkupLine

    struct lglTemplateMarkupLine {
            lglTemplateMarkupType  type;   /* Always LGL_TEMPLATE_MARKUP_LINE */

            gdouble                x1, y1; /* 1st endpoint */
            gdouble                x2, y2; /* 2nd endpoint */
    };

### struct lglTemplateMarkupCircle

    struct lglTemplateMarkupCircle {
            lglTemplateMarkupType  type;   /* Always LGL_TEMPLATE_MARKUP_CIRCLE */

            gdouble                x0, y0; /* Center of circle */
            gdouble                r;      /* Radius of circle */
    };

### struct lglTemplateMarkupRect

    struct lglTemplateMarkupRect {
            lglTemplateMarkupType  type;   /* Always LGL_TEMPLATE_MARKUP_RECT */

            gdouble                x1, y1; /* Upper left corner */
            gdouble                w, h;   /* Width and height. */
            gdouble                r;      /* Radius of corners. */
    };

### struct lglTemplateMarkupEllipse

    struct lglTemplateMarkupEllipse {
            lglTemplateMarkupType  type;   /* Always LGL_TEMPLATE_MARKUP_ELLIPSE */

            gdouble                x1, y1; /* Upper left corner */
            gdouble                w, h;   /* Width and height. */
    };

### struct lglTemplateOrigin

    struct lglTemplateOrigin {
            gdouble               x, y; /* Label origin relative to upper

                                         * upper left hand corner of paper */
    };