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 <!-- ##### SECTION Image ##### -->
  22
  23
  24 <!-- ##### STRUCT lglTemplate ##### -->
  25 <para>
  26 This is the main structure of a libglabels template.  A template represents a single sheet
  27 of peel-off labels or cards.
  28 </para>
  29
  30 @brand: Vendor or brand name of label or card.  E.g. "Avery."
  31 @part: Part name or number of label or card.  E.g. "8160."
  32 @equiv_part: Part name or number of a part with identical layout.  Must be from same vendor.
  33 @description: A description of the template.  E.g. "Mailing labels."
  34 @paper_id: A paper ID.  E.g. "A4" or "US-Letter."
  35 @page_width: Page width in points.  Used only if paper_id is "Other."
  36 @page_height: Page height in points.  Used only if paper_id is "Other."
  37 @product_url: URL to a webpage describing product.
  38 @category_ids: A list of category IDs that this template belongs to.
  39 @frames: A list of (#lglTemplateFrame *) structures.  GLabels currently only supports one frame
  40 per template -- future versions may support multiple frames per template.
  41
  42 <!-- ##### ENUM lglTemplateFrameShape ##### -->
  43 <para>
  44 This enumeration defines frame types that are supported by libglabels
  45 </para>
  46
  47 @LGL_TEMPLATE_FRAME_SHAPE_RECT: A rectangular frame.  (May have rounded corners.)
  48 @LGL_TEMPLATE_FRAME_SHAPE_ELLIPSE: An elliptical frame.
  49 @LGL_TEMPLATE_FRAME_SHAPE_ROUND: A round frame.
  50 @LGL_TEMPLATE_FRAME_SHAPE_CD: A CD or DVD frame.  (Includes credit-card style CDs.)
  51
  52 <!-- ##### UNION lglTemplateFrame ##### -->
  53 <para>
  54 A union of all possible frame structures.  The type of structure is indicated by the shape
  55 member, which overlays the first field of all other member structures.
  56 </para>
  57
  58
  59 <!-- ##### STRUCT lglTemplateFrameAll ##### -->
  60 <para>
  61 This structure is composed of a set of fields common to all frame structures.  All frame types
  62 can be cast to this structure.
  63 </para>
  64
  65 @shape: The shape of the frame.
  66 @id: Reserved for future use.  Should always be zero.
  67 @layouts: A list of (#lglTemplateLayout *) structures.  Typically a frame will have a single
  68 layout, representing a simple grid of labels or cards.  If the layout of labels or cards is
  69 more complex, multiple (#lglTemplateLayout *) structures may be needed.
  70 @markups: A list of (#lglTemplateMarkup *) structures, which represent non-printing markup lines.
  71
  72 <!-- ##### STRUCT lglTemplateFrameRect ##### -->
  73 <para>
  74 This structure defines the frame for a rectangular label or card.
  75 </para>
  76
  77 @shape: Common field.  Always #LGL_TEMPLATE_FRAME_SHAPE_RECT for #lglTemplateFrameRect.
  78 @id: Common field.  See #lglTemplateFrameAll.
  79 @layouts:  Common field.  See #lglTemplateFrameAll.
  80 @markups:  Common field.  See #lglTemplateFrameAll.
  81 @w: Width of label or card in points.
  82 @h: Height of label or card in points.
  83 @r: Radius of corners in points.
  84 @x_waste: Amount of horizontal over-print to allow in points.
  85 @y_waste: Amount of vertical over-print to allow in points.
  86
  87 <!-- ##### STRUCT lglTemplateFrameEllipse ##### -->
  88 <para>
  89 This structure defines the frame for an elliptical label or card.
  90 </para>
  91
  92 @shape: Common field.  Always #LGL_TEMPLATE_FRAME_SHAPE_ELLIPSE for #lglTemplateFrameEllipse.
  93 @id: Common field.  See #lglTemplateFrameAll.
  94 @layouts:  Common field.  See #lglTemplateFrameAll.
  95 @markups:  Common field.  See #lglTemplateFrameAll.
  96 @w: Width of label or card in points.
  97 @h: Height of label or card in points.
  98 @waste: Amount of over-print to allow in points.
  99
 100 <!-- ##### STRUCT lglTemplateFrameRound ##### -->
 101 <para>
 102 This structure defines the frame for a round label or card.
 103 </para>
 104
 105 @shape: Common field.  Always #LGL_TEMPLATE_FRAME_SHAPE_ROUND for #lglTemplateFrameRound.
 106 @id: Common field.  See #lglTemplateFrameAll.
 107 @layouts: Common field.  See #lglTemplateFrameAll.
 108 @markups: Common field.  See #lglTemplateFrameAll.
 109 @r: Radius of label or card in points.
 110 @waste: Amount of over-print to allow in points.
 111
 112 <!-- ##### STRUCT lglTemplateFrameCD ##### -->
 113 <para>
 114 This structure defines the frame for a CD or DVD label.  This structure also supports
 115 credit-card CD labels.
 116 </para>
 117
 118 @shape: Common field.  Always #LGL_TEMPLATE_FRAME_SHAPE_CD for #lglTemplateFrameCD.
 119 @id: Common field.  See #lglTemplateFrameAll.
 120 @layouts: Common field.  See #lglTemplateFrameAll.
 121 @markups: Common field.  See #lglTemplateFrameAll.
 122 @r1: Outer radius of label in points.
 123 @r2: Radius of center hole in points.
 124 @w: Clip width in points.  Used for credit-card CD labels.  This field is ignored if zero.
 125 @h: Clip height in points.  Used for credit-card CD labels.  This field is ignored if zero.
 126 @waste: Amount of over-print to allow in points.
 127
 128 <!-- ##### STRUCT lglTemplateLayout ##### -->
 129 <para>
 130 This structure defines a simple grid layout of labels or cards.
 131 </para>
 132
 133 @nx: Number of labels or cards across in the grid (horizontal).
 134 @ny: Number of labels or cards down in the grid (vertical).
 135 @x0: Distance (in points) from the left edge of page to the left edge of the left column of
 136 cards or labels in the layout.
 137 @y0: Distance (in points) from the top edge of page to the top edge of the top row of
 138 cards or labels in the layout.
 139 @dx: Horizontal pitch of grid in points.  This is the distance from left edge to left edge
 140 (not the gap between labels or cards).
 141 @dy: Vertical pitch of grid in points.  This is the distance from top edge to top edge
 142 (not the gap between labels or cards).
 143
 144 <!-- ##### ENUM lglTemplateMarkupType ##### -->
 145 <para>
 146 This enumeration defines markup types that are supported by libglabels
 147 </para>
 148
 149 @LGL_TEMPLATE_MARKUP_MARGIN: A margin line around perimeter of label or card.
 150 @LGL_TEMPLATE_MARKUP_LINE: A simple line segment.
 151 @LGL_TEMPLATE_MARKUP_CIRCLE: A circle.
 152 @LGL_TEMPLATE_MARKUP_RECT: A rectangle.  Possibly with rounded corners.
 153 @LGL_TEMPLATE_MARKUP_ELLIPSE: An ellipse.
 154
 155 <!-- ##### UNION lglTemplateMarkup ##### -->
 156 <para>
 157 A union of all possible markup structures.  The type of structure is indicated by the type
 158 member, which overlays the first field of all other member structures.
 159 </para>
 160
 161
 162 <!-- ##### STRUCT lglTemplateMarkupMargin ##### -->
 163 <para>
 164 This structure defines a simple margin markup around the perimeter of a label or card.
 165 </para>
 166
 167 @type: Common field.  Always #LGL_TEMPLATE_MARKUP_MARGIN for #lglTemplateMarkupMargin.
 168 @size: Distance of margin from edge of label or card.
 169
 170 <!-- ##### STRUCT lglTemplateMarkupLine ##### -->
 171 <para>
 172 This structure defines a simple line segment markup.
 173 </para>
 174
 175 @type: Common field.  Always #LGL_TEMPLATE_MARKUP_LINE for #lglTemplateMarkupLine.
 176 @x1: Distance (in points) of first endpoint from left edge of label or card.
 177 @y1: Distance (in points) of first endpoint from top edge of label or card.
 178 @x2: Distance (in points) of second endpoint from left edge of label or card.
 179 @y2: Distance (in points) of second endpoint from top edge of label or card.
 180
 181 <!-- ##### STRUCT lglTemplateMarkupCircle ##### -->
 182 <para>
 183 This structure defines a simple circle markup.
 184 </para>
 185
 186 @type: Common field.  Always #LGL_TEMPLATE_MARKUP_CIRCLE for #lglTemplateMarkupCircle.
 187 @x0: Distance (in points) of vertex from left edge of label or card.
 188 @y0: Distance (in points) of vertex from top edge of label or card.
 189 @r: Radius of circle in points.
 190
 191 <!-- ##### STRUCT lglTemplateMarkupRect ##### -->
 192 <para>
 193 This structure defines a simple rectangle markup.  The rectangle can have rounded corners.
 194 </para>
 195
 196 @type: Common field.  Always #LGL_TEMPLATE_MARKUP_RECT for #lglTemplateMarkupRect.
 197 @x1: Distance (in points) of left edge of markup from left edge of label or card.
 198 @y1: Distance (in points) of top edge of markup from top edge of label or card.
 199 @w: Width of rectangle in points.
 200 @h: Height of rectangle in points.
 201 @r: Radius of corners in points.  Should be zero for sharp corners.
 202
 203 <!-- ##### STRUCT lglTemplateMarkupEllipse ##### -->
 204 <para>
 205 This structure defines a simple elliptical markup.
 206 </para>
 207
 208 @type: Common field.  Always #LGL_TEMPLATE_MARKUP_ELLIPSE for #lglTemplateMarkupEllipse.
 209 @x1: Distance (in points) of left edge of markup from left edge of label or card.
 210 @y1: Distance (in points) of top edge of markup from top edge of label or card.
 211 @w: Width of rectangle in points.
 212 @h: Height of rectangle in points.
 213
 214 <!-- ##### STRUCT lglTemplateOrigin ##### -->
 215 <para>
 216 This structure represents the cartesian coordinates of the origin of a label or card on the page.
 217 The orign is the upper left corner of the extent of the label or card.  These coordinates are
 218 relative to the upper left corner of the page.
 219 </para>
 220
 221 @x: Distance in points from top edge of page.
 222 @y: Distance in points from left edge of page.
 223
 224 <!-- ##### FUNCTION lgl_template_new ##### -->
 225 <para>
 226
 227 </para>
 228
 229 @brand:
 230 @part:
 231 @description:
 232 @paper_id:
 233 @page_width:
 234 @page_height:
 235 @Returns:
 236
 237
 238 <!-- ##### FUNCTION lgl_template_new_from_equiv ##### -->
 239 <para>
 240
 241 </para>
 242
 243 @brand:
 244 @part:
 245 @equiv_part:
 246 @Returns:
 247
 248
 249 <!-- ##### FUNCTION lgl_template_dup ##### -->
 250 <para>
 251
 252 </para>
 253
 254 @orig_template:
 255 @Returns:
 256
 257
 258 <!-- ##### FUNCTION lgl_template_free ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @template:
 264
 265
 266 <!-- ##### FUNCTION lgl_template_add_category ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @template:
 272 @category_id:
 273
 274
 275 <!-- ##### FUNCTION lgl_template_add_frame ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @template:
 281 @frame:
 282
 283
 284 <!-- ##### FUNCTION lgl_template_get_name ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @template:
 290 @Returns:
 291
 292
 293 <!-- ##### FUNCTION lgl_template_do_templates_match ##### -->
 294 <para>
 295
 296 </para>
 297
 298 @template1:
 299 @template2:
 300 @Returns:
 301
 302
 303 <!-- ##### FUNCTION lgl_template_does_brand_match ##### -->
 304 <para>
 305
 306 </para>
 307
 308 @template:
 309 @brand:
 310 @Returns:
 311
 312
 313 <!-- ##### FUNCTION lgl_template_does_page_size_match ##### -->
 314 <para>
 315
 316 </para>
 317
 318 @template:
 319 @paper_id:
 320 @Returns:
 321
 322
 323 <!-- ##### FUNCTION lgl_template_does_category_match ##### -->
 324 <para>
 325
 326 </para>
 327
 328 @template:
 329 @category_id:
 330 @Returns:
 331
 332
 333 <!-- ##### FUNCTION lgl_template_are_templates_identical ##### -->
 334 <para>
 335
 336 </para>
 337
 338 @template1:
 339 @template2:
 340 @Returns:
 341
 342
 343 <!-- ##### FUNCTION lgl_template_frame_rect_new ##### -->
 344 <para>
 345
 346 </para>
 347
 348 @id:
 349 @w:
 350 @h:
 351 @r:
 352 @x_waste:
 353 @y_waste:
 354 @Returns:
 355
 356
 357 <!-- ##### FUNCTION lgl_template_frame_ellipse_new ##### -->
 358 <para>
 359
 360 </para>
 361
 362 @id:
 363 @w:
 364 @h:
 365 @waste:
 366 @Returns:
 367
 368
 369 <!-- ##### FUNCTION lgl_template_frame_round_new ##### -->
 370 <para>
 371
 372 </para>
 373
 374 @id:
 375 @r:
 376 @waste:
 377 @Returns:
 378
 379
 380 <!-- ##### FUNCTION lgl_template_frame_cd_new ##### -->
 381 <para>
 382
 383 </para>
 384
 385 @id:
 386 @r1:
 387 @r2:
 388 @w:
 389 @h:
 390 @waste:
 391 @Returns:
 392
 393
 394 <!-- ##### FUNCTION lgl_template_frame_dup ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @orig_frame:
 400 @Returns:
 401
 402
 403 <!-- ##### FUNCTION lgl_template_frame_free ##### -->
 404 <para>
 405
 406 </para>
 407
 408 @frame:
 409
 410
 411 <!-- ##### FUNCTION lgl_template_frame_add_layout ##### -->
 412 <para>
 413
 414 </para>
 415
 416 @frame:
 417 @layout:
 418
 419
 420 <!-- ##### FUNCTION lgl_template_frame_add_markup ##### -->
 421 <para>
 422
 423 </para>
 424
 425 @frame:
 426 @markup:
 427
 428
 429 <!-- ##### FUNCTION lgl_template_frame_get_size ##### -->
 430 <para>
 431
 432 </para>
 433
 434 @frame:
 435 @w:
 436 @h:
 437
 438
 439 <!-- ##### FUNCTION lgl_template_frame_get_n_labels ##### -->
 440 <para>
 441
 442 </para>
 443
 444 @frame:
 445 @Returns:
 446
 447
 448 <!-- ##### FUNCTION lgl_template_frame_get_origins ##### -->
 449 <para>
 450
 451 </para>
 452
 453 @frame:
 454 @Returns:
 455
 456
 457 <!-- ##### FUNCTION lgl_template_frame_get_layout_description ##### -->
 458 <para>
 459
 460 </para>
 461
 462 @frame:
 463 @Returns:
 464
 465
 466 <!-- ##### FUNCTION lgl_template_frame_get_size_description ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @frame:
 472 @units:
 473 @Returns:
 474
 475
 476 <!-- ##### FUNCTION lgl_template_layout_new ##### -->
 477 <para>
 478
 479 </para>
 480
 481 @nx:
 482 @ny:
 483 @x0:
 484 @y0:
 485 @dx:
 486 @dy:
 487 @Returns:
 488
 489
 490 <!-- ##### FUNCTION lgl_template_layout_dup ##### -->
 491 <para>
 492
 493 </para>
 494
 495 @orig_layout:
 496 @Returns:
 497
 498
 499 <!-- ##### FUNCTION lgl_template_layout_free ##### -->
 500 <para>
 501
 502 </para>
 503
 504 @layout:
 505
 506
 507 <!-- ##### FUNCTION lgl_template_markup_margin_new ##### -->
 508 <para>
 509
 510 </para>
 511
 512 @size:
 513 @Returns:
 514
 515
 516 <!-- ##### FUNCTION lgl_template_markup_line_new ##### -->
 517 <para>
 518
 519 </para>
 520
 521 @x1:
 522 @y1:
 523 @x2:
 524 @y2:
 525 @Returns:
 526
 527
 528 <!-- ##### FUNCTION lgl_template_markup_circle_new ##### -->
 529 <para>
 530
 531 </para>
 532
 533 @x0:
 534 @y0:
 535 @r:
 536 @Returns:
 537
 538
 539 <!-- ##### FUNCTION lgl_template_markup_rect_new ##### -->
 540 <para>
 541
 542 </para>
 543
 544 @x1:
 545 @y1:
 546 @w:
 547 @h:
 548 @r:
 549 @Returns:
 550
 551
 552 <!-- ##### FUNCTION lgl_template_markup_ellipse_new ##### -->
 553 <para>
 554
 555 </para>
 556
 557 @x1:
 558 @y1:
 559 @w:
 560 @h:
 561 @Returns:
 562
 563
 564 <!-- ##### FUNCTION lgl_template_markup_dup ##### -->
 565 <para>
 566
 567 </para>
 568
 569 @orig_markup:
 570 @Returns:
 571
 572
 573 <!-- ##### FUNCTION lgl_template_markup_free ##### -->
 574 <para>
 575
 576 </para>
 577
 578 @markup:
 579
 580
 581 <!-- ##### FUNCTION lgl_template_print ##### -->
 582 <para>
 583
 584 </para>
 585
 586 @template:
 587
 588