Mirrors/zint
1
0
Fork 0
mirror of https://git.code.sf.net/p/zint/code synced 2025-12-20 03:17:12 +00:00
Code Issues Projects Releases Wiki Activity

general: raw_segs -> content_segs, BARCODE_RAW_TEXT ->

Browse Source 
`BARCODE_CONTENT_SEGS`, `z_rt_XXX()` -> `z_ct_XXX()`;
  move `encoded_data`/`row_height` to end of `zint_symbol`
  (see ZXing-C++ issue #883)
manual: update re `content_segs`; `my_symbol` -> `symbol`;
  improve MicroPDF417 description
This commit is contained in:
gitlost
2025-11-04 23:02:10 +00:00
parent 543696cb06
commit f0c7248b62
82 changed files with 2203 additions and 2187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
docs/manual.pmd
View File

@@ -1,6 +1,6 @@
% Zint Barcode Generator and Zint Barcode Studio User Manual
% Version 2.15.0.9
% October 2025
% November 2025
# 1. Introduction
@@ -1270,7 +1270,7 @@ All others ASCII N/A
Table: Default Character Sets {#tbl:default_character_sets}
[^7]: Shift JIS (JIS X 0201 Roman) re-maps two ASCII characters: backslash (`\`)
to the yen sign (¥), and tilde (`~`) to overline (U+203E).
to the yen sign (`¥`), and tilde (`~`) to overline (`‾`, U+203E).
If Zint encounters characters which can not be encoded using the default
character encoding then it will take advantage of the ECI (Extended Channel
@@ -1618,7 +1618,7 @@ Grid Matrix, MaxiCode, MicroPDF417, PDF417, QR Code and Ultracode.
The `--structapp` option marks a symbol as part of a Structured Append sequence,
and has the format
```
```bash
--structapp=I,C[,ID]
```
@@ -1682,11 +1682,11 @@ following code creates and then deletes a symbol:
#include <stdio.h>
int main()
{
struct zint_symbol *my_symbol;
my_symbol = ZBarcode_Create();
if (my_symbol != NULL) {
struct zint_symbol *symbol;
symbol = ZBarcode_Create();
if (symbol != NULL) {
printf("Symbol successfully created!\n");
ZBarcode_Delete(my_symbol);
ZBarcode_Delete(symbol);
}
return 0;
}
@@ -1711,11 +1711,11 @@ the current working directory:
#include <zint.h>
int main(int argc, char **argv)
{
struct zint_symbol *my_symbol;
my_symbol = ZBarcode_Create();
ZBarcode_Encode(my_symbol, argv[1], 0);
ZBarcode_Print(my_symbol, 0);
ZBarcode_Delete(my_symbol);
struct zint_symbol *symbol;
symbol = ZBarcode_Create();
ZBarcode_Encode(symbol, argv[1], 0);
ZBarcode_Print(symbol, 0);
ZBarcode_Delete(symbol);
return 0;
}
```
@@ -1727,10 +1727,10 @@ function as shown in the next example:
#include <zint.h>
int main(int argc, char **argv)
{
struct zint_symbol *my_symbol;
my_symbol = ZBarcode_Create();
ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0);
ZBarcode_Delete(my_symbol);
struct zint_symbol *symbol;
symbol = ZBarcode_Create();
ZBarcode_Encode_and_Print(symbol, argv[1], 0, 0);
ZBarcode_Delete(symbol);
return 0;
}
```
@@ -1817,13 +1817,13 @@ client application:
```c
int row, col, i = 0, j = 0;
for (row = 0; row < my_symbol->bitmap_height; row++) {
for (col = 0; col < my_symbol->bitmap_width; col++) {
int red = (int) my_symbol->bitmap[i];
int green = (int) my_symbol->bitmap[i + 1];
int blue = (int) my_symbol->bitmap[i + 2];
if (my_symbol->alphamap) {
int alpha = (int) my_symbol->alphamap[j];
for (row = 0; row < symbol->bitmap_height; row++) {
for (col = 0; col < symbol->bitmap_width; col++) {
int red = (int) symbol->bitmap[i];
int green = (int) symbol->bitmap[i + 1];
int blue = (int) symbol->bitmap[i + 2];
if (symbol->alphamap) {
int alpha = (int) symbol->alphamap[j];
render_rgba(row, col, red, green, blue, alpha);
j++;
} else {
@@ -1845,9 +1845,9 @@ yellow, `'G'` for green, and `'K'` for black. Alpha values are not reported
```c
int row, col, i = 0;
for (row = 0; row < my_symbol->bitmap_height; row++) {
for (col = 0; col < my_symbol->bitmap_width; col++) {
render_pixel(row, col, my_symbol->bitmap[i]);
for (row = 0; row < symbol->bitmap_height; row++) {
for (col = 0; col < symbol->bitmap_width; col++) {
render_pixel(row, col, symbol->bitmap[i]);
i++;
}
}
@@ -1883,23 +1883,23 @@ struct zint_vector_hexagon *hex;
struct zint_vector_string *string;
struct zint_vector_circle *circle;
prepare_canvas(my_symbol->vector->width, my_symbol->vector->height,
my_symbol->scale, my_symbol->fgcolour, my_symbol->bgcolour,
prepare_canvas(symbol->vector->width, symbol->vector->height,
symbol->scale, symbol->fgcolour, symbol->bgcolour,
rotate_angle);
for (rect = my_symbol->vector->rectangles; rect; rect = rect->next) {
for (rect = symbol->vector->rectangles; rect; rect = rect->next) {
draw_rect(rect->x, rect->y, rect->width, rect->height,
rect->colour);
}
for (hex = my_symbol->vector->hexagons; hex; hex = hex->next) {
for (hex = symbol->vector->hexagons; hex; hex = hex->next) {
draw_hexagon(hex->x, hex->y, hex->diameter, hex->rotation);
}
for (string = my_symbol->vector->strings; string; string = string->next) {
for (string = symbol->vector->strings; string; string = string->next) {
draw_string(string->x, string->y, string->fsize,
string->rotation, string->halign,
string->text, string->length);
}
for (circle = my_symbol->vector->circles; circle; circle = circle->next) {
for (circle = symbol->vector->circles; circle; circle = circle->next) {
draw_circle(circle->x, circle->y, circle->diameter, circle->width);
}
```
@@ -1917,15 +1917,15 @@ length of the buffer is given in `memfile_size`. For instance:
#include <string.h>
int main(int argc, char **argv)
{
struct zint_symbol *my_symbol;
my_symbol = ZBarcode_Create();
my_symbol->output_options |= BARCODE_MEMORY_FILE;
struct zint_symbol *symbol;
symbol = ZBarcode_Create();
symbol->output_options |= BARCODE_MEMORY_FILE;
/* Only the extension is used, to determine output format */
strcpy(my_symbol->outfile, "mem.svg");
ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0);
/* `my_symbol->memfile` now contains the SVG output */
fwrite(my_symbol->memfile, 1, my_symbol->memfile_size, stdout);
ZBarcode_Delete(my_symbol);
strcpy(symbol->outfile, "mem.svg");
ZBarcode_Encode_and_Print(symbol, argv[1], 0, 0);
/* `symbol->memfile` now contains the SVG output */
fwrite(symbol->memfile, 1, symbol->memfile_size, stdout);
ZBarcode_Delete(symbol);
return 0;
}
@@ -2071,14 +2071,6 @@ Member Name Type Meaning Default Value
`width` integer Width of the generated (output only)
symbol.
`encoded_data` array of Representation of the (output only)
unsigned encoded data.
character
arrays
`row_height` array of Heights of each row. (output only)
floats
`errtxt` character Error message in the (output only)
string event that an error
occurred, with a
@@ -2122,13 +2114,22 @@ Member Name Type Meaning Default Value
`memfile_size` integer Length of in-memory file (output only)
buffer.
`raw_segs` pointer to Pointer to array of raw (output only)
array of segments if
segments `BARCODE_RAW_TEXT` set in
`output_options` - see
[5.16 Feedback].
`content_segs` pointer to Pointer to array of (output only)
array of content segments if
segments `BARCODE_CONTENT_SEGS`
set in `output_options`
- see [5.16 Feedback].
`raw_seg_count` integer Number of raw segments. (output only)
`content_seg_count` integer Number of content (output only)
segments.
`encoded_data` array of Representation of the (output only)
unsigned encoded data.
character
arrays
`row_height` array of Heights of each row. (output only)
floats
-----------------------------------------------------------------------------
Table: API Structure `zint_symbol` {#tbl:api_structure_zint_symbol}
@@ -2150,12 +2151,12 @@ plotted in green.
#include <string.h>
int main(int argc, char **argv)
{
struct zint_symbol *my_symbol;
my_symbol = ZBarcode_Create();
strcpy(my_symbol->fgcolour, "00ff00");
my_symbol->height = 400.0f;
ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0);
ZBarcode_Delete(my_symbol);
struct zint_symbol *symbol;
symbol = ZBarcode_Create();
strcpy(symbol->fgcolour, "00ff00");
symbol->height = 400.0f;
ZBarcode_Encode_and_Print(symbol, argv[1], 0, 0);
ZBarcode_Delete(symbol);
return 0;
}
```
@@ -2165,7 +2166,7 @@ setting the background alpha to `"00"` where the values for R, G and B will be
ignored:
```c
strcpy(my_symbol->bgcolour, "55555500");
strcpy(symbol->bgcolour, "55555500");
```
This is what the CLI option `--nobackground` does - see [4.7 Using Colour].
@@ -2252,23 +2253,23 @@ To catch errors use an integer variable as shown in the code below:
#include <string.h>
int main(int argc, char **argv)
{
struct zint_symbol *my_symbol;
struct zint_symbol *symbol;
int error;
my_symbol = ZBarcode_Create();
symbol = ZBarcode_Create();
/* Set invalid foreground colour */
strcpy(my_symbol->fgcolour, "nonsense");
error = ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0);
strcpy(symbol->fgcolour, "nonsense");
error = ZBarcode_Encode_and_Print(symbol, argv[1], 0, 0);
if (error != 0) {
/* Some warning or error occurred */
printf("%s\n", my_symbol->errtxt);
printf("%s\n", symbol->errtxt);
if (error >= ZINT_ERROR) {
/* Stop now */
ZBarcode_Delete(my_symbol);
ZBarcode_Delete(symbol);
return 1;
}
}
/* Otherwise carry on with the rest of the application */
ZBarcode_Delete(my_symbol);
ZBarcode_Delete(symbol);
return 0;
}
```
@@ -2297,7 +2298,7 @@ file. To select more than one option from the table below simply `OR` them
together when adjusting this value:
```c
my_symbol->output_options |= BARCODE_BIND | READER_INIT;
symbol->output_options |= BARCODE_BIND | READER_INIT;
```
------------------------------------------------------------------------------
@@ -2351,8 +2352,8 @@ Value Effect
`BARCODE_MEMORY_FILE` Write output to in-memory buffer `symbol->memfile`
instead of to `outfile` file.
`BARCODE_RAW_TEXT` Write data encoded to raw segment buffers
`symbol->raw_segs` (see [5.16 Feedback]).
`BARCODE_CONTENT_SEGS` Write data encoded to content segment buffers
`symbol->contentsegs` (see [5.16 Feedback]).
------------------------------------------------------------------------------
Table: API `output_options` Values {#tbl:api_output_options}
@@ -2420,19 +2421,19 @@ from the default for the CLI and GUI, which is `UNICODE_MODE`.)
for example, you can set
```c
my_symbol->input_mode = UNICODE_MODE | ESCAPE_MODE;
symbol->input_mode = UNICODE_MODE | ESCAPE_MODE;
```
or
```c
my_symbol->input_mode = GS1_MODE | GS1PARENS_MODE | GS1NOCHECK_MODE;
symbol->input_mode = GS1_MODE | GS1PARENS_MODE | GS1NOCHECK_MODE;
```
whereas
```c
my_symbol->input_mode = DATA_MODE | GS1_MODE;
symbol->input_mode = DATA_MODE | GS1_MODE;
```
is not valid.
@@ -2510,13 +2511,13 @@ int main(int argc, char **argv)
{ "Текст", 0, 7 },
{ "文章", 0, 20 }
};
struct zint_symbol *my_symbol;
my_symbol = ZBarcode_Create();
my_symbol->symbology = BARCODE_AZTEC;
my_symbol->input_mode = UNICODE_MODE;
ZBarcode_Encode_Segs(my_symbol, segs, 3);
ZBarcode_Print(my_symbol, 0);
ZBarcode_Delete(my_symbol);
struct zint_symbol *symbol;
symbol = ZBarcode_Create();
symbol->symbology = BARCODE_AZTEC;
symbol->input_mode = UNICODE_MODE;
ZBarcode_Encode_Segs(symbol, segs, 3);
ZBarcode_Print(symbol, 0);
ZBarcode_Delete(symbol);
return 0;
}
```
@@ -2552,12 +2553,12 @@ For example:
```c
/* Royal Mail 4-State Customer Code */
my_symbol->symbology = BARCODE_RM4SCC;
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"); /* Returns 7.5 */
symbol->symbology = BARCODE_RM4SCC;
symbol->dpmm = 600.0f / 25.4f; /* 600 dpi */
symbol->scale = ZBarcode_Scale_From_XdimDp(
symbol->symbology,
ZBarcode_Default_Xdim(symbol->symbology),
symbol->dpmm, "PNG"); /* Returns 7.5 */
```
The third function `ZBarcode_XdimDP_From_Scale()` is the "reverse" of
@@ -2701,10 +2702,11 @@ the addition of `0` meaning less than 5% + 3 codewords and `-1` meaning minimum
`P << 8`.
Detailed feedback on the data encoded may be requested by specifying the
`BARCODE_RAW_TEXT` option in the `output_options` member, which will populate
the `raw_segs` member with an array of `zint_seg` structures (see [5.12 Multiple
Segments] for the format), one for each segment specified, the size of the array
being set in `raw_seg_count` - which will always be at least one.
`BARCODE_CONTENT_SEGS` option in the `output_options` member, which will
populate the `content_segs` member with an array of `zint_seg` structures (see
[5.12 Multiple Segments] for the format), one for each segment specified, the
size of the array being set in `content_seg_count` - which will always be at
least one.
The `source`, `length` and `eci` members of `zint_seg` will be set accordingly -
the unconverted data in `source`, the data length in `length`, and the character
@@ -2921,9 +2923,9 @@ case Zint will verify the check digit, or you may use symbology
Input less than 11 digits will be zero-filled.
In addition 2-digit and 5-digit add-on symbols can be added, their data
separated from the main data by a `+` character or a space. For example, to draw
a UPC-A symbol with the data "72527270270" and 5-digit add-on data "12345" use
the command:
separated from the main data by a `'+'` character or a space. For example, to
draw a UPC-A symbol with the data "72527270270" and 5-digit add-on data "12345"
use the command:
```bash
zint -b UPCA -d "72527270270+12345"
@@ -2932,11 +2934,11 @@ zint -b UPCA -d "72527270270+12345"
or using the API:
```c
my_symbol->symbology = BARCODE_UPCA;
symbol->symbology = BARCODE_UPCA;
/* Using '+' */
error = ZBarcode_Encode_and_Print(my_symbol, "72527270270+12345", 0, 0);
error = ZBarcode_Encode_and_Print(symbol, "72527270270+12345", 0, 0);
/* Or a space */
error = ZBarcode_Encode_and_Print(my_symbol, "72527270270 12345", 0, 0);
error = ZBarcode_Encode_and_Print(symbol, "72527270270 12345", 0, 0);
```
![`zint -b UPCA --compliantheight -d
@@ -2953,9 +2955,9 @@ zint -b UPCA -d "72527270270+12345" --guardwhitespace
or using the API:
```c
my_symbol->symbology = BARCODE_UPCA;
my_symbol->output_options |= EANUPC_GUARD_WHITESPACE;
error = ZBarcode_Encode_and_Print(my_symbol, "72527270270+12345", 0, 0);
symbol->symbology = BARCODE_UPCA;
symbol->output_options |= EANUPC_GUARD_WHITESPACE;
error = ZBarcode_Encode_and_Print(symbol, "72527270270+12345", 0, 0);
```
![`zint -b UPCA --compliantheight -d "72527270270+12345"
@@ -2981,7 +2983,7 @@ An 8-digit input including the check digit may also be supplied, in which case
Zint will verify the check digit, or the symbology `BARCODE_UPCE_CHK` (38) may
be used, which will verify that the last digit is a check digit before encoding.
As with UPC-A, 2-digit and 5-digit add-on symbols can be added using a `+`
As with UPC-A, 2-digit and 5-digit add-on symbols can be added using a `'+'`
character or a space as a separator, and a quiet zone indicator can be added
when there is an add-on by setting `--guardwhitespace` (API `output_options |=
EANUPC_GUARD_WHITESPACE`):
@@ -3029,8 +3031,8 @@ will encode an EAN-13 symbol with a 2-digit add-on. As before these results
can be achieved using the API:
```c
my_symbol->symbology = BARCODE_EAN13;
error = ZBarcode_Encode_and_Print(my_symbol, "451234567890+21", 0, 0);
symbol->symbology = BARCODE_EAN13;
error = ZBarcode_Encode_and_Print(symbol, "451234567890+21", 0, 0);
```
![`zint -b EAN13 --compliantheight -d
@@ -3068,9 +3070,9 @@ zint -b EAN8 -d "7432365" --guardwhitespace
or using the API:
```c
my_symbol->symbology = BARCODE_EAN8;
my_symbol->output_options |= EANUPC_GUARD_WHITESPACE;
error = ZBarcode_Encode_and_Print(my_symbol, "7432365", 0, 0);
symbol->symbology = BARCODE_EAN8;
symbol->output_options |= EANUPC_GUARD_WHITESPACE;
error = ZBarcode_Encode_and_Print(symbol, "7432365", 0, 0);
```
![`zint -b EAN8 --compliantheight -d "7432365"`
@@ -3118,9 +3120,9 @@ will generate a standalone 5-digit add-on with quiet zone guards, or using the
API:
```c
my_symbol->symbology = BARCODE_EAN_5ADDON;
my_symbol->output_options |= EANUPC_GUARD_WHITESPACE;
error = ZBarcode_Encode_and_Print(my_symbol, "54321", 0, 0);
symbol->symbology = BARCODE_EAN_5ADDON;
symbol->output_options |= EANUPC_GUARD_WHITESPACE;
error = ZBarcode_Encode_and_Print(symbol, "54321", 0, 0);
```
![`zint -b EAN_5ADDON --compliantheight -d "54321"`
@@ -3608,10 +3610,10 @@ achieved using the API by executing the `ZBarcode_Encode()` function more than
once on a symbol. For example:
```c
my_symbol->symbology = BARCODE_CODE128;
error = ZBarcode_Encode(my_symbol, "This", 0);
error = ZBarcode_Encode(my_symbol, "That", 0);
error = ZBarcode_Print(my_symbol);
symbol->symbology = BARCODE_CODE128;
error = ZBarcode_Encode(symbol, "This", 0);
error = ZBarcode_Encode(symbol, "That", 0);
error = ZBarcode_Print(symbol);
```
![`zint -d "This" -d "That"`](images/code128_stacked.svg){.lin}
@@ -3711,11 +3713,12 @@ above.
### 6.2.6 MicroPDF417 (ISO 24728)
A variation of the PDF417 standard, MicroPDF417 is intended for applications
where symbol size needs to be kept to a minimum. 34 predefined symbol sizes are
available with 1 - 4 columns and 4 - 44 rows. The maximum amount a MicroPDF417
symbol can hold is 250 alphanumeric characters or 366 digits. The amount of
error correction used is dependent on symbol size. The number of columns used
can be determined using the `--cols` switch (API `option_2`) as with PDF417.
where symbol size needs to be kept to a minimum. Its size ranges over 1 - 4 data
columns and 4 - 44 rows. The maximum amount a MicroPDF417 symbol can hold is 250
alphanumeric characters or 366 digits. The amount of error correction used is
dependent on symbol size. The number of data columns used can be determined
using the `--cols` switch (API `option_2`) as with PDF417. The amount of data
determines the number of rows.
![`zint -b MICROPDF417 -d "12345678"`](images/micropdf417.svg){.lin}
@@ -3852,15 +3855,15 @@ CC-A (see [below][6.3.1 CC-A]) component with the data `"(99)1234-abcd"`. The
same results can be achieved using the API as shown below:
```c
my_symbol->symbology = BARCODE_EAN13_CC;
my_symbol->option_1 = 1;
strcpy(my_symbol->primary, "331234567890");
ZBarcode_Encode_and_Print(my_symbol, "[99]1234-abcd", 0, 0);
symbol->symbology = BARCODE_EAN13_CC;
symbol->option_1 = 1;
strcpy(symbol->primary, "331234567890");
ZBarcode_Encode_and_Print(symbol, "[99]1234-abcd", 0, 0);
```
2-digit and 5-digit add-on data can be used with EAN and UPC symbols using the
`+` character as described in sections [6.1.3 UPC (Universal Product Code) (ISO
15420)] and [6.1.4 EAN (European Article Number) (ISO 15420)].
`'+'` character as described in sections [6.1.3 UPC (Universal Product Code)
(ISO 15420)] and [6.1.4 EAN (European Article Number) (ISO 15420)].
The 2D component of a composite symbol can use one of three systems: CC-A, CC-B
and CC-C, as described below. The 2D component type can be selected