mirrors/zint
2
0
Fork 0
mirror of https://github.com/zint/zint synced 2024-11-16 20:57:25 +13:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update API documentation

Browse Source
This commit is contained in:
Robin Stuart 2016-10-22 10:05:27 +01:00
parent 82e7d197fd
commit e5f5aa7f9b
1 changed files with 66 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
docs/manual.txt
View File

@ -163,9 +163,11 @@ example
zint -d "This Text" zint -d "This Text"
This will encode the text "This Text". Zint will use the default symbology, This will encode the text "This Text". Zint will use the default symbology,
Code 128, and output to the default file out.png in the current directory. The Code 128, and output to the default file out.png in the current directory.
-d switch and the input data should always be the last entry on the command Alternatively, if libpng was not present when Zint was built, the default
line input. Any options given after this will be ignored. output file will be out.gif. The -d switch and the input data should always
be the last entry on the command line input. Any options given after this
will be ignored.
The data input to Zint is assumed to be encoded in Unicode (UTF-8) format. If The data input to Zint is assumed to be encoded in Unicode (UTF-8) format. If
you are encoding characters beyond the 7-bit ASCII set using a scheme other than you are encoding characters beyond the 7-bit ASCII set using a scheme other than
@ -269,6 +271,7 @@ Numeric Value | Barcode Name
70 | Royal Mail 4 State (RM4SCC) 70 | Royal Mail 4 State (RM4SCC)
71 | Data Matrix (ECC200) 71 | Data Matrix (ECC200)
72 | EAN-14 72 | EAN-14
74 | Codablock-F
75 | NVE-18 75 | NVE-18
76 | Japanese Postal Code 76 | Japanese Postal Code
77 | Korea Post 77 | Korea Post
@ -415,6 +418,7 @@ also available for Code 16k, Data Matrix, Aztec Code, DotCode and QR Code.
The --binary option prevents Zint from performing any convertion of the data The --binary option prevents Zint from performing any convertion of the data
before placing in the barcode symbol and should be used if you are encoding raw before placing in the barcode symbol and should be used if you are encoding raw
binary or encrypted data. binary or encrypted data.
If your platform does not use Unicode or if you are using data from file which If your platform does not use Unicode or if you are using data from file which
is not stored in UTF-8 then you can specify the encoding by using the --binary is not stored in UTF-8 then you can specify the encoding by using the --binary
switch in combination with the --eci= switch followed by the appropriate number switch in combination with the --eci= switch followed by the appropriate number
@ -612,7 +616,8 @@ gcc -o simple simple.c –lzint
To encode data in a barcode use the ZBarcode_Encode() function. To write the To encode data in a barcode use the ZBarcode_Encode() function. To write the
symbol to a file use the ZBarcode_Print() function. For example the following symbol to a file use the ZBarcode_Print() function. For example the following
code takes a string from the command line and outputs a Code 128 symbol in a code takes a string from the command line and outputs a Code 128 symbol in a
PNG file named out.png in the current working directory: PNG file named out.png (or a GIF file called out.gif if libpng is not present)
in the current working directory:
#include <stdio.h> #include <stdio.h>
#include <zint.h> #include <zint.h>
@ -640,7 +645,7 @@ int main(int argc, char **argv)
return 0; return 0;
} }
Input strings should be Unicode formatted. Input data should be Unicode (UTF-8) formatted.
5.3 Encoding and Printing Functions in Depth 5.3 Encoding and Printing Functions in Depth
-------------------------------------------- --------------------------------------------
@ -665,11 +670,11 @@ symbologies which allow this. A value of 0 will disable this function and Zint
will encode data up to the first NULL character in the input string. will encode data up to the first NULL character in the input string.
The "rotate_angle" value can be used to rotate the image when outputting as a The "rotate_angle" value can be used to rotate the image when outputting as a
PNG image. Valid values are 0, 90, 180 and 270. raster image. Valid values are 0, 90, 180 and 270.
The ZBarcode_Encode_File() and ZBarcode_Encode_File_and_Print() functions can The ZBarcode_Encode_File() and ZBarcode_Encode_File_and_Print() functions can
be used to encode data read directly from a file where the filename is given in be used to encode data read directly from a text file where the filename is given
the "filename" string. in the "filename" string.
5.4 Buffering Symbols in Memory 5.4 Buffering Symbols in Memory
------------------------------- -------------------------------
@ -690,15 +695,29 @@ saving the image to file it is placed in a character array. The "bitmap"
pointer is set to the first memory location in the array and the values pointer is set to the first memory location in the array and the values
"barcode_width" and "barcode_height" indicate the size of the resulting image "barcode_width" and "barcode_height" indicate the size of the resulting image
in pixels. Rotation and colour options can be used at the same time as using in pixels. Rotation and colour options can be used at the same time as using
the buffer functions in the same way as when saving to a PNG image. The bitmap the buffer functions in the same way as when saving to a raster image. The
is held in memory using the structure defined for the Windows bitmap (BMP) pixel data can be extracted from the character array by the methd shown in
format. the example below where render_pixel() is assumed to be a function for drawing
a pixel on the screen implemented by the external application:
int row, col, i = 0;
int red, blue, green;
for (row = 0; row < my_symbol->bitmap_height; row++) {
for (column = 0; column < my_symbol->bitmap_width; column++) {
red = my_symbol->bitmap[i];
green = my_symbol->bitmap[i + 1];
blue = my_symbol->bitmap[i + 2];
render_pixel(row, column, red, green, blue);
i += 3;
}
}
5.5 Setting Options 5.5 Setting Options
------------------- -------------------
So far our application is not very useful unless we plan to only make Code 128 So far our application is not very useful unless we plan to only make Code 128
barcodes and we don't mind that they only save to out.png. As with the front symbols and we don't mind that they only save to out.png. As with the CLI
end program, of course, these options can be altered. The way this is done is program, of course, these options can be altered. The way this is done is
by altering the contents of the zint_symbol structure between the creation and by altering the contents of the zint_symbol structure between the creation and
encoding stages. The zint_symbol structure consists of the following variables: encoding stages. The zint_symbol structure consists of the following variables:
@ -710,8 +729,9 @@ symbology | integer | Symbol to use (see section | BARCODE_CODE128
height | integer | Symbol height. [1] | 50 height | integer | Symbol height. [1] | 50
whitespace_width | integer | Whtespace width. | 0 whitespace_width | integer | Whtespace width. | 0
border_width | integer | Border width. | 0 border_width | integer | Border width. | 0
output_options | integer | Binding or box parameters | (none) output_options | integer | Set various output file | (none)
| | (see section 5.8). [2] | | | parameters (see section |
| | 5.8). [2] |
fgcolour | character | Foreground (ink) colour as | "000000" fgcolour | character | Foreground (ink) colour as | "000000"
| string | RGB hexadecimal string. | | string | RGB hexadecimal string. |
| | Must be 6 characters | | | Must be 6 characters |
@ -726,7 +746,7 @@ outfile | character | Contains the name of the | "out.png"
| string | file to output a result- | | string | file to output a result- |
| | ing barcode symbol to. | | | ing barcode symbol to. |
| | Must end in .png, .gif, | | | Must end in .png, .gif, |
| | .eps, .pcx or .svg | | | .eps, .pcx, .svg or .txt |
option_1 | integer | Symbol specific options. | (automatic) option_1 | integer | Symbol specific options. | (automatic)
option_2 | integer | Symbol specific options. | (automatic) option_2 | integer | Symbol specific options. | (automatic)
option_3 | integer | Symbol specific options. | (automatic) option_3 | integer | Symbol specific options. | (automatic)
@ -743,6 +763,9 @@ text | unsigned | Human readable text, which | NULL
| string | put data plus one more | | string | put data plus one more |
| | check digit. Uses UTF-8 | | | check digit. Uses UTF-8 |
| | formatting. | | | formatting. |
show_hrt | integer | Set to 0 to hide text. | 1
dot_size | float | Size of dots used in dotty | 4.0 / 5.0
| | mode. |
rows | integer | Number of rows used by the | (output only) rows | integer | Number of rows used by the | (output only)
| | the symbol. | | | the symbol. |
width | integer | Width of the generated sym- | (output only) width | integer | Width of the generated sym- | (output only)
@ -794,6 +817,9 @@ ZINT_WARN_INVALID_OPTION | One of the values in zint_struct was set
| incorrectly but Zint has made a guess at | incorrectly but Zint has made a guess at
| what it should have been and generated a | what it should have been and generated a
| barcode accordingly. | barcode accordingly.
ZINT_WARN_USES_ECI | Zint has automatically inserted an ECI
| character. The symbol may not be readable
| with some readers.
ZINT_ERROR_TOO_LONG | The input data is too long or too short for the ZINT_ERROR_TOO_LONG | The input data is too long or too short for the
| selected symbology. No symbol has been | selected symbology. No symbol has been
| generated. | generated.
@ -909,6 +935,7 @@ Value |
70 | BARCODE_RM4SCC | Royal Mail 4 State (RM4SCC) 70 | BARCODE_RM4SCC | Royal Mail 4 State (RM4SCC)
71 | BARCODE_DATAMATRIX | Data Matrix ECC200 71 | BARCODE_DATAMATRIX | Data Matrix ECC200
72 | BARCODE_EAN14 | EAN-14 72 | BARCODE_EAN14 | EAN-14
74 | BARCODE_CODABLOCKF | Codablock-F
75 | BARCODE_NVE18 | NVE-18 75 | BARCODE_NVE18 | NVE-18
76 | BARCODE_JAPANPOST | Japanese Postal Code 76 | BARCODE_JAPANPOST | Japanese Postal Code
77 | BARCODE_KOREAPOST | Korea Post 77 | BARCODE_KOREAPOST | Korea Post
@ -958,20 +985,29 @@ Value |
142 | BARCODE_GRIDMATRIX | Grid Matrix 142 | BARCODE_GRIDMATRIX | Grid Matrix
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
5.8 Adding Boxes and Boundary Bars 5.8 Adjusting other output options
---------------------------------- ----------------------------------
Boxes and boundary bars are handled using the output_options variable in the The output_options variable can be used to adjust various aspects of the output
file. To select more than one option from the table below simply add them together
when adjusting this value:
zint_symbol structure. To use this option simply assign a value to the my_symbol->output_options += BARCODE_BIND + READER_INIT;
output_options variable from the following table [2].
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
Value | Effect Value | Effect
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
0 | No box or boundary bars. 0 | No options selected.
BARCODE_BIND | Boundary bars above and below the symbol and between rows if BARCODE_BIND | Boundary bars above and below the symbol and between
| stacking multiple symbols. | rows if stacking multiple symbols. [2]
BARCODE_BOX | Add a box surrounding the symbol and whitespace. BARCODE_BOX | Add a box surrounding the symbol and whitespace. [2]
BARCODE_STDOUT | Output the file to stdout.
READER_INIT | Add a reader initialisation symbol to the data before
| encoding.
SMALL_TEXT | Use a smaller font for the human readable text.
BOLD_TEXT | Embolden the human readable text.
CMYK_COLOUR | Select the CMYK colour space option for encapsulated
| PostScript files.
BARCODE_DOTTY_MODE | Plot a matrix symbol using dots rather than squares.
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
5.9 Setting the Input Mode 5.9 Setting the Input Mode
@ -1007,7 +1043,7 @@ if(ZBarcode_ValidID(BARCODE_PDF417) != 0) {
USPS OneCode, RM4SCC, PDF417, Data Matrix ECC200, Maxicode, QR Code, GS1 USPS OneCode, RM4SCC, PDF417, Data Matrix ECC200, Maxicode, QR Code, GS1
DataBar-14 Stacked, PDF417 and MicroPDF417 - all of which have a fixed height. DataBar-14 Stacked, PDF417 and MicroPDF417 - all of which have a fixed height.
[2] This value is ignored for Code 16k and ITF-14 symbols. [2] This value is ignored for Code 16k, Codablock-F and ITF-14 symbols.
6. Types of Symbology 6. Types of Symbology
===================== =====================