## The lglTemplate Structure

The lglTemplate Structure — How templates are represented in memory

## Synopsis

    #include <libglabels/template.h>

                        lglTemplate;

                        lglTemplateAlias;

    enum                lglTemplateFrameShape;
    union               lglTemplateFrame;
                        lglTemplateFrameAll;
                        lglTemplateFrameRect;
                        lglTemplateFrameRound;
                        lglTemplateFrameCD;

                        lglTemplateLayout;

    enum                lglTemplateMarkupType;
    union               lglTemplateMarkup;
                        lglTemplateMarkupMargin;
                        lglTemplateMarkupLine;
                        lglTemplateMarkupCircle;
                        lglTemplateMarkupRect;

                        lglTemplateOrigin;

    lglTemplate *       lgl_template_new                    (const gchar *brand,
                                                             const gchar *part,
                                                             const gchar *description,
                                                             const gchar *paper_id,
                                                             gdouble page_width,
                                                             gdouble page_height);
    lglTemplate *       lgl_template_dup                    (const lglTemplate *orig_template);
    void                lgl_template_free                   (lglTemplate *template);
    void                lgl_template_add_category           (lglTemplate *template,
                                                             const gchar *category_id);
    void                lgl_template_add_frame              (lglTemplate *template,
                                                             lglTemplateFrame *frame);
    void                lgl_template_add_alias              (lglTemplate *template,
                                                             lglTemplateAlias *alias);

    gchar *             lgl_template_get_name               (const lglTemplate *template);
    gboolean            lgl_template_do_templates_match     (const lglTemplate *template1,
                                                             const lglTemplate *template2);
    gboolean            lgl_template_does_brand_match       (const lglTemplate *template,
                                                             const gchar *brand);
    gboolean            lgl_template_does_page_size_match   (const lglTemplate *template,
                                                             const gchar *paper_id);
    gboolean            lgl_template_does_category_match    (const lglTemplate *template,
                                                             const gchar *category_id);

    lglTemplateAlias *  lgl_template_alias_new              (const gchar *brand,
                                                             const gchar *part);
    lglTemplateAlias *  lgl_template_alias_dup              (const lglTemplateAlias *orig_alias);
    void                lgl_template_alias_free             (lglTemplateAlias *alias);

    lglTemplateFrame *  lgl_template_frame_rect_new         (const gchar *id,
                                                             gdouble w,
                                                             gdouble h,
                                                             gdouble r,
                                                             gdouble x_waste,
                                                             gdouble y_waste);
    lglTemplateFrame *  lgl_template_frame_round_new        (const gchar *id,
                                                             gdouble r,
                                                             gdouble waste);
    lglTemplateFrame *  lgl_template_frame_cd_new           (const gchar *id,
                                                             gdouble r1,
                                                             gdouble r2,
                                                             gdouble w,
                                                             gdouble h,
                                                             gdouble waste);
    lglTemplateFrame *  lgl_template_frame_dup              (const lglTemplateFrame *orig_frame);
    void                lgl_template_frame_free             (lglTemplateFrame *frame);
    void                lgl_template_frame_add_layout       (lglTemplateFrame *frame,
                                                             lglTemplateLayout *layout);
    void                lgl_template_frame_add_markup       (lglTemplateFrame *frame,
                                                             lglTemplateMarkup *markup);

    void                lgl_template_frame_get_size         (const lglTemplateFrame *frame,
                                                             gdouble *w,
                                                             gdouble *h);
    gint                lgl_template_frame_get_n_labels     (const lglTemplateFrame *frame);
    lglTemplateOrigin * lgl_template_frame_get_origins      (const lglTemplateFrame *frame);

    lglTemplateLayout * lgl_template_layout_new             (gint nx,
                                                             gint ny,
                                                             gdouble x0,
                                                             gdouble y0,
                                                             gdouble dx,
                                                             gdouble dy);
    lglTemplateLayout * lgl_template_layout_dup             (const lglTemplateLayout *orig_layout);
    void                lgl_template_layout_free            (lglTemplateLayout *layout);

    lglTemplateMarkup * lgl_template_markup_margin_new      (gdouble size);
    lglTemplateMarkup * lgl_template_markup_line_new        (gdouble x1,
                                                             gdouble y1,
                                                             gdouble x2,
                                                             gdouble y2);
    lglTemplateMarkup * lgl_template_markup_circle_new      (gdouble x0,
                                                             gdouble y0,
                                                             gdouble r);
    lglTemplateMarkup * lgl_template_markup_rect_new        (gdouble x1,
                                                             gdouble y1,
                                                             gdouble w,
                                                             gdouble h,
                                                             gdouble r);
    lglTemplateMarkup * lgl_template_markup_dup             (const lglTemplateMarkup *orig_markup);
    void                lgl_template_markup_free            (lglTemplateMarkup *markup);

## Description

This section describes a set of structures that represent a template in memory. It also describes functions to help create and interpret these structures.

## Details

### lglTemplate

    typedef struct {
    	gchar               *brand;
            gchar               *part;
    	gchar               *description;
    	gchar               *paper_id;
    	gdouble              page_width;
    	gdouble              page_height;

    	/* List of (lglTemplateAlias *) aliase structures. */
    	GList               *aliases;

            /* List of (gchar *) category ids. */
    	GList               *category_ids;

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

This is the main structure of a libglabels template. A template represents a single sheet of peel-off labels or cards.

gchar *`brand`; | Brand name of label or card. E.g. "Avery."
gchar *`part`; | Part name or number of label or card. E.g. "8160."
gchar *`description`; | A description of the template. E.g. "Mailing labels."
gchar *`paper_id`; | A paper ID. E.g. "A4" or "US-Letter."
gdouble `page_width`; | Page width in points. Used only if paper_id is "Other."
gdouble `page_height`; | Page height in points. Used only if paper_id is "Other."
GList *`aliases`; | A list of alternate names for this template. Often a single template can be used for multiple products.
GList *`category_ids`; | A list of category IDs that this template belongs to.
GList *`frames`; | A list of (lglTemplateFrame *) structures. GLabels currently only supports one frame per template -- future versions may support multiple frames per template.

### lglTemplateAlias

    typedef struct {
    	gchar               *brand;
            gchar               *part;
    } lglTemplateAlias;

This structure defines an alias for the parent template structure. An alias is used for different products that can use the same template.

gchar *`brand`; | Brand name of label or card. E.g. "Avery."
gchar *`part`; | Part name or number of label or card. E.g. "8160."

### enum lglTemplateFrameShape

    typedef enum {
    	LGL_TEMPLATE_FRAME_SHAPE_RECT,
    	LGL_TEMPLATE_FRAME_SHAPE_ROUND,
    	LGL_TEMPLATE_FRAME_SHAPE_CD,
    } lglTemplateFrameShape;

This enumeration defines frame types that are supported by libglabels

`LGL_TEMPLATE_FRAME_SHAPE_RECT` | A rectangular frame. (May have rounded corners.)
`LGL_TEMPLATE_FRAME_SHAPE_ROUND` | A round frame.
`LGL_TEMPLATE_FRAME_SHAPE_CD` | A CD or DVD frame. (Includes credit-card style CDs.)

### union lglTemplateFrame

    union lglTemplateFrame{

    	lglTemplateFrameShape shape;

    	lglTemplateFrameAll   all;
    	lglTemplateFrameRect  rect;
    	lglTemplateFrameRound round;
    	lglTemplateFrameCD    cd;
    };

A union of all possible frame structures. The type of structure is indicated by the shape member, which overlays the first field of all other member structures.

### lglTemplateFrameAll

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

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

This structure is composed of a set of fields common to all frame structures. All frame types can be cast to this structure.

lglTemplateFrameShape `shape`; | The shape of the frame.
gchar *`id`; | Reserved for future use. Should always be zero.
GList *`layouts`; | A list of (lglTemplateLayout *) structures. Typically a frame will have a single layout, representing a simple grid of labels or cards. If the layout of labels or cards is more complex, multiple (lglTemplateLayout *) structures may be needed.
GList *`markups`; | A list of (lglTemplateMarkup *) structures, which represent non-printing markup lines.

### lglTemplateFrameRect

    typedef struct {
            /* 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. */
    } lglTemplateFrameRect;

This structure defines the frame for a rectangular label or card.

lglTemplateFrameShape `shape`; | Common field. Always LGL_TEMPLATE_FRAME_SHAPE_RECT for lglTemplateFrameRect.
gchar *`id`; | Common field. See lglTemplateFrameAll.
GList *`layouts`; | Common field. See lglTemplateFrameAll.
GList *`markups`; | Common field. See lglTemplateFrameAll.
gdouble `w`; | Width of label or card in points.
gdouble `h`; | Height of label or card in points.
gdouble `r`; | Radius of corners in points.
gdouble `x_waste`; | Amount of horizontal over-print to allow in points.
gdouble `y_waste`; | Amount of vertical over-print to allow in points.

### lglTemplateFrameRound

    typedef struct {
            /* 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. */
    } lglTemplateFrameRound;

This structure defines the frame for a round label or card.

lglTemplateFrameShape `shape`; | Common field. Always LGL_TEMPLATE_FRAME_SHAPE_ROUND for lglTemplateFrameRound.
gchar *`id`; | Common field. See lglTemplateFrameAll.
GList *`layouts`; | Common field. See lglTemplateFrameAll.
GList *`markups`; | Common field. See lglTemplateFrameAll.
gdouble `r`; | Radius of label or card in points.
gdouble `waste`; | Amount of over-print to allow in points.

### lglTemplateFrameCD

    typedef struct {
            /* 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. */
    } lglTemplateFrameCD;

This structure defines the frame for a CD or DVD label. This structure also supports credit-card CD labels.

lglTemplateFrameShape `shape`; | Common field. Always LGL_TEMPLATE_FRAME_SHAPE_CD for lglTemplateFrameCD.
gchar *`id`; | Common field. See lglTemplateFrameAll.
GList *`layouts`; | Common field. See lglTemplateFrameAll.
GList *`markups`; | Common field. See lglTemplateFrameAll.
gdouble `r1`; | Outer radius of label in points.
gdouble `r2`; | Radius of center hole in points.
gdouble `w`; | Clip width in points. Used for credit-card CD labels. This field is ignored if zero.
gdouble `h`; | Clip height in points. Used for credit-card CD labels. This field is ignored if zero.
gdouble `waste`; | Amount of over-print to allow in points.

### lglTemplateLayout

    typedef struct {
    	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 */
    } lglTemplateLayout;

This structure defines a simple grid layout of labels or cards.

gint `nx`; | Number of labels or cards across in the grid (horizontal).
gint `ny`; | Number of labels or cards down in the grid (vertical).
gdouble `x0`; | Distance (in points) from the left edge of page to the left edge of the left column of cards or labels in the layout.
gdouble `y0`; | Distance (in points) from the top edge of page to the top edge of the top row of cards or labels in the layout.
gdouble `dx`; | Horizontal pitch of grid in points. This is the distance from left edge to left edge (not the gap between labels or cards).
gdouble `dy`; | Vertical pitch of grid in points. This is the distance from top edge to top edge (not the gap between labels or cards).

### enum lglTemplateMarkupType

    typedef enum {
    	LGL_TEMPLATE_MARKUP_MARGIN,
    	LGL_TEMPLATE_MARKUP_LINE,
    	LGL_TEMPLATE_MARKUP_CIRCLE,
    	LGL_TEMPLATE_MARKUP_RECT,
    } lglTemplateMarkupType;

This enumeration defines markup types that are supported by libglabels

`LGL_TEMPLATE_MARKUP_MARGIN` | A margin line around perimeter of label or card.
`LGL_TEMPLATE_MARKUP_LINE` | A simple line segment.
`LGL_TEMPLATE_MARKUP_CIRCLE` | A circle.
`LGL_TEMPLATE_MARKUP_RECT` | A rectangle. Possibly with rounded corners.

### union lglTemplateMarkup

    union lglTemplateMarkup {

    	lglTemplateMarkupType   type;

    	lglTemplateMarkupMargin margin;
    	lglTemplateMarkupLine   line;
    	lglTemplateMarkupCircle circle;
    	lglTemplateMarkupRect   rect;
    };

A union of all possible markup structures. The type of structure is indicated by the type member, which overlays the first field of all other member structures.

### lglTemplateMarkupMargin

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

            gdouble                size;  /* Margin size */
    } lglTemplateMarkupMargin;

