25.7. Method reference

25.7.1. Encoder methods

All encoder methods are accessed on an instance of class PDF417Barcode

1
2
3
...
$encoder = new PDF417Barcode($columns,$errlevel);
...

PDF417Barcode

PDF417Barcode($aNumCols=10, $aErrLevel=2)

Purpose:

To create a new PDF417 encoder with a chosen number of columns and error level. Please note that these parameters can also be adjusted using the methods described below. The method will throw exceptions if the parmeters are outside there valid range.

$aNumCols , an integer in the range [2,30]

$aErrLevel, an integer in the range [0,8]

Returns:

A new encoder which is used by the backend to generate the barcode label.

Example:

1
2
// Create a new encoder with 20 columns
$encoder = new PDF417Barcode(20);

SetColumns

SetColumns($aCols)

Purpose:

Specify number of data columns. This should be a value in the range [2-30] (inclusively) . Note that it is also possible to specify the number of columns in the instantiation of the encoder.

Example:

1
2
3
// Create a new encoder with 20 columns
$encoder = new PDF417Barcode();
$encoder->SetColumns(20);

Note:

The number of rows will be automatically adjusted to fit the data and the error correction codewords as specified by the error level setting. The number of rows is not directly user configurable.

SetErrLevel

SetErrLevel($aErrLevel)

Purpose:

Specify the chosen level of error correction.

Example:

1
2
$encoder = new PDF417Barcode();
$encoder->SetErrLevel(5);

Note:

A high error level will limit the number of payload data since the total number of data in the label is fixed.

SetTruncated

SetTruncated($aTrunc=true)

Purpose:

Specify that barcode should use the truncated PDF format. This will make the barcode slightly narrower and might be used where the physical space is at premium.

Example:

1
2
$encoder = new  PDF417Barcode();
$encoder->SetTruncated ();

Note:

Not all barcode scanners can handle truncated PDF417.

25.7.2. Common backend methods

The backend is responsible for the actual output of the barcode (see Figure 25.4).

It is possible to either create an image or a postscript backend. In the creation of the backend an instance of the encoder is given as the second argument. The actual output from the script (to create the barcode label) is done with a call to the Backend::Stroke() method. As usual this call should be the last line in the script if it is used to send the image back to the browser.

The method call to Stroke() should always be guarded with a try{} catch {} statement.

Example:

1
2
3
4
5
6
7
8
9
10
try {
    $encoder = new  PDF417Barcode( $columns, $errlevel);
    $backend = PDF417BackendFactory::Create( BACKEND_IMAGE, $encoder);
 
    // .. Output formatting
    $backend->Stroke();
}
catch(JpGraphException $e) {
    echo 'PDF417 Error: '.$e->GetMessage();
}

In the example above we have chosen to create an image encoder (specified by constant BACKEND_IMAGE) by default the image format used will be PNG which is also the recommended format.

Stroke

Stroke($aData, $aFile='')

Purpose:

Encode a specific data string entered as the first argument and send the barcode output, depending on backend, either directly back to the browser as an image or return the Postscript representation as a string.

Example:

1
2
3
4
5
6
7
8
9
10
11
<?php
// Data to be encoded
$data = ... ;
 
try {
    ...
    $backend->Stroke($data);
} catch( JpGraphException $e) {
    ...
}
?>

SetVertical

SetVertical($aFlg=true)

Purpose:

Draw the barcode vertically instead of the default horizontal direction

Example:

1
$backend->SetVertical();

SetScale

SetScale($aScale)

Purpose:

Will arbitrary scale the generated barcode image. Scale factor is specified as a floating point number .

Example:

1
$backend->SetScale(2.5);

SetModuleWidth

SetModuleWidth($aWidth)

Purpose:

Specifies the module width to be used in the barcode. The module width is interpretated differently depending on whether it is applied on an image or a postscript backend. The module width will determine the physical width of the overall barcode. Please make sure that the printer has good enough resolution to handle the chosen module width.

For image backends is specifies the number of pixels to be used for the width of one module in the barcode. The module can be thought of as the thinnest line printed in the barcode. Each codeword is encoded 17 modules wide where there are 4 black and 4 white separated areas.

Even though most modern inkjet printers (2003 and later) can resolve modules down to 1 pixels it is recommended that for inkjet printers a module width of >= 2 is used.

For Postcript backend the module width specified the width in Postscript points (1 point = 1/72 inch).

Example:

1
$backend->SetModuleWidth(2);

Tip

The size of the barcode image can be fine tuned by applying an overall scaling constant as specified with the method SetScale().

SetHeight

SetHeight($aHeight)

Purpose:

Specified the height to width ratio for the individual rows in the barcode. By default the ratio is 3, which means that the height of the rows in the barcode is 3 times the module width. Most scanners can handle a factor between 2-5. You should very rarely have to change this parameter.

The ratio is specified as an integer.

One reason to change this to a smaller value is to make a barcode label take up less vertical space.

Example:

1
$backend->SetHeight(2);

Caution

Not all barcode scanners are good at handling very small ratios. This will also make the barcode more susceptible to damages.

SetColor

SetColor($aFrgColor,$aBkgColor)

Purpose:

Specify the foreground and background color for the barcode.

Example:

1
$backend->SetColor( 'black', 'lightyellow');

ShowFrame

ShowFrame($aFlg=true)

Purpose:

Draw a 1 pixel frame around the barcode. This is not recommended in production since it might disturb some scanners reading. This is only useful if you need a visual feedback on the boundaries for the image.

Example:

1
backend->SetFrame();

ShowText

ShowText($aFlg=true)

Caution

This is an extension specific to JpGraph. Human readable text is not part of the official PDF417 standard and hence this is disabled by default.. There are usually no problems of including this text but it is not recommended to do so in a production environment. This is mostly useful when debugging an application and to make it easer to see that the correct data is encoded as a barcode label.

Purpose:

Show human readable text of the encoded data underneath the barcode label.

Example:

%%

SetFont

SetFont($aFontFam,$aFontStyle,$aFontSize)

Purpose:

Specify the font for the human readable text underneath the barcode label.

Example:

1
$backend->SetFont( FF_ARIAL, FS_NORMAL, 8);

25.7.3. Image backend methods

SetImgFormat

SetImgFormat($aFormat)

Purpose:

Specify image format. Possible values are

  • 'auto'

  • 'png'

  • 'jpeg'

  • 'gif'

Example:

1
$backend->SetImgFormat('jpeg');

25.7.4. Postscript backend methods

SetEPS($aFlg=true)

SetEPS($aFlg=true)

Purpose:

Format the output as Encapsulated Postcript. This adds a bounding box information to the output and makes this format suitable to be included in other postscript files.

Example:

1
2
3
$encoder = new PDF417Barcode( $columns, $errlevel);
$backend = PDF417BackendFactory::Create( BACKEND_PS, $encoder); 
$backend->SetEPS();