Seth/sethLabels
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

Merge branch 'RefactorPrint'

Browse Source 
- Modifies printing model to be similar to glabels-3.x.
   - Allow simple projects to print by-the-page (#51)
   - Added collated vs uncollated document merges
- Added ability to separate merge groups by page
- Updated man pages
- Updated misc developer documentation
This commit is contained in:
Jim Evins
2020-01-01 14:19:11 -05:00
parent af607ca4af
commit aebcda43cb
23 changed files with 1184 additions and 380 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PRODUCT-TEMPLATES.md
+107 -96
View File
@@ -20,10 +20,6 @@ Assumptions/caveats
A sheet contains only one size of label or card (if a sheet contains more than one size of item,
it can be split into multiple templates for multiple pass printing).
Distances can be expressed in units of *pt*, *in*, *mm*, *cm*, or *pc*. For example:
`"1.0in"` or `"2.54cm"`. If no units are specified, computer points (*pt*) will
be assumed (1 *pt* = 1/72 *in* = 0.352778 *mm*).
Template Files
--------------
@@ -57,22 +53,37 @@ An example template file containing a single *Template* node:
</Glabels-templates>
```
*Distance* Attributes
---------------------
A distance attribute is expressed as a number followed by a unit identifier.
Valid unit identifiers are *pt*, *in*, *mm*, *cm*, or *pc*. These are a subset of
the SVG absolute length units. Examples:
```xml
<Label-round radius="1.0in" >
<Label-round radius="2.54cm">
```
If no units are specified, computer points (*pt*) will be assumed (1 *pt* = 1/72 *in* = 0.352778 *mm*).
*Template* Node
---------------
A *Template* node describes a single stationery product. It must contain exactly one instance of
a label node, either *Label-rectangle*, *Label-round*, *Label-ellipse* or *Label-cd*.
Property | Description
---------------|------------
*brand* | Brand or manufacturer of stationery product. E.g. "Avery".
*part* | Part number or name of stationery product. E.g. "8160".
*size* | Paper size. Must match an ID defined in *paper-sizes.xml*, "roll" or "other". E.g. "A4".
*description* | Description of stationery product. E.g, "Mailing Labels".
*_description* | Translatable description of stationery product. Used in predefined labels instead of description.
*width* | Page width. Only valid if `size="other"` or `size="roll"`.
*height* | Page height. Only valid if `size="other"`. Value is ignored if `size="roll"`.
*equiv* | Equivalent part number. If this property is present, the template is a clone of another template of the same brand. The template will inherit all properties, except brand and name from the other template. This equiv property must refer to a previously defined template - *gLabels* does not currently support forward references.
Property | Type | Description
---------------|----------|------------
*brand* | string | Brand or manufacturer of stationery product. E.g. "Avery".
*part* | string | Part number or name of stationery product. E.g. "8160".
*size* | string | Paper size. Must match an ID defined in *paper-sizes.xml*, "roll" or "other". E.g. "A4".
*description* | string | Description of stationery product. E.g, "Mailing Labels".
*_description* | string | Translatable description of stationery product. Used in predefined labels instead of description.
*width* | distance | Page width. Only valid if `size="other"` or `size="roll"`.
*height* | distance | Page height. Only valid if `size="other"`. Value is ignored if `size="roll"`.
*equiv* | string | Equivalent part number. If this property is present, the template is a clone of another template of the same brand. The template will inherit all properties, except brand and name from the other template. This equiv property must refer to a previously defined template - *gLabels* does not currently support forward references.
### Guidelines for Creating Product Descriptions
@@ -90,10 +101,10 @@ If creating templates to be distributed with *gLabels*, please use the following
A *Meta* node contains some additional information about the template. A *Template* node may contain zero
or more *Meta* nodes. Only one property should be defined per *Meta* node.
Property | Description
--------------|------------
*category* | A category for the template. A template can belong to multiple categories by simply adding multiple *Meta* nodes to the parent *Template* node. The category must match an existing ID defined in categories.xml. E.g. `category="media"`
*product_url* | A URL pointing to the vendor's webpage for the specific product, if available.
Property | Type | Description
---------------|----------|------------
*category* | string | A category for the template. A template can belong to multiple categories by simply adding multiple *Meta* nodes to the parent *Template* node. The category must match an existing ID defined in categories.xml. E.g. `category="media"`
*product_url* | string | A URL pointing to the vendor's webpage for the specific product, if available.
*Label-rectangle* Node
@@ -102,14 +113,14 @@ Property | Description
A *Label-rectangle* node describes the dimensions of a single label or business card that is rectangular
in shape (may have rounded edges).
Property | Description
--------------|------------
*id* | Reserved for future use. Should always be 0.
*width* | Width of label or card. E.g. `width="29mm"`
*height* | Height of label or card. E.g. `height="100mm"`
*round* | Radius of corners. For items with square edges (business cards), the radius should be 0.
*x_waste* | Amount of horizontal waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
*y_waste* | Amount of vertical waste (over-print) to allow.
Property | Type | Description
---------------|----------|------------
*id* | integer | Reserved for future use. Should always be 0.
*width* | distance | Width of label or card. E.g. `width="29mm"`
*height* | distance | Height of label or card. E.g. `height="100mm"`
*round* | distance | Radius of corners. For items with square edges (business cards), the radius should be 0.
*x_waste* | distance | Amount of horizontal waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
*y_waste* | distance | Amount of vertical waste (over-print) to allow.
![Label-rectangle properties](images/glabels-template-rect-label.png)
@@ -120,12 +131,12 @@ Property | Description
A *Label-ellipse* node describes the dimensions of a single label or business card that is elliptical
in shape.
Property | Description
--------------|------------
*id* | Reserved for future use. Should always be 0.
*width* | Width of label or card. E.g. `width="29mm"`
*height* | Height of label or card. E.g. `height="100mm"`
*waste* | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
Property | Type | Description
---------------|----------|------------
*id* | integer | Reserved for future use. Should always be 0.
*width* | distance | Width of label or card. E.g. `width="29mm"`
*height* | distance | Height of label or card. E.g. `height="100mm"`
*waste* | distance | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
![Label-ellipse properties](images/glabels-template-ellipse-label.png)
@@ -135,11 +146,11 @@ Property | Description
A *Label-round* node describes the dimensions of a simple round label (not a CD).
Property | Description
--------------|------------
*id* | Reserved for future use. Should always be 0.
*radius* | Radius (1/2 diameter) of label or card. E.g. `radius="14.5mm"`
*waste* | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
Property | Type | Description
---------------|----------|------------
*id* | integer | Reserved for future use. Should always be 0.
*radius* | distance | Radius (1/2 diameter) of label or card. E.g. `radius="14.5mm"`
*waste* | distance | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
![Label-round properties](images/glabels-template-round-label.png)
@@ -149,14 +160,14 @@ Property | Description
A *Label-cd* node describes the dimensions of a CD, DVD, or business card CD.
Property | Description
--------------|------------
*id* | Reserved for future use. Should always be 0.
*radius* | Outer radius (1/2 diameter) of label. E.g. `radius="58.5mm"`
*hole* | Radius (1/2 diameter) of concentric hole. E.g. `hole="18mm"`
*width* | If present, the label is clipped to the given Width. (For use with business card CDs.)
*height* | If present, the label is clipped to the given height. (For use with business card CDs.)
*waste* | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
Property | Type | Description
---------------|----------|------------
*id* | integer | Reserved for future use. Should always be 0.
*radius* | distance | Outer radius (1/2 diameter) of label. E.g. `radius="58.5mm"`
*hole* | distance | Radius (1/2 diameter) of concentric hole. E.g. `hole="18mm"`
*width* | distance | If present, the label is clipped to the given Width. (For use with business card CDs.)
*height* | distance | If present, the label is clipped to the given height. (For use with business card CDs.)
*waste* | distance | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
![Label-cd properties](images/glabels-template-cd-label.png)
@@ -165,13 +176,13 @@ Property | Description
A *Label-continuous* node describes the dimensions of a single section of a continuous label tape.
Property | Description
--------------|------------
*id* | Reserved for future use. Should always be 0.
*width* | Width of label or card. E.g. `width="29mm"`
*min_height* | Minimum user defined height or length of label.
*max_height* | Maximum user defined height or length of label.
*derault_height* | Default user defined height or length of label.
Property | Type | Description
-----------------|----------|------------
*id* | integer | Reserved for future use. Should always be 0.
*width* | distance | Width of label or card. E.g. `width="29mm"`
*min_height* | distance | Minimum user defined height or length of label.
*max_height* | distance | Maximum user defined height or length of label.
*default_height* | distance | Default user defined height or length of label.
*Label-path* Node
@@ -179,13 +190,13 @@ Property | Description
A *Label-path* node describes the dimensions of a label with an outline defined by an arbitrary path.
Property | Description
--------------|------------
*id* | Reserved for future use. Should always be 0.
*d_units* | Units used in path definition. (default = `"pt"`)
*d* | Path definition. This is a subset of of the SVG path "d" attribute. Commands include "M/m", "L/l", "H/h", "V/v", and "Z/z". Commands and data must be delimited by white space."
*x_waste* | Amount of horizontal waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
*y_waste* | Amount of vertical waste (over-print) to allow.
Property | Type | Description
---------------|----------|------------
*id* | integer | Reserved for future use. Should always be 0.
*d_units* | string | Units used in path definition. Must be a supported distance unit identifier. (default = `"pt"`)
*d* | string | Path definition. This is a subset of of the SVG path "d" attribute. Commands include "M/m", "L/l", "H/h", "V/v", and "Z/z". Commands and data must be delimited by white space."
*x_waste* | distance | Amount of horizontal waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
*y_waste* | distance | Amount of vertical waste (over-print) to allow.
*Markup* Nodes
@@ -201,59 +212,59 @@ special areas, or other helpful hints to the user of a template.
A *Markup-margin* describes a margin along all edges of a label.
Property | Description
--------------|------------
*size* | Size of the margin. I.e. the distance of the margin line from the edge of the card/label.
*x_size* | Size of the margin in x dimension. I.e. the distance of the margin line from the edge of the card/label.
*y_size* | Size of the margin in y dimension. I.e. the distance of the margin line from the edge of the card/label.
Property | Type | Description
---------------|----------|------------
*size* | distance | Size of the margin. I.e. the distance of the margin line from the edge of the card/label.
*x_size* | distance | Size of the margin in x dimension. I.e. the distance of the margin line from the edge of the card/label.
*y_size* | distance | Size of the margin in y dimension. I.e. the distance of the margin line from the edge of the card/label.
### *Markup-line* Node
A *Markup-line* node describes a markup line.
Property | Description
--------------|------------
*x1* | X coordinate of 1st endpoint of the line segment.
*y1* | Y coordinate of 1st endpoint of the line segment.
*x2* | X coordinate of 2nd endpoint of the line segment.
*y2* | Y coordinate of 2nd endpoint of the line segment.
Property | Type | Description
---------------|----------|------------
*x1* | distance | X coordinate of 1st endpoint of the line segment.
*y1* | distance | Y coordinate of 1st endpoint of the line segment.
*x2* | distance | X coordinate of 2nd endpoint of the line segment.
*y2* | distance | Y coordinate of 2nd endpoint of the line segment.
### *Markup-circle* Node
A *Markup-circle* describes a markup circle.
Property | Description
--------------|------------
*x0* | X coordinate of circle origin (center).
*y0* | Y coordinate of circle origin (center).
*radius* | Radius of circle.
Property | Type | Description
---------------|----------|------------
*x0* | distance | X coordinate of circle origin (center).
*y0* | distance | Y coordinate of circle origin (center).
*radius* | distance | Radius of circle.
### *Markup-rect* Node
A *Markup-rect* describes a markup rectangle.
Property | Description
--------------|------------
*x1* | X coordinate of upper left corner of rectangle.
*y1* | Y coordinate of upper left corner of rectangle.
*w* | Width of rectangle.
*h* | Height of rectangle.
*r* | Radius of rounded corners of rectangle.
Property | Type | Description
---------------|----------|------------
*x1* | distance | X coordinate of upper left corner of rectangle.
*y1* | distance | Y coordinate of upper left corner of rectangle.
*w* | distance | Width of rectangle.
*h* | distance | Height of rectangle.
*r* | distance | Radius of rounded corners of rectangle.
### *Markup-ellipse* Node
A *Markup-ellipse* describes a markup ellipse.
Property | Description
--------------|------------
*x1* | X coordinate of upper left corner of ellipse bounding box.
*y1* | Y coordinate of upper left corner of ellipse bounding box.
*w* | Width of ellipse.
*h* | Height of ellipse.
Property | Type | Description
---------------|----------|------------
*x1* | distance | X coordinate of upper left corner of ellipse bounding box.
*y1* | distance | Y coordinate of upper left corner of ellipse bounding box.
*w* | distance | Width of ellipse.
*h* | distance | Height of ellipse.
*Layout* Node
@@ -282,13 +293,13 @@ with unique coordinates for the top left corner of that label.
> A single label can always be treated as a grid of one.
Property | Description
--------------|------------
*nx* | Number of labels/cards in the grid in the X direction (horizontal).
*ny* | Number of labels/cards in the grid in the Y direction (vertical).
*x0* | Distance from left edge of sheet to the left edge of the left column of cards/labels in the layout.
*y0* | Distance from the top edge of sheet to the top edge of the top row of labels/cards in the layout.
*dx* | Horizontal pitch of grid.
*dy* | Vertical pitch of grid.
Property | Type | Description
---------------|----------|------------
*nx* | integer | Number of labels/cards in the grid in the X direction (horizontal).
*ny* | integer | Number of labels/cards in the grid in the Y direction (vertical).
*x0* | distance | Distance from left edge of sheet to the left edge of the left column of cards/labels in the layout.
*y0* | distance | Distance from the top edge of sheet to the top edge of the top row of labels/cards in the layout.
*dx* | distance | Horizontal pitch of grid.
*dy* | distance | Vertical pitch of grid.
![Layout example](images/glabels-template-layout.png)
docs/README.md
+2 -1
View File
@@ -1,4 +1,5 @@
Developer Documentation Directory
=================================
This directory contains developer documentation. For user documentation, see [user-docs/](../user-docs).
This directory contains developer and installation documentation primarily for developers, packagers and other contributors.
For user documentation, see [user-docs/](../user-docs/_build).
docs/TODO.md
+55 -61
View File
@@ -1,80 +1,74 @@
To Do List for gLabels 4.0 -- 2019-10-07
========================================
Expose user variables to glabels-batch
--------------------------------------
There should be a way to set initial values of user variables from the glabels-batch
command line. Possibly even create them on the fly.
- [x] Expose user variables to glabels-batch
Add programmable margin to text objects
---------------------------------------
The current built-in fixed margin seems to confuse people when dealing with
different horizontal and vertical alignments.
There should be a way to set initial values of user variables from the glabels-batch
command line. Possibly even create them on the fly.
Improve print copies UI
-----------------------
As with previous versions of glabels, there should be a way of selecting
the number of sheets to print. Merge printing should be able to be collated
or not, and if printing multiple copies, start on the same first label.
- [x] Improve print copies UI
Printer calibration tool
------------------------
There desperately needs to be a printer calibration tool. At a minimum
the tool should allow adjusting horizontal and vertical offsets. The
adjustments should be unique to each printer.
As with previous versions of glabels, there should be a way of selecting
the number of sheets to print. Merge printing should be able to be collated
or not, and if printing multiple copies, start on the same first label.
I am thinking of a test page with a cross in the center. It would have a
grid around this cross, indicating how much to adjust x & y. The user
would fold the paper in quaters and use this grid to guestimate the offsets.
- [ ] Write help documentation
There should be warnings about how printers may drift from calibration or
even not have repeatable results.
- [x] Add "User Variables" feature
* A more sophisticated tool, could adjust for scaling and skew, but it would
be very difficult to interact with the user on these.
Add page to MainWindow to
- Define variables,
- Set their initial values
- Control how they might increment (per item instance, per item copy, per page)
Save as part of glabels project file
Write help documentation
------------------------
- [x] Add support for arbitrary label shapes
I.e. similar to an SVG path.
Completed List for gLabels 4.0 -- 2018-04-15
============================================
- [x] Add support for "Continuous Roll" labels
Add "User Variables" feature
----------------------------
If product template is for a continuous roll, define a mininum and default length.
This determines h and dy
* Add page to MainWindow to
- Define variables
- Set their initial values
- Control how they might increment (per item instance, per item copy, per page)
* Save as part of glabels project file
Add support for arbitrary label shapes
--------------------------------------
* I.e. similar to an SVG path.
Add support for "Continuous Roll" labels
----------------------------------------
* If product template is for a continuous roll, define a mininum and default length
- This determines h and dy
* Add option to Properties page to adjust this value
Add option to Properties page to adjust this value
To Do List for gLabels 4.1 -- 2019-03-17
========================================
To Do List for post gLabels 4.0 -- 2019-03-17
=============================================
- [ ] Create a "built-in" merge source
As an alternative to external merge sources, let the user edit the merge source
in situ. The user can add fields. The user can add records using those fields.
The user created database will become part of the glabels project file.
For simple databases, such as a small address list, this would be much easier
to deal with than creating it externally.
- [ ] Printer calibration tool
There desperately needs to be a printer calibration tool. At a minimum
the tool should allow adjusting horizontal and vertical offsets. The
adjustments should be unique to each printer.
I am thinking of a test page with a cross in the center. It would have a
grid around this cross, indicating how much to adjust x & y. The user
would fold the paper in quaters and use this grid to guestimate the offsets.
There should be warnings about how printers may drift from calibration or
even not have repeatable results.
A more sophisticated tool, could adjust for scaling and skew, but it would
be very difficult to interact with the user on these.
- [ ] Add programmable margin to text objects
The current built-in fixed margin seems to confuse people when dealing with
different horizontal and vertical alignments.
Create a "built-in" merge source
--------------------------------
As an alternative to external merge sources, let the user edit the merge source
in situ. The user can add fields. The user can add records using those fields.
The user created database will become part of the glabels project file.
For simple databases, such as a small address list, this would be much easier
to deal with than creating it externally.