This structure defines a simple margin markup around the perimeter of a label or card.

lglTemplateMarkupType `type`; | Common field. Always LGL_TEMPLATE_MARKUP_MARGIN for lglTemplateMarkupMargin.
gdouble `size`; | Distance of margin from edge of label or card.

### lglTemplateMarkupLine

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

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

This structure defines a simple line segment markup.

lglTemplateMarkupType `type`; | Common field. Always LGL_TEMPLATE_MARKUP_LINE for lglTemplateMarkupLine.
gdouble `x1`; | Distance (in points) of first endpoint from left edge of label or card.
gdouble `y1`; | Distance (in points) of first endpoint from top edge of label or card.
gdouble `x2`; | Distance (in points) of second endpoint from left edge of label or card.
gdouble `y2`; | Distance (in points) of second endpoint from top edge of label or card.

### lglTemplateMarkupCircle

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

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

This structure defines a simple circle markup.

lglTemplateMarkupType `type`; | Common field. Always LGL_TEMPLATE_MARKUP_CIRCLE for lglTemplateMarkupCircle.
gdouble `x0`; | Distance (in points) of vertex from left edge of label or card.
gdouble `y0`; | Distance (in points) of vertex from top edge of label or card.
gdouble `r`; | Radius of circle in points.

### lglTemplateMarkupRect

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

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

