git.sur5r.net Git - glabels/blob - docs/libglabels/tmpl/template.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 The lglTemplate Structure
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 How templates are represented in memory
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   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.
  11 </para>
  12
  13 <!-- ##### SECTION See_Also ##### -->
  14 <para>
  15
  16 </para>
  17
  18 <!-- ##### SECTION Stability_Level ##### -->
  19
  20
  21 <!-- ##### STRUCT lglTemplate ##### -->
  22 <para>
  23 This is the main structure of a libglabels template.  A template represents a single sheet
  24 of peel-off labels or cards.
  25 </para>
  26
  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
  34 multiple products.
  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.
  38
  39 <!-- ##### STRUCT lglTemplateAlias ##### -->
  40 <para>
  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.
  43 </para>
  44
  45 @brand: Brand name of label or card.  E.g. "Avery."
  46 @part: Part name or number of label or card.  E.g. "8160."
  47
  48 <!-- ##### ENUM lglTemplateFrameShape ##### -->
  49 <para>
  50 This enumeration defines frame types that are supported by libglabels
  51 </para>
  52
  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.)
  56
  57 <!-- ##### UNION lglTemplateFrame ##### -->
  58 <para>
  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.
  61 </para>
  62
  63
  64 <!-- ##### STRUCT lglTemplateFrameAll ##### -->
  65 <para>
  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.
  68 </para>
  69
  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.
  76
  77 <!-- ##### STRUCT lglTemplateFrameRect ##### -->
  78 <para>
  79 This structure defines the frame for a rectangular label or card.
  80 </para>
  81
  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.
  91
  92 <!-- ##### STRUCT lglTemplateFrameRound ##### -->
  93 <para>
  94 This structure defines the frame for a round label or card.
  95 </para>
  96
  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.
 103
 104 <!-- ##### STRUCT lglTemplateFrameCD ##### -->
 105 <para>
 106 This structure defines the frame for a CD or DVD label.  This structure also supports
 107 credit-card CD labels.
 108 </para>
 109
 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.
 119
 120 <!-- ##### STRUCT lglTemplateLayout ##### -->
 121 <para>
 122 This structure defines a simple grid layout of labels or cards.
 123 </para>
 124
 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).
 135
 136 <!-- ##### ENUM lglTemplateMarkupType ##### -->
 137 <para>
 138 This enumeration defines markup types that are supported by libglabels
 139 </para>
 140
 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.
 145
 146 <!-- ##### UNION lglTemplateMarkup ##### -->
 147 <para>
 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.
 150 </para>
 151
 152
 153 <!-- ##### STRUCT lglTemplateMarkupMargin ##### -->
 154 <para>
 155 This structure defines a simple margin markup around the perimeter of a label or card.
 156 </para>
 157
 158 @type: Common field.  Always #LGL_TEMPLATE_MARKUP_MARGIN for #lglTemplateMarkupMargin.
 159 @size: Distance of margin from edge of label or card.
 160
 161 <!-- ##### STRUCT lglTemplateMarkupLine ##### -->
 162 <para>
 163 This structure defines a simple line segment markup.
 164 </para>
 165
 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.
 171
 172 <!-- ##### STRUCT lglTemplateMarkupCircle ##### -->
 173 <para>
 174 This structure defines a simple circle markup.
 175 </para>
 176
 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.
 181
 182 <!-- ##### STRUCT lglTemplateMarkupRect ##### -->
 183 <para>
 184 This structure defines a simple rectangle markup.  The rectangle can have rounded corners.
 185 </para>
 186
 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.
 193
 194 <!-- ##### STRUCT lglTemplateOrigin ##### -->
 195 <para>
 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.
 199 </para>
 200
 201 @x: Distance in points from top edge of page.
 202 @y: Distance in points from left edge of page.
 203
 204 <!-- ##### FUNCTION lgl_template_new ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @brand:
 210 @part:
 211 @description:
 212 @paper_id:
 213 @page_width:
 214 @page_height:
 215 @Returns:
 216
 217
 218 <!-- ##### FUNCTION lgl_template_dup ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @orig_template:
 224 @Returns:
 225
 226
 227 <!-- ##### FUNCTION lgl_template_free ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @template:
 233
 234
 235 <!-- ##### FUNCTION lgl_template_add_category ##### -->
 236 <para>
 237
 238 </para>
 239
 240 @template:
 241 @category_id:
 242
 243
 244 <!-- ##### FUNCTION lgl_template_add_frame ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @template:
 250 @frame:
 251
 252
 253 <!-- ##### FUNCTION lgl_template_add_alias ##### -->
 254 <para>
 255
 256 </para>
 257
 258 @template:
 259 @alias:
 260
 261
 262 <!-- ##### FUNCTION lgl_template_get_name ##### -->
 263 <para>
 264
 265 </para>
 266
 267 @template:
 268 @Returns:
 269
 270
 271 <!-- ##### FUNCTION lgl_template_do_templates_match ##### -->
 272 <para>
 273
 274 </para>
 275
 276 @template1:
 277 @template2:
 278 @Returns:
 279
 280
 281 <!-- ##### FUNCTION lgl_template_does_brand_match ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @template:
 287 @brand:
 288 @Returns:
 289
 290
 291 <!-- ##### FUNCTION lgl_template_does_page_size_match ##### -->
 292 <para>
 293
 294 </para>
 295
 296 @template:
 297 @paper_id:
 298 @Returns:
 299
 300
 301 <!-- ##### FUNCTION lgl_template_does_category_match ##### -->
 302 <para>
 303
 304 </para>
 305
 306 @template:
 307 @category_id:
 308 @Returns:
 309
 310
 311 <!-- ##### FUNCTION lgl_template_alias_new ##### -->
 312 <para>
 313
 314 </para>
 315
 316 @brand:
 317 @part:
 318 @Returns:
 319
 320
 321 <!-- ##### FUNCTION lgl_template_alias_dup ##### -->
 322 <para>
 323
 324 </para>
 325
 326 @orig_alias:
 327 @Returns:
 328
 329
 330 <!-- ##### FUNCTION lgl_template_alias_free ##### -->
 331 <para>
 332
 333 </para>
 334
 335 @alias:
 336
 337
 338 <!-- ##### FUNCTION lgl_template_frame_rect_new ##### -->
 339 <para>
 340
 341 </para>
 342
 343 @id:
 344 @w:
 345 @h:
 346 @r:
 347 @x_waste:
 348 @y_waste:
 349 @Returns:
 350
 351
 352 <!-- ##### FUNCTION lgl_template_frame_round_new ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @id:
 358 @r:
 359 @waste:
 360 @Returns:
 361
 362
 363 <!-- ##### FUNCTION lgl_template_frame_cd_new ##### -->
 364 <para>
 365
 366 </para>
 367
 368 @id:
 369 @r1:
 370 @r2:
 371 @w:
 372 @h:
 373 @waste:
 374 @Returns:
 375
 376
 377 <!-- ##### FUNCTION lgl_template_frame_dup ##### -->
 378 <para>
 379
 380 </para>
 381
 382 @orig_frame:
 383 @Returns:
 384
 385
 386 <!-- ##### FUNCTION lgl_template_frame_free ##### -->
 387 <para>
 388
 389 </para>
 390
 391 @frame:
 392
 393
 394 <!-- ##### FUNCTION lgl_template_frame_add_layout ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @frame:
 400 @layout:
 401
 402
 403 <!-- ##### FUNCTION lgl_template_frame_add_markup ##### -->
 404 <para>
 405
 406 </para>
 407
 408 @frame:
 409 @markup:
 410
 411
 412 <!-- ##### FUNCTION lgl_template_frame_get_size ##### -->
 413 <para>
 414
 415 </para>
 416
 417 @frame:
 418 @w:
 419 @h:
 420
 421
 422 <!-- ##### FUNCTION lgl_template_frame_get_n_labels ##### -->
 423 <para>
 424
 425 </para>
 426
 427 @frame:
 428 @Returns:
 429
 430
 431 <!-- ##### FUNCTION lgl_template_frame_get_origins ##### -->
 432 <para>
 433
 434 </para>
 435
 436 @frame:
 437 @Returns:
 438
 439
 440 <!-- ##### FUNCTION lgl_template_layout_new ##### -->
 441 <para>
 442
 443 </para>
 444
 445 @nx:
 446 @ny:
 447 @x0:
 448 @y0:
 449 @dx:
 450 @dy:
 451 @Returns:
 452
 453
 454 <!-- ##### FUNCTION lgl_template_layout_dup ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @orig_layout:
 460 @Returns:
 461
 462
 463 <!-- ##### FUNCTION lgl_template_layout_free ##### -->
 464 <para>
 465
 466 </para>
 467
 468 @layout:
 469
 470
 471 <!-- ##### FUNCTION lgl_template_markup_margin_new ##### -->
 472 <para>
 473
 474 </para>
 475
 476 @size:
 477 @Returns:
 478
 479
 480 <!-- ##### FUNCTION lgl_template_markup_line_new ##### -->
 481 <para>
 482
 483 </para>
 484
 485 @x1:
 486 @y1:
 487 @x2:
 488 @y2:
 489 @Returns:
 490
 491
 492 <!-- ##### FUNCTION lgl_template_markup_circle_new ##### -->
 493 <para>
 494
 495 </para>
 496
 497 @x0:
 498 @y0:
 499 @r:
 500 @Returns:
 501
 502
 503 <!-- ##### FUNCTION lgl_template_markup_rect_new ##### -->
 504 <para>
 505
 506 </para>
 507
 508 @x1:
 509 @y1:
 510 @w:
 511 @h:
 512 @r:
 513 @Returns:
 514
 515
 516 <!-- ##### FUNCTION lgl_template_markup_dup ##### -->
 517 <para>
 518
 519 </para>
 520
 521 @orig_markup:
 522 @Returns:
 523
 524
 525 <!-- ##### FUNCTION lgl_template_markup_free ##### -->
 526 <para>
 527
 528 </para>
 529
 530 @markup:
 531
 532