ssBarCode version 2.1
The Delphi Native, QuickReports compatible Bar code Component - 16-bit & 32-bit versions

Soft Sector, Inc.
PO Box 81480
Cleveland OH 44181

See the document ORDER.TXT for ordering information.

You can use CompuServes SWREG service.  The SWREG number is 11379.

See the end of this document for the new features in this version.

IMPORTANT:  If you are upgrading from v2.0 or before, be sure to read this document!  Several things have changed!
Introduction
Thank you for your interest in our bar coding VCL.  There are many bar coding products for developers in existence, but all are either in DLL or VBX form.  With the release of ssBarCode from Soft Sector, Inc., developers now have a Delphi-native option to implement bar coding into their applications.

In this version, ssBarCode supports the six most popular bar code symbologies:  Code 128, Code 39 (or 3 of 9), EAN-13, Interleaved 2 of 5, Postnet, and UPC version A.  In addition, the 2 and 5 digit addons for UPC and EAN are supported.  If you have any symbologies you would like to see implemented, please let us know!

With version 2.1, ssBarcode is now 100% QuickReports compatible.  You can simply drop a QRssBarcode on a QRBand, create a normal ssBarcode, link the two, and make your reports print barcodes.  Note that ssBarcode still works standalone as well.  See the section below entitled "Using ssBarcode with QuickReports."
About Soft Sector, Inc.
Soft Sector, Inc. (SSI) is a Cleveland, OH based provider of hardware and software solutions.  Our main language for development is Borland Delphi.  In the course of our application development, we have created a number of components and tools that would be useful to other developers.  We are in the process of packaging these components for retail distribution.

Contacting Soft Sector, Inc.
We can be contacted in a variety of ways:

US Mail:  Soft Sector, Inc., PO Box 81480, Cleveland, OH 44181 USA
E-Mail:  ssi@en.com
CompuServe: 104274,1510
Phone/fax:  (216) 777-3612

WWW: http://ourworld.compuserve.com/homepages/softsect

The newest version of ssBarcode, as well as our other components, can always be found at our Web site.
Installation
You can install ssBarCode as you would any other component.  Specifically, follow these steps:

** Make sure you unZIPed the ZIP file with the -D option!! **

1.  Unzip the .ZIP file into a directory (example:  \SSBC) with the -D option.  There will be several directories created.  The actual components reside in LIB16 and LIB32, depending on if you are using Delphi 1.x (LIB16) or Delphi 2.0 (LIB32).

2.  Go into Delphi and access the OPTIONS pulldown menu.  Then choose INSTALL COMPONENTS...

3.  Click on the ADD button.  Another dialog box will pop up.  Click on the BROWSE button.

