mirror of
https://git.code.sf.net/p/zint/code
synced 2025-06-03 16:38:42 -04:00
- Add special symbology-specific escape sequences (Code 128 only)
for manual Code Set switching via `input_mode` flag `EXTRA_ESCAPE_MODE` (CLI `--extraesc`) (ticket #204) - GUI: disable "Reset" colour if default; add "Unset" to Printing Scale dialog (allows unsetting of X-dim/resolution settings without having to zap) - library: guard against out-of-bounds rows (negative) - test suite: fix some clang-tidy warnings; slight coverage improvements
This commit is contained in:
gitlost
parent
5669addf01
commit
6f7cdd660c
30 changed files with 649 additions and 285 deletions
Binary file not shown.
|
Before Width: | Height: | Size: 116 KiB After Width: | Height: | Size: 121 KiB |
|
|
@ -1,6 +1,6 @@
|
|||
% Zint Barcode Generator and Zint Barcode Studio User Manual
|
||||
% Version 2.12.0.9
|
||||
% December 2022
|
||||
% January 2023
|
||||
|
||||
# 1. Introduction
|
||||
|
||||
|
|
@ -81,6 +81,8 @@ GS1 data
|
|||
'chunks' of data, each of which starts with an Application Identifier (AI).
|
||||
The AI identifies what type of information is being encoded.
|
||||
|
||||
\clearpage
|
||||
|
||||
Reader Initialisation (Programming)
|
||||
|
||||
: Some symbologies allow a special character to be included which can be
|
||||
|
|
@ -516,6 +518,9 @@ Table: {#tbl:escape_sequences tag=": Escape Sequences"}
|
|||
codeset from U+0000 to U+D7FF and U+E000 to U+FFFF (i.e. excluding surrogates).
|
||||
Not to be confused with the Windows Bitmap file format BMP!
|
||||
|
||||
(Special escape sequences are available for Code 128 only to manually switch
|
||||
Code Sets - see [6.1.10.1 Standard Code 128 (ISO 15417)] for details.)
|
||||
|
||||
Input data can be read directly from file using the `-i` or `--input` switch as
|
||||
shown below. The input file is assumed to be UTF-8 formatted unless an
|
||||
alternative mode is selected. This command replaces the use of the `-d` switch.
|
||||
|
|
@ -1501,9 +1506,9 @@ you wish.
|
|||
## 5.1 Creating and Deleting Symbols
|
||||
|
||||
The symbols manipulated by Zint are held in a `zint_symbol` structure defined in
|
||||
`"zint.h"`. These symbols are created with the `ZBarcode_Create()` function and
|
||||
deleted using the `ZBarcode_Delete()` function. For example the following code
|
||||
creates and then deletes a symbol:
|
||||
`"zint.h"`. These symbol structures are created with the `ZBarcode_Create()`
|
||||
function and deleted using the `ZBarcode_Delete()` function. For example the
|
||||
following code creates and then deletes a symbol:
|
||||
|
||||
```c
|
||||
#include <zint.h>
|
||||
|
|
@ -2110,6 +2115,10 @@ Value Effect
|
|||
`FAST_MODE` Use faster if less optimal encodation or other shortcuts if
|
||||
available (affects `DATAMATRIX`, `MICROPDF417`, `PDF417`,
|
||||
`QRCODE` and `UPNQR` only).
|
||||
|
||||
`EXTRA_ESCAPE_MODE` Process special symbology-specific escape sequences
|
||||
(`CODE128` only).
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
Table: API `input_mode` Values {#tbl:api_input_mode tag="$ $"}
|
||||
|
|
@ -2118,8 +2127,8 @@ The default mode is `DATA_MODE`. (Note that this differs from the default for
|
|||
the CLI and GUI, which is `UNICODE_MODE`.)
|
||||
|
||||
`DATA_MODE`, `UNICODE_MODE` and `GS1_MODE` are mutually exclusive, whereas
|
||||
`ESCAPE_MODE`, `GS1PARENS_MODE`, `GS1NOCHECK_MODE`, `HEIGHTPERROW_MODE` and
|
||||
`FAST_MODE` are optional. So, for example, you can set
|
||||
`ESCAPE_MODE`, `GS1PARENS_MODE`, `GS1NOCHECK_MODE`, `HEIGHTPERROW_MODE`,
|
||||
`FAST_MODE` and `EXTRA_ESCAPE_MODE` are optional. So, for example, you can set
|
||||
|
||||
```c
|
||||
my_symbol->input_mode = UNICODE_MODE | ESCAPE_MODE;
|
||||
|
|
@ -2139,8 +2148,10 @@ my_symbol->input_mode = DATA_MODE | GS1_MODE;
|
|||
|
||||
is not valid.
|
||||
|
||||
Permissible escape sequences are listed in Table {@tbl:escape_sequences}. An
|
||||
example of `GS1PARENS_MODE` usage is given in section [6.1.10.3 GS1-128].
|
||||
Permissible escape sequences (`ESCAPE_MODE`) are listed in Table
|
||||
{@tbl:escape_sequences}, and the special Code 128-only `EXTRA_ESCAPE_MODE`
|
||||
escape sequences are given in [6.1.10.1 Standard Code 128 (ISO 15417)].
|
||||
An example of `GS1PARENS_MODE` usage is given in section [6.1.10.3 GS1-128].
|
||||
|
||||
`GS1NOCHECK_MODE` is for use with legacy systems that have data that does not
|
||||
conform to the current GS1 standard. Printable ASCII input is still checked for,
|
||||
|
|
@ -2151,6 +2162,10 @@ For `HEIGHTPERROW_MODE`, see `--heightperrow` in section [4.4 Adjusting Height].
|
|||
The `height` variable should be set to the desired per-row value on input (it
|
||||
will be set to the overall height on output).
|
||||
|
||||
`FAST_MODE` causes a less optimal encodation scheme to be used for Data Matrix,
|
||||
MicroPDF417 and PDF417. For QR Code and UPNQR, it affects Zint's automatic mask
|
||||
selection - see [6.6.3 QR Code (ISO 18004)] for details.
|
||||
|
||||
## 5.11 Multiple Segments
|
||||
|
||||
For input data requiring multiple ECIs, the following functions may be used:
|
||||
|
|
@ -2243,7 +2258,7 @@ my_symbol->dpmm = 600.0f / 25.4f; /* 600 dpi */
|
|||
my_symbol->scale = ZBarcode_Scale_From_XdimDp(
|
||||
my_symbol->symbology,
|
||||
ZBarcode_Default_Xdim(my_symbol->symbology),
|
||||
my_symbol->dpmm, "PNG"); /* 7.5 */
|
||||
my_symbol->dpmm, "PNG"); /* Returns 7.5 */
|
||||
```
|
||||
|
||||
The third function `ZBarcode_XdimDP_From_Scale()` is the "reverse" of
|
||||
|
|
@ -2488,7 +2503,6 @@ Identcode is based on Interleaved Code 2 of 5 and is used by Deutsche Post for
|
|||
identification purposes. Identcode requires an 11-digit numerical input to which
|
||||
Zint adds a check digit.
|
||||
|
||||
|
||||
\clearpage
|
||||
|
||||
### 6.1.3 UPC (Universal Product Code) (ISO 15420)
|
||||
|
|
@ -2784,8 +2798,28 @@ pharmaceuticals. The symbology is able to encode whole numbers between 3 and
|
|||
One of the most ubiquitous one-dimensional barcode symbologies, Code 128 was
|
||||
developed in 1981 by Computer Identics. This symbology supports full ASCII text
|
||||
and uses a three-Code Set system to compress the data into a smaller symbol.
|
||||
Zint automatically switches between Code Sets A, B and C and adds a modulo-103
|
||||
check digit.
|
||||
Zint automatically switches between Code Sets A, B and C (but see the special
|
||||
escapes below) and adds a modulo-103 check digit.
|
||||
|
||||
Manual switching of Code Sets is possible using the `--extraesc` option (API
|
||||
`input_mode |= EXTRA_ESCAPE_MODE`) and the Code 128-specific escapes `\^A`,
|
||||
`\^B`, `\^C`. For instance the following will force switching to Code Set B for
|
||||
the data `"5678"` (normally Code Set C would be used throughout):
|
||||
|
||||
```bash
|
||||
zint -b CODE128 -d "1234\^B5678" --extraesc
|
||||
```
|
||||
|
||||
The manually selected Code Set will apply until the next Code Set escape
|
||||
sequence, with the exception that data that cannot be represented in that Code
|
||||
Set will be switched as appropriate. If the data contains a special code
|
||||
sequence, it can be escaped by doubling the caret (`^`). For instance
|
||||
|
||||
```bash
|
||||
zint -b CODE128 -d "\^AABC\^^BDEF" --extraesc
|
||||
```
|
||||
|
||||
will encode the data `"ABC\^BDEF"` in Code Set A.
|
||||
|
||||
Code 128 is the default barcode symbology used by Zint. In addition Zint
|
||||
supports the encoding of ISO/IEC 8859-1 (non-English) characters in Code 128
|
||||
|
|
@ -2800,6 +2834,9 @@ It is sometimes advantageous to stop Code 128 from using Code Set C which
|
|||
compresses numerical data. The `BARCODE_CODE128AB`[^10] variant (symbology 60)
|
||||
suppresses Code Set C in favour of Code Sets A and B.
|
||||
|
||||
Note that the special escapes to manually switch Code Sets mentioned above are
|
||||
not available for this variant (nor for any other).
|
||||
|
||||
[^10]: `BARCODE_CODE128AB` previously used the name `BARCODE_CODE128B`, which is
|
||||
still recognised.
|
||||
|
||||
|
|
@ -2895,6 +2932,8 @@ A DPD Code can be marked as a "relabel" by specifying `--vers=1` (API
|
|||
`option_2 = 1`), which omits the identification tag and prints the barcode at
|
||||
half height. In this case, an input of 27 alphanumeric characters is required.
|
||||
|
||||
\clearpage
|
||||
|
||||
#### 6.1.10.8 UPU S10
|
||||
|
||||
|
||||
|
|
@ -3006,7 +3045,6 @@ input must be alphanumeric, excluding the letter `O`, and must be from 7 to 18
|
|||
characters in length. A single check character is added by Zint, appearing in
|
||||
the 2nd character position. Lowercase input is automatically made uppercase.
|
||||
|
||||
|
||||
\clearpage
|
||||
|
||||
## 6.2 Stacked Symbologies
|
||||
|
|
@ -4267,7 +4305,7 @@ maximum of 90 digits and does not include a check digit.
|
|||
|
||||
## 7.1 License
|
||||
|
||||
Zint, libzint and Zint Barcode Studio are Copyright © 2022 Robin Stuart. All
|
||||
Zint, libzint and Zint Barcode Studio are Copyright © 2023 Robin Stuart. All
|
||||
historical versions are distributed under the GNU General Public License
|
||||
version 3 or later. Versions 2.5 and later are released under a dual license:
|
||||
the encoding library is released under the BSD (3 clause) license whereas the
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
Zint Barcode Generator and Zint Barcode Studio User Manual
|
||||
Version 2.12.0.9
|
||||
December 2022
|
||||
January 2023
|
||||
|
||||
*******************************************************************************
|
||||
* For reference the following is a text-only version of the Zint manual, *
|
||||
|
|
@ -665,6 +665,9 @@ sequences are shown in the table below.
|
|||
|
||||
: Table : Escape Sequences:
|
||||
|
||||
(Special escape sequences are available for Code 128 only to manually switch
|
||||
Code Sets - see 6.1.10.1 Standard Code 128 (ISO 15417) for details.)
|
||||
|
||||
Input data can be read directly from file using the -i or --input switch as
|
||||
shown below. The input file is assumed to be UTF-8 formatted unless an
|
||||
alternative mode is selected. This command replaces the use of the -d switch.
|
||||
|
|
@ -1559,9 +1562,9 @@ wish.
|
|||
5.1 Creating and Deleting Symbols
|
||||
|
||||
The symbols manipulated by Zint are held in a zint_symbol structure defined in
|
||||
"zint.h". These symbols are created with the ZBarcode_Create() function and
|
||||
deleted using the ZBarcode_Delete() function. For example the following code
|
||||
creates and then deletes a symbol:
|
||||
"zint.h". These symbol structures are created with the ZBarcode_Create()
|
||||
function and deleted using the ZBarcode_Delete() function. For example the
|
||||
following code creates and then deletes a symbol:
|
||||
|
||||
#include <zint.h>
|
||||
#include <stdio.h>
|
||||
|
|
@ -2116,6 +2119,9 @@ property. Valid values are shown in the table below.
|
|||
FAST_MODE Use faster if less optimal encodation or other shortcuts if
|
||||
available (affects DATAMATRIX, MICROPDF417, PDF417, QRCODE
|
||||
and UPNQR only).
|
||||
|
||||
EXTRA_ESCAPE_MODE Process special symbology-specific escape sequences
|
||||
(CODE128 only).
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
: Table : API input_mode Values
|
||||
|
|
@ -2124,8 +2130,8 @@ The default mode is DATA_MODE. (Note that this differs from the default for the
|
|||
CLI and GUI, which is UNICODE_MODE.)
|
||||
|
||||
DATA_MODE, UNICODE_MODE and GS1_MODE are mutually exclusive, whereas
|
||||
ESCAPE_MODE, GS1PARENS_MODE, GS1NOCHECK_MODE, HEIGHTPERROW_MODE and FAST_MODE
|
||||
are optional. So, for example, you can set
|
||||
ESCAPE_MODE, GS1PARENS_MODE, GS1NOCHECK_MODE, HEIGHTPERROW_MODE, FAST_MODE and
|
||||
EXTRA_ESCAPE_MODE are optional. So, for example, you can set
|
||||
|
||||
my_symbol->input_mode = UNICODE_MODE | ESCAPE_MODE;
|
||||
|
||||
|
|
@ -2139,8 +2145,10 @@ whereas
|
|||
|
||||
is not valid.
|
||||
|
||||
Permissible escape sequences are listed in Table : Escape Sequences. An example
|
||||
of GS1PARENS_MODE usage is given in section 6.1.10.3 GS1-128.
|
||||
Permissible escape sequences (ESCAPE_MODE) are listed in Table
|
||||
: Escape Sequences, and the special Code 128-only EXTRA_ESCAPE_MODE escape
|
||||
sequences are given in 6.1.10.1 Standard Code 128 (ISO 15417). An example of
|
||||
GS1PARENS_MODE usage is given in section 6.1.10.3 GS1-128.
|
||||
|
||||
GS1NOCHECK_MODE is for use with legacy systems that have data that does not
|
||||
conform to the current GS1 standard. Printable ASCII input is still checked for,
|
||||
|
|
@ -2151,6 +2159,10 @@ For HEIGHTPERROW_MODE, see --heightperrow in section 4.4 Adjusting Height. The
|
|||
height variable should be set to the desired per-row value on input (it will be
|
||||
set to the overall height on output).
|
||||
|
||||
FAST_MODE causes a less optimal encodation scheme to be used for Data Matrix,
|
||||
MicroPDF417 and PDF417. For QR Code and UPNQR, it affects Zint’s automatic mask
|
||||
selection - see 6.6.3 QR Code (ISO 18004) for details.
|
||||
|
||||
5.11 Multiple Segments
|
||||
|
||||
For input data requiring multiple ECIs, the following functions may be used:
|
||||
|
|
@ -2234,7 +2246,7 @@ For example:
|
|||
my_symbol->scale = ZBarcode_Scale_From_XdimDp(
|
||||
my_symbol->symbology,
|
||||
ZBarcode_Default_Xdim(my_symbol->symbology),
|
||||
my_symbol->dpmm, "PNG"); /* 7.5 */
|
||||
my_symbol->dpmm, "PNG"); /* Returns 7.5 */
|
||||
|
||||
The third function ZBarcode_XdimDP_From_Scale() is the “reverse” of
|
||||
ZBarcode_Scale_From_XdimDp(), returning the X-dimension (in mm) or the dot
|
||||
|
|
@ -2736,8 +2748,24 @@ pharmaceuticals. The symbology is able to encode whole numbers between 3 and
|
|||
One of the most ubiquitous one-dimensional barcode symbologies, Code 128 was
|
||||
developed in 1981 by Computer Identics. This symbology supports full ASCII text
|
||||
and uses a three-Code Set system to compress the data into a smaller symbol.
|
||||
Zint automatically switches between Code Sets A, B and C and adds a modulo-103
|
||||
check digit.
|
||||
Zint automatically switches between Code Sets A, B and C (but see the special
|
||||
escapes below) and adds a modulo-103 check digit.
|
||||
|
||||
Manual switching of Code Sets is possible using the --extraesc option (API
|
||||
input_mode |= EXTRA_ESCAPE_MODE) and the Code 128-specific escapes \^A, \^B,
|
||||
\^C. For instance the following will force switching to Code Set B for the data
|
||||
"5678" (normally Code Set C would be used throughout):
|
||||
|
||||
zint -b CODE128 -d "1234\^B5678" --extraesc
|
||||
|
||||
The manually selected Code Set will apply until the next Code Set escape
|
||||
sequence, with the exception that data that cannot be represented in that Code
|
||||
Set will be switched as appropriate. If the data contains a special code
|
||||
sequence, it can be escaped by doubling the caret (^). For instance
|
||||
|
||||
zint -b CODE128 -d "\^AABC\^^BDEF" --extraesc
|
||||
|
||||
will encode the data "ABC\^BDEF" in Code Set A.
|
||||
|
||||
Code 128 is the default barcode symbology used by Zint. In addition Zint
|
||||
supports the encoding of ISO/IEC 8859-1 (non-English) characters in Code 128
|
||||
|
|
@ -2752,6 +2780,9 @@ It is sometimes advantageous to stop Code 128 from using Code Set C which
|
|||
compresses numerical data. The BARCODE_CODE128AB[10] variant (symbology 60)
|
||||
suppresses Code Set C in favour of Code Sets A and B.
|
||||
|
||||
Note that the special escapes to manually switch Code Sets mentioned above are
|
||||
not available for this variant (nor for any other).
|
||||
|
||||
6.1.10.3 GS1-128
|
||||
|
||||
[zint -b GS1_128 --compliantheight -d "[01]98898765432106[3202]012345[15]991231"]
|
||||
|
|
@ -4138,7 +4169,7 @@ maximum of 90 digits and does not include a check digit.
|
|||
|
||||
7.1 License
|
||||
|
||||
Zint, libzint and Zint Barcode Studio are Copyright © 2022 Robin Stuart. All
|
||||
Zint, libzint and Zint Barcode Studio are Copyright © 2023 Robin Stuart. All
|
||||
historical versions are distributed under the GNU General Public License version
|
||||
3 or later. Versions 2.5 and later are released under a dual license: the
|
||||
encoding library is released under the BSD (3 clause) license whereas the GUI,
|
||||
|
|
@ -4346,7 +4377,7 @@ defined.
|
|||
|
||||
Annex B. Man Page ZINT(1)
|
||||
|
||||
% ZINT(1) Version 2.12.0.9 % % December 2022
|
||||
% ZINT(1) Version 2.12.0.9 % % January 2023
|
||||
|
||||
NAME
|
||||
|
||||
|
|
@ -4514,6 +4545,12 @@ OPTIONS
|
|||
\UNNNNNN (U+NNNNNN) Any 21-bit Unicode character
|
||||
where NNNNNN is hexadecimal
|
||||
|
||||
--extraesc
|
||||
|
||||
Process the special escape sequences \^A, \^B and \^C that allow manual
|
||||
switching of Code Sets (Code 128 only). The sequence \^^ can be used to
|
||||
encode data that contains special escape sequences.
|
||||
|
||||
--fast
|
||||
|
||||
Use faster if less optimal encodation or other shortcuts (affects Data
|
||||
|
|
@ -4892,7 +4929,7 @@ AIM ITS/04-023 (2022)
|
|||
|
||||
COPYRIGHT
|
||||
|
||||
Copyright © 2022 Robin Stuart. Released under GNU GPL 3.0 or later.
|
||||
Copyright © 2023 Robin Stuart. Released under GNU GPL 3.0 or later.
|
||||
|
||||
AUTHOR
|
||||
|
||||
|
|
|
|||
11
docs/zint.1
11
docs/zint.1
|
|
@ -14,7 +14,7 @@
|
|||
. ftr VB CB
|
||||
. ftr VBI CBI
|
||||
.\}
|
||||
.TH "ZINT" "1" "December 2022" "Version 2.12.0.9" ""
|
||||
.TH "ZINT" "1" "January 2023" "Version 2.12.0.9" ""
|
||||
.hy
|
||||
.SH NAME
|
||||
.PP
|
||||
|
|
@ -199,6 +199,13 @@ The escape sequences are:
|
|||
.fi
|
||||
.RE
|
||||
.TP
|
||||
\f[V]--extraesc\f[R]
|
||||
Process the special escape sequences \f[V]\[rs]\[ha]A\f[R],
|
||||
\f[V]\[rs]\[ha]B\f[R] and \f[V]\[rs]\[ha]C\f[R] that allow manual
|
||||
switching of Code Sets (Code 128 only).
|
||||
The sequence \f[V]\[rs]\[ha]\[ha]\f[R] can be used to encode data that
|
||||
contains special escape sequences.
|
||||
.TP
|
||||
\f[V]--fast\f[R]
|
||||
Use faster if less optimal encodation or other shortcuts (affects Data
|
||||
Matrix, MicroPDF417, PDF417, QRCODE & UPNQR only).
|
||||
|
|
@ -627,7 +634,7 @@ ISO/IEC 16390:2007, ISO/IEC 16023:2000, ISO/IEC 24728:2006, ISO/IEC
|
|||
(2022)
|
||||
.SH COPYRIGHT
|
||||
.PP
|
||||
Copyright \[co] 2022 Robin Stuart.
|
||||
Copyright \[co] 2023 Robin Stuart.
|
||||
Released under GNU GPL 3.0 or later.
|
||||
.SH AUTHOR
|
||||
.PP
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
% ZINT(1) Version 2.12.0.9
|
||||
%
|
||||
% December 2022
|
||||
% January 2023
|
||||
|
||||
# NAME
|
||||
|
||||
|
|
@ -148,6 +148,11 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
|
|||
\UNNNNNN (U+NNNNNN) Any 21-bit Unicode character
|
||||
where NNNNNN is hexadecimal
|
||||
|
||||
`--extraesc`
|
||||
|
||||
: Process the special escape sequences `\^A`, `\^B` and `\^C` that allow manual switching of Code Sets (Code 128
|
||||
only). The sequence `\^^` can be used to encode data that contains special escape sequences.
|
||||
|
||||
`--fast`
|
||||
|
||||
: Use faster if less optimal encodation or other shortcuts (affects Data Matrix, MicroPDF417, PDF417, QRCODE & UPNQR
|
||||
|
|
@ -506,7 +511,7 @@ ISO/IEC 18004:2015, ISO/IEC 23941:2022, AIM ITS/04-023 (2022)
|
|||
|
||||
# COPYRIGHT
|
||||
|
||||
Copyright © 2022 Robin Stuart. Released under GNU GPL 3.0 or later.
|
||||
Copyright © 2023 Robin Stuart. Released under GNU GPL 3.0 or later.
|
||||
|
||||
# AUTHOR
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue