Softmatic .NET Barcode Library - Manual & Reference
The Softmatic Barcode Library .NET Barcode Library creates all common linear and 2D barcode symbologies. The library is very easy to use, yet it is fast and lightweight at only 220 kB. The library can be used on a form like any other user control or window-less in pure DLL mode, for example in an ASP server application. - Please note that this library can not be used to read or decode barcodes.Installation and Setup
-
System Requirements: Visual Studio 2005, Visual Studio Express 2005, Visual Studio 2008, Visual Studio 2010 or any
other .NET 2.0 compatible environment. Library as shipped is compiled against the .NET 2.0 framework. It has been
tested to work with .NET 2.0, .NET 3.0, .NET 3.5. The supplied sample project requires Visual Studio 2008 or higher.
-
A dedicated installation is not required. For use on a form you can add the barcode control to your
Visual Studio toolbox directly from the downloaded ZIP file.
In VS select menu Tools > Choose Toolbox Items.
Click the Browse... button and navigate to the Library folder.
Select the file Softmatic.Barcode Library NET.dll and click Open. The control will be listed in the toolbox (Initially the control will be placed at the end of the list; simply drag it to where you want or right click and have the list sorted alphabetically.)
The Sample Projects
We've provided two ready-to-compile sample projects in C# and Visual Basic .NET. You find the samples in the Sample Project C# and Sample Project VB folders. For your convenience, we also provide pre-compiled, ready-to-run binaries of the samples, you find them in the bin\Debug folder of the respective sample.The samples are simple Windows Forms applications that expose some of the control's properties to the user; the end result looks like this:
The relevant parts of the sample source code are commented to give you a starting point.
Reference
Properties (in alphabetical order, read-only properties are in orange)| Name | Type | Comment | ||||||||||||||||||||||||||||||||||||
| General | ||||||||||||||||||||||||||||||||||||||
| Checksum | Boolean |
False: Don't calculate checksum. True: Calculate checksum.
Applies only to the following codes: Code 39, Code 2/5 Interleaved, Code 2/5 Industrial. Ignored for all other codes which are either always without (Codabar, PZN, Laetus) or always with checksum (all others). Default: True |
||||||||||||||||||||||||||||||||||||
| CurrentCode | Integer |
The current barcode symbology.
Default: CODE_EAN13 Note: When setting the code type to Databar you must also set the DatabarSubType property, see below. |
||||||||||||||||||||||||||||||||||||
| DataToEncode | String |
Data to encode in the barcode. String can have up to 4096 characters (the practical limit for ordinary linear codes is 40, though).
See section below for a list what the control expects for the various symbologies.
To encode non-printable charaters, e.g. a TAB, use the tilde, followed by the ASCII code, left padded with "0" to three digits. E.g. to encode a TAB, write "~009". To encode an FNC1 character (if you want to assemble your own Code 128 GS1 symbols), write "~999". To encode a tilde, write "~0126". Note: When encoding non-printable characters make sure your scanner can actually read and transmit such data - this is not a given, especially if the scanner emulates a keyboard, e.g. via a wedge or USB. In many cases you will need to use a scanner that is connected via the serial port. Default: "401234567890" |
||||||||||||||||||||||||||||||||||||
| ModuleHeight | Float |
Height of the barcode in mm. Ignored for EAN Family barcodes (see CurrentEANSize property below), Databar GS1, and 2D matrix symbologies.
The smallest acceptable value depends on the application, values under 8 mm should be avoided, for Code 128 GS1 the value should be 32 mm. Default: 25 mm |
||||||||||||||||||||||||||||||||||||
| ModuleWidth | Float |
Width of the smallest bar (= module) in mm. Ignored for EAN Family barcodes (see CurrentEANSize property below).
The smallest acceptable value depends on the print resolution, avoid values under 0.1 mm. For Databar GS1 and Code 128 GS1 the value should be between 0.495 and 1.016 mm. Default: 0.5 mm |
||||||||||||||||||||||||||||||||||||
| Ratio | Float |
Ratio of the width of the wide bar to the width of the narrow bar. For 2-width codes (Code 39, Code 2/5) only. Ignored for
all other codes.
The smallest acceptable value depends on the print quality and the resolution of the scanner; a ratio of 3 results in a low-density code, a ratio of 2 results in a high-density code. Values under 2 should be avoided. Default: 3 |
||||||||||||||||||||||||||||||||||||
| Human Readable Part | ||||||||||||||||||||||||||||||||||||||
| HumanReadable | Boolean |
Display human readable text under the barcode. Ignored for all 2D symbologies and ISBN family. ISBN barcodes
are standardized and always come with text.
Default: True |
||||||||||||||||||||||||||||||||||||
| HumanReadableFont | String |
Name of the font to use for the human readable text.
Default: "Arial" |
||||||||||||||||||||||||||||||||||||
| HumanReadableSize | Float |
Size of the font for the human readable text in points. Ignored for EAN Family codes where the font size
depends on the code size.
Default: 12 pt. |
||||||||||||||||||||||||||||||||||||
| License | ||||||||||||||||||||||||||||||||||||||
| License | String |
The license of the control. Will return build date, version and expiry date for the library.
Default: n/a |
||||||||||||||||||||||||||||||||||||
| Output | ||||||||||||||||||||||||||||||||||||||
| MarginX | Float |
Left and right margin of the barcode. Should not be under 5 mm.
Default: 5 mm |
||||||||||||||||||||||||||||||||||||
| MarginY | Float |
Top and bottom margin of the barcode. Should not be under 5 mm.
Default: 5 mm |
||||||||||||||||||||||||||||||||||||
| Reduction | Float |
Reduce bar width to compensate for ink spread (dot gain). Between 0% and 80%. For ordinary office laser printers
a value of 10% is recommended.
Default: 0 % |
||||||||||||||||||||||||||||||||||||
| EPS | String |
A string containing the EPS (Encapsulated PostScript) representation of the barcode.
Returns an empty string in the free version of the library.
Default: n/a |
||||||||||||||||||||||||||||||||||||
| Specific (EAN) | ||||||||||||||||||||||||||||||||||||||
| CurrentEANReduce | Float |
Reduce the height of an EAN symbol. Between 0% (no height reduction) and 80%.
Default: 0 % |
||||||||||||||||||||||||||||||||||||
| CurrentEANSize | Int |
Required EAN SC size. Between 0 (circa 81%) and 9 (200%). A value of 2 corresponds to the 100% SC 2 size with a module width of 0.33mm.
Default: 2 |
||||||||||||||||||||||||||||||||||||
| Specific (Databar GS1) | ||||||||||||||||||||||||||||||||||||||
| DatabarSubType | Int |
The Databar sub type.
Default: GS1_DB_EXPANDED |
||||||||||||||||||||||||||||||||||||
| SymbolsPerRow | Int |
Symbols per Row for Databar GS1 Expanded Stacked. Value must be an even number between 4 and 20. (Everything higher than 8 results
in barcodes that are too wide for most practical purposes)
Default: 4 |
||||||||||||||||||||||||||||||||||||
| Specific (ISBN) | ||||||||||||||||||||||||||||||||||||||
| Addon | String |
Text for ISBN addon satellite barcode. Must be 5 digits or empty (= no addon).
Default: "90000" |
||||||||||||||||||||||||||||||||||||
| Specific (PDF417) | ||||||||||||||||||||||||||||||||||||||
| RequestCols | Int |
Per default (RequestCols = -1) the control will create a PDF417 symbol that is roughly 3:2 (width : height) as recommended
by the ISO standard. Specify the desired number of columns (between 3 and 30) if you require a different size.
Default: -1 |
||||||||||||||||||||||||||||||||||||
| Specific (QR) | ||||||||||||||||||||||||||||||||||||||
| QrECC | Int |
Per default the control creates a Quality M QR code (medium error correction capacity) as this gives the best compromise
between size and ECC capability. Values permitted:
0 Quality M (recommended) 1 Quality L (least) 2 Quality H 3 Quality Q (best) Default: 0 |
Methods
| Name | Parameter | Comment |
| GetCode | Float dpi |
Creates a barcode, returns a Bitmap with the code. The dpi parameter determines the output resolution, e.g. 300 for 300 dpi.
The actual dimensions of the barcode (and, hence, the returned bitmap) are determined from the moduleHeight, moduleWidth and the encoded data.
Max. permitted value: 1200.
Returns: Bitmap |
| Init | void |
Must be called before the first use of the control. Resets all properties to the defaults as described in this document.
Returns: void |
More on DataToEncode
-
EAN 8: Enter 7 or 8 digits, the library will always create a checksum, discarding the 8th
digit if necessary.
-
EAN 13: Enter 12 or 13 digits, the library will always create a checksum, discarding the
13th digit if necessary. Enter 2 or 5 digits for the add-on or leave empty.
-
UPC-A: Enter 11 or 12 digits, the library will always create a checksum, discarding the
12th digit if necessary.
-
UPC-E: Enter 7 or 8 digits, the library will always create a checksum, discarding the 8th
digit if necessary. The number must start with a "0" or "1".
-
ISBN-10: Enter 10 digits, e.g. 1-12345-123-X. The software will prepend 978 and calcu-
late the proper checksum.
-
ISBN-13: Enter 13 digits, e.g. 978-1-12345-123-8. The software will in any case recalcu-
late the proper checksum.
-
Code 128: Enter up to 40 characters, the full ASCII set is permitted. Encode non-
printable characters (e.g. a TAB) by a tilde, followed by the three-digit ASCII code, e.g.
"~009".
-
Code 128 GS1: Enter up to 40 characters, the full ASCII set is permitted. Encode non-
printable characters (e.g. a TAB) by a tilde, followed by the three-digit ASCII code, e.g.
"~009". Indicate field identifiers by parentheses, e.g. "(00)1234(10)123". The software
knows all fixed and variable length identifiers and will append an FNC1 to variable
fields as required.
-
Code 39: Enter up to 40 characters, the full ASCII set is permitted, the control
switches to Code 39 Extended automatically if so required. Encode non-
printable characters (e.g. a TAB) by a tilde, followed by the three-digit ASCII code, e.g.
"~009".
-
Code PZN: Enter exactly 7 digits, the control will provide the hyphen and the "PZN" text.
Set check digit to false.
-
Code Laetus: Enter a numerical value of up to 131070.
-
Code 2/5: Enter up to 40 digits 0-9.
-
Codabar: Enter up to 40 characters, digits 0-9, special characters "-", "$", ":", "/", ".",
"+". Use "A", "B", "C", or "D" as start stop characters, e.g. "A12345D".
-
2D Barcodes: Enter up to 4,000 characters (numbers and letters). The actual amount of data that can be
encoded depends on the kind of data and the symbology used. Encode non-printable
characters (e.g. a TAB) by a tilde, followed by the three-digit ASCII code, e.g. "~009".
- Databar GS1
- Omnidirectional, Omnidirectional Stacked, Truncated, Stacked, Limited
Expects a purely numeric 14-digit GTIN. Must not contain application identifiers, hyphens, blanks, letters. If you have a 13-digit GTIN, i.e. a GTIN without the check digit, this is ok as well as the check digit is not encoded into the barcode anyway.
- Expanded, Expanded Stacked
Expects the complete data string with all parentheses and application identifiers (AI), e.g. "(01)12345678901234". Make sure not to have spaces or tabs or carriage returns between the AIs and the actual data. A purely numeric code can have up to 74 digits (not counting the parentheses), a code with only characters can have up to 41 characters.
Databar GS1 Expanded defines 14 different encoding methods and supports an extended character set. Which encoding method is chosen by the software depends on the application identifiers and data encoded. This is transparent for the user but be aware of the following issues:
- Data strings that include AIs for weight (310x, 320x) or price (392x, 393x) are considered variable items,
i.e. the GTIN must begin with a "9", example "(01)95012345678903(3103)000123".
- The application identifier (01) always denotes an GTIN, i.e. it must be followed by 14 digits before the next AI.
Also, if a GTIN is present in the data it must be the first item in the data string.
This is ok: (01)95012345678903
This is ok: (01)95012345678903(3103)000123
This is not ok: (01)123456
This is not ok: (3103)000123(01)95012345678903
- The library will automatically detect variable length AIs, e.g. (10) for batch number, and will insert FNC1 symbols if necessary.
- The set of encodable data with Databar GS1 Expanded is as follows: Letters: A-Z and a-z, digits: 0-9, special characters:
!,",%,&,\,(,),*,+,,,-,.,/,:,;,<,=,>,?,_ .
- Data strings that include AIs for weight (310x, 320x) or price (392x, 393x) are considered variable items,
i.e. the GTIN must begin with a "9", example "(01)95012345678903(3103)000123".
- Omnidirectional, Omnidirectional Stacked, Truncated, Stacked, Limited
The DataToEncode property of the control is data-bindable. To bind the property at design time, select the control and hit F4 to display the properties; scroll down to DataBindings and select a data source from the list or create a new data source. Of course it's also possible to data bind the property at runtime.