4.  A file selection common dialog will pop up.  Select the directory that contains the files for your version of Delphi (see #1 above).  In the "List Files of Type" drop down, you should select "DCU" files.

5.  You should see two .DCU files.  You should install SSBC.DCU first.  If you plan to use ssBarcode along with QuickReports, you should repeat this process and choose QRSSBC.DCU the second time.

6.  Now click OK in the Install Components dialog box.  Delphis VCL will now recompile.  When its done, you should have a palette page named "Soft Sector".  On it will appear an icon for the ssBarCode component.

Thats all there is to it!  Youre now ready to start creating bar codes!

Note that this restricted version of ssBarCode will only run while the Delphi IDE is running.  That means in order to include it in your applications, you must pay the registration fee!  See the file ORDER.TXT for more information on this extremely useful, yet affordable product.

Demo Programs
Weve written a two simple demo programs to show off some of the features of ssBarcode, including the different symbologies, bar width specification, and barcode printing.  The first project name is DEMOBC.DPR, and it is located in the DEMOS directory.  All of the features of this demo program are very easy to understand, and some of the code is commented.  The second demo program is named QRDEMO.DPR.  This is a simple project that illustrates how to create a QuickReports report including a barcode.  It makes use of the DBDEMO database files that came with Delphi.

Properties 
AddOn
AutoSize
BarCodeType
BarColor
BarWidth
BearerBars
CalcCheckDigit
Canvas (*)
Color (*)
Data
DataField (*)
DataSource (*)
Font 
Orientation
PrintHumanReadable
Visible (*)
WideBarRatio

(*)  These are inherited properties that are not described in this document.  See the Delphi help file for details.

AddOn  property

Declaration
property AddOn : string

Description
The AddOn property allows you to implement either 2 or 5 digit addon codes for UPC or EAN.  If you try to enter an AddOn code with the BarCodeType property set to either bcUPC_A or bcEAN_13, you will raise an exception.

AddOn codes are used for a few rather specific purposes.  The 2 digit addon code is used to track the serial number of periodicals, mainly magazines.  The 5 digit addon has several purposes, but mainly it is used in conjunction with EAN-13 for bar coding books.  A books ISBN number can be encoded in the actual EAN code.  Then the addon code is used to indicate the price of the book and the currency.  This form of using EAN is commonly known as "Bookland EAN."

AutoSize property

Declaration
property AutoSize : boolean

Description
The AutoSize property will automatically size the bar code to certain proportions based a number of calculations.  The first factor is the BarWidth property; the width of the component will be the BarWidth property times the actual number of bars and spaces.  The height of the component will be based on the standard accepted height to width ratio for each symbology.

If you set AutoSize to false, you can size the component as you see fit.  However, there is no guarantee that the resulting code will fit in the space you allot.

BarCodeType property

Declaration
property BarCodeType : TBarCodeType 

Description
This is the main property of the component.  It defines which symbology you want to use to create the bar code.  The possible values for TBarCodeType are:

{bcCode128, bcCode39, bcEAN_13, bcInt2of5, bcPostnet, bcUPC_A}

See the section below entitled "Symbologies" for a more in-depth description of each symbology.  
When you set the BarCodeType property, the program will check the Data property to see if the data entered is acceptable for the chosen bar code type.  For example, you cannot have alpha characters in an Interleaved 2 of 5 code.  If the data is not acceptable, an exception of type EBarCodeError will be raised.

BarColor property

Declaration
property BarColor : TColor 

Description
Use this property to set a color for the actual bars themselves as well as the human readable text beneath the bar code.  Note that for best scanning, bar codes should be black bars on a white background, but you do have the option to change this.

BarWidth property

Declaration
property BarWidth : single 

Description
This property allows you to change the width, in inches, of each bar.  For bar codes that have a narrow to wide bar ratio, the wide bar width is calculated based on the WideBarRatio property.  If you have the AutoSize property set to True, the component will resize when you change this property.

Each symbology has a standard accepted BarWidth, listed below.  Of course, these are only recommendations and you are free to use whatever width you choose.

Code 128 = varies, based on use.  Generally 0.0070 inches to 0.015 inches. 
Code 39 = 0.010 inches
EAN-13 = 0.013 inches
Interleaved 2 of 5 = 0.015 inches
Postnet = 0.020 ** (We strongly recommend using this value for Postnet)
UPC A = 0.013 inches

NOTE:  We have successfully printed a Code 128 barcode on a 300 dpi laser printer with a bar width of 0.0070 inches.  That is an extremely efficient code!

BearerBars property

Declaration
property BearerBars : boolean 

Description
Certain bar code symbologies call for bearer bars, or horizontal lines that run along the top and bottom of the code.  The reason for these bars is that a partial scan can sometimes be interpreted as a complete scan.  Bearer bars greatly reduce the chance of this happening.  

As of version 1.0, only Interleaved 2 of 5 bar codes can have bearer bars.  The other symbologies do not need them.  If you try to set BearerBars equal to True for any other symbology, an EBarCodeError exception will be raised.

CalcCheckDigit property

Declaration
property CalcCheckDigit : boolean 

Description
Set this property to True if you want the component to automatically generate the check digit for UPC A bar codes.  If CalcCheckDigit is False, then you must provide all 12 digits of the UPC code in the Data property, or an exception will be raised.

Data property

Declaration
property Data : string 

Description
This property is where you set the actual data to be encoded.  Data for each bar code symbology must follow certain rules or an exception will be raised.  See the section below entitled "Symbologies" for a description of acceptable data for each type of bar code.  Please note that Code 128 requires some special characters to function.  They are described below as well.

DataField / DataSource property

Declaration
(same as normal Delphi VCL)

Description
These fields work exactly the same as every other Delphi data-aware components.  Just a quick note:  when you set the DataField and DataSource properties, you are required to perform the necessary error checking to make sure that the data being passed is legal for the chosen symbology.  We suggest implementing a TField.OnGetText event handler for the field that the barcode is using.  See the demo program for an example of this.

Font property

Declaration
property Font : TFont

Description
This is the font that will be used to draw the human readable portion of the barcode.  Note that this MUST be a scalable font! (either TrueType or ATM)  Also note that you can change the fonts attributes (bold, italic, etc.), but the fonts size is automatically calculated by the component.  The Fonts color is taken from the BarColor property, as all barcode specifications call for the bars and human readable text to be the same color.

If possible, you should always use the font OCR-B for your human readable.  If you do not have this TrueType font, it is available from a variety of sources.  Most bar code specification documents call for this font to be used.

Orientation property

Declaration
property Orientation : TOrientation 

Description
The Orientation property is used to rotate the bar code in 90 degree increments.  You would never want to have a bar code that is not rotated in an increment of 90 degrees.  The human readable text is obviously also rotated.  The possible values for TOrientation are:

{orLeft_Right, orRight_Left, orTop_Bottom, orBottom_Top}

orLeft_Right means that the bar code is created from Left to Right (it is the default).  orTop_Bottom means that the bar code is created from Top to Bottom, etc.

PrintHumanReadable property

Declaration
property PrintHumanReadable : boolean 

Description
This property allows you to set whether the component will output the human readable version of the bar code (i.e. the actual letters or numbers).  Bar codes like UPC A and EAN 13 should always have this set to True.  As for the other bar codes, it is completely up to you.

WideBarRatio property

Declaration
property WideBarRatio : single

Description
This property affects the narrow-to-wide bar ratio for symbologies that have such elements.  The value you give this property will be multiplied by the value of BarWidth to get the wide bar width.  Most symbologies dictate a wide bar ratio in the 2.0 to 3.0 range.  You will want a higher WideBarRatio if your BarWidth is very small.  Most applications call for this ratio to be 3.0.

Methods
There is only one available method, aside from the constructor for this component.  The constructors implementation is as follows:

constructor Create(AOwner : TComponent); 

PrintBarcode Method

Declaration
procedure PrintBarcode(X, Y, Height : single);

Description
This method makes it extremely easy to print barcodes from your application.  Simply create an instance of ssBarcode, either at design-time or run-time, set the properties you need, and then call this method.  ssBarcode handles all of the sticky implementations of printing, such as printer resolutions, margins, etc.  NOTE:  If you dropped ssBarcode on QuickReports band, you do not have to manually issue this command.

To use this method, supply X and Y values for the upper left hand corner of the barcode, in inches.  The Height parameter allows you to specify an exact height of the barcode, in inches.  You can also pass 0 (zero) as the Height, and ssBarcode will calculate the Height based on standard height-to-width ratio for the current symbology.

** IMPORTANT NOTE **  This method uses the Printer variable (defined in the Printers unit that came with Delphi) to handle the physical printer.  As such, you must follow the code below to print barcodes:

{procedure name}

begin
  Printer.BeginDoc; {****}
  ssBarCode1.PrintBarcode(1.0,1.0,0);
  {any other output to the printer here}
  Printer.EndDoc; {****}
end;
  
The lines with asterisks are absolutely critical.  If you do not include them, it is unlikely that the barcode will print.

Another thing to note:  the PrintBarcode method pays no attention to the AutoSize or Width properties.  PrintBarcode will always print the entire barcode with no clipping.

CHANGE FROM VERSION 1.5:  Notice you no longer have to set the Printer.Canvass font.  It will take the font from the ssBarcode component.
Events
The events defined for ssBarCode are inherited from standard Delphi events.  See Delphis help file for details.

OnClick
OnDblClick
OnMouseDown
OnMouseMove
OnMouseUp

Using ssBarcode with QuickReports
We have done the necessary work to make ssBarcode completely compatible with the very popular report writer QuickReports.  If you are unfamiliar with QR, the following may not make much sense to you.

You will remember that you actually installed two components, ssBarcode and QRssBarcode.  BOTH components are necessary to make your program work with both QR and ssBarcode.  QRssBarcode is what some call a "wrapper" component.  It needs to be linked to an actual instance of ssBarcode, either at design time or run time.  QRssBarcode doesnt have any properties for changing the barcode parameters.  It simply has a property called "Barcode" that you link to an instance of ssBarcode that actually does the work.

In other words, you create an ssBarcode that controls the QRssBarcode.  Whatever changes you make to the ssBarcode will be reflected in the QRssBarcode.  I know this sounds a little confusing, but it really is rather simple once you play with it.

Why did we do it this way?  We were having problems with people using different versions of QuickReports than the one that we compiled with.  So weve included the full source code to QRssBarcode, which means it will compile no matter what version of QR you are using. 
NOTE ABOUT BARCODES WITH QUICKREPORTS:  QuickReports does its own scaling based on the number of pixels the screen can display per inch.  Obviously, most printers can display many more pixels (or dots) per inch.  As such, bar codes printed using QuickReports tend to be of slightly lower quality than the same barcode printed using the ssBarcode.PrintBarcode method.  Nevertheless, we have done extensive testing with barcodes printed with QR and have had favorable results.  

Symbologies
A symbology is a set of rules that govern how to create a bar code based on what data is being coded.  There are many symbologies in existence, some general purpose and others for very specific applications.  Each bar code has its pros and cons.  This version of ssBarCode contains the six major symbologies, as described below.

Code 128
Code 128 is an extremely flexible symbology and can be used to create alphanumeric barcodes.  It derives its name from the fact that it can represent all 128 ASCII symbols.  If you are unfamiliar with Code 128, I will try to give you a quick tutorial, as Code 128 is more complicated than most other one-dimensional barcodes.

The first thing you must know about Code 128 is that it has three different character sets (A, B, and C).  That means one set of bars can mean three different things based on which set is currently in use.  The other tricky bit is that you have the option of switching character sets in the middle of the code.  I think you see now why this is a more difficult code.

Character set A can encode most symbol characters (!,$,/, etc.) as well as all uppercase letters and the ten digits.  In addition, it can encode the "special" ASCII characters, such as carriage return, line feed, null, escape, etc.

Character set B encodes all symbol characters, upper and lowercase letters and the ten digits.

Character set C encodes 100 pairs of numbers.  That is, one set of bars could mean "05" or "43", etc.  This effictively doubles the density of Code 128 when using numbers only.  Also note, because they are numeric pairs, the Code C portion must have an even number of digits.

Now that you know what the differences in the codes are, you now have to know how to use them with ssBarcode.  Since all normal ASCII characters are used by Code 128, we must use special characters to tell the component what to do.  ssBarcode uses ASCII values #208 through #242 for this purpose.  If youre using the Object Inspector to type the Data property, you hold down the Alt key, then type (on the numeric keypad) 0 + the number  (Alt-0208 for instance).  The table below lists all of the special characters.

#208	START A
#209	START B
#210	START C

These are the special START CODE characters.  Each Code 128 barcodes MUST START with one of the three above. Which start code you use is obviously which character set is active.  You cannot use a start code in the middle of a symbol.  See the table below for the special codes used to switch to a different character set.

Special Char		Character Set A		Character Set B		Character Set C
#201			Function 3		Function 3		<none>
#202			Function 2		Function 2		<none>
#203			TempShift to B		TempShift to A		<none>
#204			Switch to C		Switch to C		<none>
#205			Switch to B		Function 4		<none>
#206			Function 4		Switch to A		Switch to A
#207			Function 1		Function 1		Function 1
#211			NUL			<none>			<none>
#212			SOH			<none>			<none>
#213			STX			<none>			<none>
#214			ETX			<none>			<none>
#215			EOT			<none>			<none>
#216			ENQ			<none>			<none>
#217			ACK			<none>			<none>
#218			BEL			<none>			<none>
#219			BS			<none>			<none>
#220			HT			<none>			<none>
#221			LF			<none>			<none>
#222			VT			<none>			<none>
#223			FF			<none>			<none>
#224			CR			<none>			<none>
#225			SO			<none>			<none>
#226			SI			<none>			<none>
#227			DLE			<none>			<none>
#228			DC1			<none>			<none>
#229			DC2			<none>			<none>
#230			DC3			<none>			<none>
#231			DC4			<none>			<none>
#232			NAK			<none>			<none>
#233			SYN			<none>			<none>
#234			ETB			<none>			<none>
#235			CAN			<none>			<none>
#236			EM			<none>			<none>
#237			SUB			<none>			<none>
#238			ESC			<none>			<none>
#239			FS			<none>			<none>
#240			GS			<none>			<none>
#241			RS			<none>			<none>
#242			US			<none>			<none>

Got all that?  <smile>  Ok, so heres what that table means:  if the current character set is A, then a #205 means Switch to Code B.  If the current set was B, that same #205 means Function 4.  

The Switch codes are all boldfaced because youll probably use those the most.  A Switch code means "Switch to Character Set X for the remainder of the code, or until another Switch code is encountered."

The Temp-Shift codes means "Shift to Code X for the next character only."

The "Function" codes mean different things based on your barcode reader.  Generally they are explained in the readers documentation.

Ok, I think a few examples are in order:

Lets say you want to encode the text "CODE 128".  Character set A is sufficient.  Heres how:
  ssBarCode.Data := #208 + "CODE 128"; 
If you were using the Object Inspector, you wouldve typed {Alt-0208}CODE 128.

Heres a little more advanced example.  We want to encode "1234 abcd".  We can use Set C, since we have an even number of digits.  Then we have to switch to Set B for the lowercase letters.
  ssBarCode.Data := #210 + "1234" + #205 + " abcd";

Ok, one last example.  We want to encode "Soft Sector 1996", but we want a Carriage Return in between "Soft" and "Sector".  Here goes:
  ssBarCode.Data := #209 + "Soft" + #203 +  #224 + "Sector " + #204 + "1996";

See what happened there?  We started off in Set B and wrote "Soft", then we Temp Shifted to A to encode the CR.  The we wrote "Sector" in Set B.  Finally, we switched to Set C to encode "1996."

I realise that this looks very complex.  But spend some time playing around and it will get much easier.

Code 39 (or 3 of 9)
Code 39 was the first alphanumeric symbology to be developed.  It is now in wide use and is the de facto standard for non retail applications.  It can encode the 26 letters of the alphabet (in upper case), the 10 digits, and the symbols "- . $ / + %"  Code 39 gets its name because each character has five bars and four spaces (nine elements); of those nine, three are wide.  Thus, "3 of 9."  If you need to encode any non-numeric data, its a choice between 3 of 9 and Code 128.  In most cases, a proper implementation of Code 128 is more efficient.  However, 3 of 9 is more universally accepted by barcode readers.

EAN-13
EAN stands for the European Article Numbering.  It is also compatible with JAN and IAN.  EAN is the standard for retail applications in countries other than the United States.  EAN-13 encodes 13 digits, but does so in the same amount of space that UPC encodes 12 digits.  This is accomplished because the first digit is actually encoded in the parity of the left side bars, rather than by actual bars.  

The makeup of an EAN code is similar to a UPC, except that it starts with a 1 to 3 digit code identifying the country of origin.  The standard EAN country codes can be found in numerous places, including several Web sites.  Note that an EAN code with a first digit of "0" is exactly the same as a UPC code encoding the same digits.  

EAN codes are becoming widespread even in the U.S., especially on books.  An ISBN number can be encoded in the EAN main code, then the price of the book can be encoded in the 5 digit addon.  This is commonly called "Bookland EAN".  Note that all Bookland EAN codes must start with "978".

Interleaved 2 of 5
Interleaved 2 of 5 (sometimes abbreviated I2of5 or ITF) is a high-density, continuous numeric symbology mainly used in the distribution industry.  Many packages you receive have ITF bar codes on them.  ITF is a very efficient symbology because it encodes data both in the bars and spaces.  Each digit is made up of five bars, of which two are wide; thus the name "2 of 5".  Since data is encoded in both bars and spaces, all ITF bar codes musthave an even number of digits!  Many applications will add a trailing zero if the number to be encoded contains an odd number of digits.  If you are encoding less than ten digits, ITF is the most efficient bar code.

One of the problems with ITF is that a partial scan has a high probability of decoding as a valid, but shorter, ITF symbol.  To minimize this risk, ITF bar codes are often used with bearer bars (sometimes called protection stripes).  Bearer bars are horizontal bars running along the top and bottom of the symbol.  They decrease the probability that a partial scan will decode as valid.

Postnet
This symbology was developed by the United States Post Office for the purpose of marking postal items so that they could be sorted by automatic equipment.  In the strictest sense, Postnet is not a bar code, since information is not encoded into the widths of the bars.  Postnet encodes using the heights of the bars instead.  Postnet codes generally match the length of a Zip code; that is, either 5 or 9 digits.  Recently, the Post Office has accepted a Postnet code with 11 digits, the last two being used as the first two digits of a street address, PO Box, apartment number, etc.  For more information about the proper use of Postnet codes, contact your local Post Office.

UPC version A
UPC (Universal Product Code) is the bar code of choice for the retail industry in the United States.  UPC is a coding system as well as a symbology; it is designed to uniquely identify a product and its manufacturer.  The actual UPC code is a 10-digit code:  the first five digits represent the manufacturer, the next five as a unique product identifier code assigned by the manufacturer.  This 10-digit code is preceded with a "number system" digit and followed by a check digit.  Thus the UPC-A bar code encodes 12 digits of data.

When you apply for a UPC manufacturer number, the UCC (Uniform Code Council) assigns you a six digit number; the first digit is a "Number System" digit from 0 to 9.  The meanings of each of these digits is listed below.  The next five digits is your actual manufacturer number.

The Number System assignments are as follows:

0 - 92,000 manufacturer identification numbers; 8,000 locally assigned numbers
1 - Reserved
2 - Random weight consumer packages
3 - Drug products
4 - In-store marking without format
5 - UPC coupons
6 - 100,000 manufacturer identification numbers
7 - 100,000 manufacturer identification numbers
8 - Reserved
9 - Reserved

Since all UPC-A codes encoded 12 digits of data, UPC-A is a fixed-width symbology.

Future Enhancements
This is version 2.0 of ssBarCode.  ssBarcode has grown enormously since its 1.0 release.  We believe that ssBarcode rivals any competitor, be it VCL, VBX, or DLL. If you have any features youd like to see, please let us know.  Specifically, if there are symbologies youd like use to implement, drop us a line.

- Additional symbologies:  UPC-E, EAN-8, Codabar, FIM, Code 93, Code 49, 2-dimensional codes?
- Windows .HLP file

NOTE:  The source code to ssBarcode will be made available to registered users at a reasonable price.  The scheduled release date for the source code is Friday, May 24th.  Please check our Web page!
Revision History
05-15-96 Version 2.1
- Changed the way ssBarcode interacts with QuickReports
- Added a new component, QRssBarcode
- Added 32-bit version
- Bug fix:  barcodes printed with QR now respect the AutoSize property correctly
- Changed demo program, added new QRDEMO program

05-07-96 Version 2.0
- Added two symbologies:  Code 128, EAN-13
- Added 2 and 5 digit AddOn codes
- Added Font property for human readable
- Made data-aware (added DataField and DataSource properties)
- Made QuickReports compatible
- Added additional error checking
- Streamlined internal code

04-15-96  Version 1.5
- Changed the BarWidth to type Single.  Now you specify the BarWidth in Inches (generally fractions thereof)
- Added property WideBarRatio, allowing you to specify the narrow-to-wide bar ratio for symbologies that support it (Code 39 and Int2of5)
- Added method PrintBarcode, allowing you to easily print barcodes on any Windows-supported printer

03-24-96   Version 1.0
Initial public release


