1 <!-- ##### SECTION Title ##### -->
2 The lglTemplate Structure
4 <!-- ##### SECTION Short_Description ##### -->
5 How templates are represented in memory
7 <!-- ##### SECTION Long_Description ##### -->
9 This section describes a set of structures that represent a template in memory. It also
10 describes functions to help create and interpret these structures.
13 <!-- ##### SECTION See_Also ##### -->
18 <!-- ##### SECTION Stability_Level ##### -->
21 <!-- ##### STRUCT lglTemplate ##### -->
23 This is the main structure of a libglabels template. A template represents a single sheet
24 of peel-off labels or cards.
27 @brand: Brand name of label or card. E.g. "Avery."
28 @part: Part name or number of label or card. E.g. "8160."
29 @description: A description of the template. E.g. "Mailing labels."
30 @paper_id: A paper ID. E.g. "A4" or "US-Letter."
31 @page_width: Page width in points. Used only if paper_id is "Other."
32 @page_height: Page height in points. Used only if paper_id is "Other."
33 @aliases: A list of alternate names for this template. Often a single template can be used for
35 @category_ids: A list of category IDs that this template belongs to.
36 @frames: A list of (#lglTemplateFrame *) structures. GLabels currently only supports one frame
37 per template -- future versions may support multiple frames per template.
39 <!-- ##### STRUCT lglTemplateAlias ##### -->
41 This structure defines an alias for the parent template structure. An alias is used for
42 different products that can use the same template.
45 @brand: Brand name of label or card. E.g. "Avery."
46 @part: Part name or number of label or card. E.g. "8160."
48 <!-- ##### ENUM lglTemplateFrameShape ##### -->
50 This enumeration defines frame types that are supported by libglabels
53 @LGL_TEMPLATE_FRAME_SHAPE_RECT: A rectangular frame. (May have rounded corners.)
54 @LGL_TEMPLATE_FRAME_SHAPE_ROUND: A round frame.
55 @LGL_TEMPLATE_FRAME_SHAPE_CD: A CD or DVD frame. (Includes credit-card style CDs.)
57 <!-- ##### UNION lglTemplateFrame ##### -->
59 A union of all possible frame structures. The type of structure is indicated by the shape
60 member, which overlays the first field of all other member structures.
64 <!-- ##### STRUCT lglTemplateFrameAll ##### -->
66 This structure is composed of a set of fields common to all frame structures. All frame types
67 can be cast to this structure.
70 @shape: The shape of the frame.
71 @id: Reserved for future use. Should always be zero.
72 @layouts: A list of (#lglTemplateLayout *) structures. Typically a frame will have a single
73 layout, representing a simple grid of labels or cards. If the layout of labels or cards is
74 more complex, multiple (#lglTemplateLayout *) structures may be needed.
75 @markups: A list of (#lglTemplateMarkup *) structures, which represent non-printing markup lines.
77 <!-- ##### STRUCT lglTemplateFrameRect ##### -->
79 This structure defines the frame for a rectangular label or card.
82 @shape: Common field. Always #LGL_TEMPLATE_FRAME_SHAPE_RECT for #lglTemplateFrameRect.
83 @id: Common field. See #lglTemplateFrameAll.
84 @layouts: Common field. See #lglTemplateFrameAll.
85 @markups: Common field. See #lglTemplateFrameAll.
86 @w: Width of label or card in points.
87 @h: Height of label or card in points.
88 @r: Radius of corners in points.
89 @x_waste: Amount of horizontal over-print to allow in points.
90 @y_waste: Amount of vertical over-print to allow in points.
92 <!-- ##### STRUCT lglTemplateFrameRound ##### -->
94 This structure defines the frame for a round label or card.
97 @shape: Common field. Always #LGL_TEMPLATE_FRAME_SHAPE_ROUND for #lglTemplateFrameRound.
98 @id: Common field. See #lglTemplateFrameAll.
99 @layouts: Common field. See #lglTemplateFrameAll.
100 @markups: Common field. See #lglTemplateFrameAll.
101 @r: Radius of label or card in points.
102 @waste: Amount of over-print to allow in points.
104 <!-- ##### STRUCT lglTemplateFrameCD ##### -->
106 This structure defines the frame for a CD or DVD label. This structure also supports
107 credit-card CD labels.
110 @shape: Common field. Always #LGL_TEMPLATE_FRAME_SHAPE_CD for #lglTemplateFrameCD.
111 @id: Common field. See #lglTemplateFrameAll.
112 @layouts: Common field. See #lglTemplateFrameAll.
113 @markups: Common field. See #lglTemplateFrameAll.
114 @r1: Outer radius of label in points.
115 @r2: Radius of center hole in points.
116 @w: Clip width in points. Used for credit-card CD labels. This field is ignored if zero.
117 @h: Clip height in points. Used for credit-card CD labels. This field is ignored if zero.
118 @waste: Amount of over-print to allow in points.
120 <!-- ##### STRUCT lglTemplateLayout ##### -->
122 This structure defines a simple grid layout of labels or cards.
125 @nx: Number of labels or cards across in the grid (horizontal).
126 @ny: Number of labels or cards down in the grid (vertical).
127 @x0: Distance (in points) from the left edge of page to the left edge of the left column of
128 cards or labels in the layout.
129 @y0: Distance (in points) from the top edge of page to the top edge of the top row of
130 cards or labels in the layout.
131 @dx: Horizontal pitch of grid in points. This is the distance from left edge to left edge
132 (not the gap between labels or cards).
133 @dy: Vertical pitch of grid in points. This is the distance from top edge to top edge
134 (not the gap between labels or cards).
136 <!-- ##### ENUM lglTemplateMarkupType ##### -->
138 This enumeration defines markup types that are supported by libglabels
141 @LGL_TEMPLATE_MARKUP_MARGIN: A margin line around perimeter of label or card.
142 @LGL_TEMPLATE_MARKUP_LINE: A simple line segment.
143 @LGL_TEMPLATE_MARKUP_CIRCLE: A circle.
144 @LGL_TEMPLATE_MARKUP_RECT: A rectangle. Possibly with rounded corners.
146 <!-- ##### UNION lglTemplateMarkup ##### -->
148 A union of all possible markup structures. The type of structure is indicated by the type
149 member, which overlays the first field of all other member structures.
153 <!-- ##### STRUCT lglTemplateMarkupMargin ##### -->
155 This structure defines a simple margin markup around the perimeter of a label or card.
158 @type: Common field. Always #LGL_TEMPLATE_MARKUP_MARGIN for #lglTemplateMarkupMargin.
159 @size: Distance of margin from edge of label or card.
161 <!-- ##### STRUCT lglTemplateMarkupLine ##### -->
163 This structure defines a simple line segment markup.
166 @type: Common field. Always #LGL_TEMPLATE_MARKUP_LINE for #lglTemplateMarkupLine.
167 @x1: Distance (in points) of first endpoint from left edge of label or card.
168 @y1: Distance (in points) of first endpoint from top edge of label or card.
169 @x2: Distance (in points) of second endpoint from left edge of label or card.
170 @y2: Distance (in points) of second endpoint from top edge of label or card.
172 <!-- ##### STRUCT lglTemplateMarkupCircle ##### -->
174 This structure defines a simple circle markup.
177 @type: Common field. Always #LGL_TEMPLATE_MARKUP_CIRCLE for #lglTemplateMarkupCircle.
178 @x0: Distance (in points) of vertex from left edge of label or card.
179 @y0: Distance (in points) of vertex from top edge of label or card.
180 @r: Radius of circle in points.
182 <!-- ##### STRUCT lglTemplateMarkupRect ##### -->
184 This structure defines a simple rectangle markup. The rectangle can have rounded corners.
187 @type: Common field. Always #LGL_TEMPLATE_MARKUP_RECT for #lglTemplateMarkupRect.
188 @x1: Distance (in points) of left edge of markup from left edge of label or card.
189 @y1: Distance (in points) of top edge of markup from top edge of label or card.
190 @w: Width of rectangle in points.
191 @h: Height of rectangle in points.
192 @r: Radius of corners in points. Should be zero for sharp corners.
194 <!-- ##### STRUCT lglTemplateOrigin ##### -->
196 This structure represents the cartesian coordinates of the origin of a label or card on the page.
197 The orign is the upper left corner of the extent of the label or card. These coordinates are
198 relative to the upper left corner of the page.
201 @x: Distance in points from top edge of page.
202 @y: Distance in points from left edge of page.
204 <!-- ##### FUNCTION lgl_template_new ##### -->
218 <!-- ##### FUNCTION lgl_template_dup ##### -->
227 <!-- ##### FUNCTION lgl_template_free ##### -->
235 <!-- ##### FUNCTION lgl_template_add_category ##### -->
244 <!-- ##### FUNCTION lgl_template_add_frame ##### -->
253 <!-- ##### FUNCTION lgl_template_add_alias ##### -->
262 <!-- ##### FUNCTION lgl_template_get_name ##### -->
271 <!-- ##### FUNCTION lgl_template_do_templates_match ##### -->
281 <!-- ##### FUNCTION lgl_template_does_brand_match ##### -->
291 <!-- ##### FUNCTION lgl_template_does_page_size_match ##### -->
301 <!-- ##### FUNCTION lgl_template_does_category_match ##### -->
311 <!-- ##### FUNCTION lgl_template_alias_new ##### -->
321 <!-- ##### FUNCTION lgl_template_alias_dup ##### -->
330 <!-- ##### FUNCTION lgl_template_alias_free ##### -->
338 <!-- ##### FUNCTION lgl_template_frame_rect_new ##### -->
352 <!-- ##### FUNCTION lgl_template_frame_round_new ##### -->
363 <!-- ##### FUNCTION lgl_template_frame_cd_new ##### -->
377 <!-- ##### FUNCTION lgl_template_frame_dup ##### -->
386 <!-- ##### FUNCTION lgl_template_frame_free ##### -->
394 <!-- ##### FUNCTION lgl_template_frame_add_layout ##### -->
403 <!-- ##### FUNCTION lgl_template_frame_add_markup ##### -->
412 <!-- ##### FUNCTION lgl_template_frame_get_size ##### -->
422 <!-- ##### FUNCTION lgl_template_frame_get_n_labels ##### -->
431 <!-- ##### FUNCTION lgl_template_frame_get_origins ##### -->
440 <!-- ##### FUNCTION lgl_template_layout_new ##### -->
454 <!-- ##### FUNCTION lgl_template_layout_dup ##### -->
463 <!-- ##### FUNCTION lgl_template_layout_free ##### -->
471 <!-- ##### FUNCTION lgl_template_markup_margin_new ##### -->
480 <!-- ##### FUNCTION lgl_template_markup_line_new ##### -->
492 <!-- ##### FUNCTION lgl_template_markup_circle_new ##### -->
503 <!-- ##### FUNCTION lgl_template_markup_rect_new ##### -->
516 <!-- ##### FUNCTION lgl_template_markup_dup ##### -->
525 <!-- ##### FUNCTION lgl_template_markup_free ##### -->