template

template

Synopsis

#include <libglabels/lgl-template.h>

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;

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_new_from_equiv         (const gchar *brand,
                                                         const gchar *part,
                                                         const gchar *equiv_part);
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);

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);
gboolean            lgl_template_are_templates_identical
                                                        (const lglTemplate *template1,
                                                         const lglTemplate *template2);

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_ellipse_new      (const gchar *id,
                                                         gdouble w,
                                                         gdouble h,
                                                         gdouble 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);
gchar *             lgl_template_frame_get_layout_description
                                                        (const lglTemplateFrame *frame);
gchar *             lgl_template_frame_get_size_description
                                                        (const lglTemplateFrame *frame,
                                                         lglUnits units);

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_ellipse_new     (gdouble x1,
                                                         gdouble y1,
                                                         gdouble w,
                                                         gdouble h);
lglTemplateMarkup * lgl_template_markup_dup             (const lglTemplateMarkup *orig_markup);
void                lgl_template_markup_free            (lglTemplateMarkup *markup);

void                lgl_template_print                  (const lglTemplate *template);

Description

Details

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

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


union lglTemplateFrame

union _lglTemplateFrame{

        lglTemplateFrameShape   shape;

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


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

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


union lglTemplateMarkup

union _lglTemplateMarkup {

        lglTemplateMarkupType    type;

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


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 */
};


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.

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.

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.

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

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

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.

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.

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.

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

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.

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.

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_ellipse_new ()

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

This function creates a new ellipse markup structure.

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.

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.

lgl_template_print ()

void                lgl_template_print                  (const lglTemplate *template);

Print template details (for debugging purposes).

template :

template