This structure defines a simple rectangle markup. The rectangle can have rounded corners.

lglTemplateMarkupType `type`; | Common field. Always LGL_TEMPLATE_MARKUP_RECT for lglTemplateMarkupRect.
gdouble `x1`; | Distance (in points) of left edge of markup from left edge of label or card.
gdouble `y1`; | Distance (in points) of top edge of markup from top edge of label or card.
gdouble `w`; | Width of rectangle in points.
gdouble `h`; | Height of rectangle in points.
gdouble `r`; | Radius of corners in points. Should be zero for sharp corners.

### lglTemplateOrigin

    typedef struct {
    	gdouble               x, y; /* Label origin relative to upper
    				     * upper left hand corner of paper */
    } lglTemplateOrigin;

This structure represents the cartesian coordinates of the origin of a label or card on the page. The orign is the upper left corner of the extent of the label or card. These coordinates are relative to the upper left corner of the page.

gdouble `x`; | Distance in points from top edge of page.
gdouble `y`; | Distance in points from left edge of page.

### 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 aliases, categories, or frames associated with it. See `lgl_template_add_alias()`, `lgl_template_add_category()`, and `lgl_template_add_frame()` to add these.

`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_dup ()

    lglTemplate *       lgl_template_dup                    (const lglTemplate *orig_template);

This function duplicates a template structure.

`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.

`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.

`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.

`template` : | Pointer to template structure
`frame` : | Pointer to frame structure

### lgl_template_add_alias ()

    void                lgl_template_add_alias              (lglTemplate *template,
                                                             lglTemplateAlias *alias);

This function adds the given alias to a templates list of aliases.

`template` : | Pointer to template structure
`alias` : | Alias string

### 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.

`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.

`template1` : | Pointer to 1st template structure to test
`template2` : | Pointer to 2nd template structure to test
Returns : | TRUE if the two template matche.

### 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.

`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.

`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.

`template` : | Pointer to template structure to test
`category_id` : | Category ID string
Returns : | TRUE if the template matches the given category ID.

### lgl_template_alias_new ()

    lglTemplateAlias *  lgl_template_alias_new              (const gchar *brand,
                                                             const gchar *part);

Create a new template alias structure, with the given brand and part number.

`brand` : | Alias brand
`part` : | Alias part name/number
Returns : | pointer to a newly allocated lglTemplateAlias structure.

### lgl_template_alias_dup ()

    lglTemplateAlias *  lgl_template_alias_dup              (const lglTemplateAlias *orig_alias);

This function duplicates a template alias structure.

`orig_alias` : | Alias to duplicate.
Returns : | a newly allocated lglTemplateAlias structure.

### lgl_template_alias_free ()

    void                lgl_template_alias_free             (lglTemplateAlias *alias);

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

`alias` : | Alias to free.

### 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.

`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_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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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()`.

`frame` : | lglTemplateFrame structure to query
Returns : | A newly allocated array of lglTemplateOrigin structures.

### 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.

`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.

`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.

`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.

`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.

`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.

`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.

`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_dup ()

    lglTemplateMarkup * lgl_template_markup_dup             (const lglTemplateMarkup *orig_markup);

This function duplicates a template markup structure.

`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.

`markup` : | Markup to free.