repo_zf1/documentation/manual/en/module_specs/Zend_Barcode-Objects.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.barcode.objects" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Zend_Barcode Objects</title>

    <para>
        Barcode objects allow you to generate barcodes independently of the rendering support. After
        generation, you can retrieve the barcode as an array of drawing instructions that you can
        provide to a renderer.
    </para>

    <para>
        Objects have a large number of options. Most of them are common to all objects. These
        options can be set in four ways:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                As an array or a <classname>Zend_Config</classname> object passed to the
                constructor.
            </para>
        </listitem>

        <listitem>
            <para>
                As an array passed to the <methodname>setOptions()</methodname> method.
            </para>
        </listitem>

        <listitem>
            <para>
                As a <classname>Zend_Config</classname> object passed to the
                <methodname>setConfig()</methodname> method.
            </para>
        </listitem>

        <listitem>
            <para>Via individual setters for each configuration type.</para>
        </listitem>
    </itemizedlist>

    <example id="zend.barcode.objects.configuration">
        <title>Different ways to parameterize a barcode object</title>

        <programlisting language="php"><![CDATA[
$options = array('text' => 'ZEND-FRAMEWORK', 'barHeight' => 40);

// Case 1: constructor
$barcode = new Zend_Barcode_Object_Code39($options);

// Case 2: setOptions()
$barcode = new Zend_Barcode_Object_Code39();
$barcode->setOptions($options);

// Case 3: setConfig()
$config  = new Zend_Config($options);
$barcode = new Zend_Barcode_Object_Code39();
$barcode->setConfig($config);

// Case 4: individual setters
$barcode = new Zend_Barcode_Object_Code39();
$barcode->setText('ZEND-FRAMEWORK')
        ->setBarHeight(40);
]]></programlisting>
    </example>

    <sect2 id="zend.barcode.objects.common.options">
        <title>Common Options</title>

        <para>
            In the following list, the values have no units; we will use the term "unit." For
            example, the default value of the "thin bar" is "1 unit". The real units depend on the
            rendering support (see <link linkend="zend.barcode.renderers">the renderers
                documentation</link> for more information). Setters are each named by uppercasing
            the initial letter of the option and prefixing the name with "set" (e.g. "barHeight"
            becomes "setBarHeight"). All options have a corresponding getter prefixed with "get"
            (e.g. "getBarHeight"). Available options are:
        </para>

        <table id="zend.barcode.objects.common.options.table">
            <title>Common Options</title>

            <tgroup cols="4">
                <thead>
                    <row>
                        <entry>Option</entry>
                        <entry>Data Type</entry>
                        <entry>Default Value</entry>
                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><emphasis>barcodeNamespace</emphasis></entry>
                        <entry><type>String</type></entry>
                        <entry><classname>Zend_Barcode_Object</classname></entry>

                        <entry>
                            Namespace of the barcode; for example, if you need to extend the
                            embedding objects
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>barHeight</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>50</entry>
                        <entry>Height of the bars</entry>
                    </row>
                    <row>
                        <entry><emphasis>barThickWidth</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>3</entry>
                        <entry>Width of the thick bar</entry>
                    </row>

                    <row>
                        <entry><emphasis>barThinWidth</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>1</entry>
                        <entry>Width of the thin</entry>
                    </row>

                    <row>
                        <entry><emphasis>factor</emphasis></entry>
                        <entry>
                            <type>Integer</type>, <type>Float</type>,
                            <type>String</type> or <type>Boolean</type>
                        </entry>
                        <entry>1</entry>
                        <entry>Factor by which to multiply bar widths and font sizes</entry>
                    </row>

                    <row>
                        <entry><emphasis>foreColor</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>0 (black)</entry>

                        <entry>
                            Color of the bar and the text. Could be provided as an integer
                            or as a <acronym>HTML</acronym> value (e.g. "#333333")
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>backgroundColor</emphasis></entry>
                        <entry><type>Integer</type> or <type>String</type></entry>
                        <entry>16777125 (white)</entry>

                        <entry>
                            Color of the background. Could be provided as an integer
                            or as a <acronym>HTML</acronym> value (e.g. "#333333")
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>reverseColor</emphasis></entry>
                        <entry><type>Boolean</type></entry>
                        <entry><constant>FALSE</constant></entry>
                        <entry>Allow switching the color of the bar and the background</entry>
                    </row>

                    <row>
                        <entry><emphasis>orientation</emphasis></entry>
                        <entry>
                            <type>Integer</type>, <type>Float</type>,
                            <type>String</type> or <type>Boolean</type>
                        </entry>
                        <entry>0</entry>
                        <entry>Orientation of the barcode</entry>
                    </row>

                    <row>
                        <entry><emphasis>font</emphasis></entry>
                        <entry><type>String</type> or <type>Integer</type></entry>
                        <entry><constant>NULL</constant></entry>

                        <entry>
                            Font path to a <acronym>TTF</acronym> font or a number between 1 and 5
                            if using image generation with GD (internal fonts)
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>fontSize</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>10</entry>
                        <entry>Size of the font (not applicable with numeric fonts)</entry>
                    </row>

                    <row>
                        <entry><emphasis>withBorder</emphasis></entry>
                        <entry><type>Boolean</type></entry>
                        <entry><constant>FALSE</constant></entry>
                        <entry>Draw a border around the barcode and the quiet zones</entry>
                    </row>

                    <row>
                        <entry><emphasis>withQuietZones</emphasis></entry>
                        <entry><type>Boolean</type></entry>
                        <entry><constant>TRUE</constant></entry>
                        <entry>Leave a quiet zone before and after the barcode</entry>
                    </row>

                    <row>
                        <entry><emphasis>drawText</emphasis></entry>
                        <entry><type>Boolean</type></entry>
                        <entry><constant>TRUE</constant></entry>
                        <entry>Set if the text is displayed below the barcode</entry>
                    </row>

                    <row>
                        <entry><emphasis>stretchText</emphasis></entry>
                        <entry><type>Boolean</type></entry>
                        <entry><constant>FALSE</constant></entry>
                        <entry>Specify if the text is stretched all along the barcode</entry>
                    </row>

                    <row>
                        <entry><emphasis>withChecksum</emphasis></entry>
                        <entry><type>Boolean</type></entry>
                        <entry><constant>FALSE</constant></entry>

                        <entry>
                            Indicate whether or not the checksum is automatically added to
                            the barcode
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>withChecksumInText</emphasis></entry>
                        <entry><type>Boolean</type></entry>
                        <entry><constant>FALSE</constant></entry>

                        <entry>
                            Indicate whether or not the checksum is displayed in the textual
                            representation
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>text</emphasis></entry>
                        <entry><type>String</type></entry>
                        <entry><constant>NULL</constant></entry>
                        <entry>The text to represent as a barcode</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <sect3 id="zend.barcode.objects.common.options.barcodefont">
            <title>Particular case of static setBarcodeFont()</title>

            <para>
                You can set a commont font for all your objects by using the static method
                <methodname>Zend_Barcode_Object::setBarcodeFont()</methodname>. This value
                can be always be overridden for individual objects by using the
                <methodname>setFont()</methodname> method.
            </para>

            <programlisting language="php"><![CDATA[
// In your bootstrap:
Zend_Barcode_Object::setBarcodeFont('my_font.ttf');

// Later in your code:
Zend_Barcode::render(
    'code39',
    'pdf',
    array('text' => 'ZEND-FRAMEWORK')
); // will use 'my_font.ttf'

// or:
Zend_Barcode::render(
    'code39',
    'image',
    array(
        'text' => 'ZEND-FRAMEWORK',
        'font' => 3
    )
); // will use the 3rd GD internal font
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.barcode.objects.common.getters">
        <title>Common Additional Getters</title>

        <para></para>

        <table id="zend.barcode.objects.common.getters.table">
            <title>Common Getters</title>

            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Getter</entry>
                        <entry>Data Type</entry>
                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><methodname>getType()</methodname></entry>
                        <entry><type>String</type></entry>

                        <entry>
                            Return the name of the barcode class without the namespace (e.g.
                            <classname>Zend_Barcode_Object_Code39</classname> returns simply
                            "code39")
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getRawText()</methodname></entry>
                        <entry><type>String</type></entry>
                        <entry>Return the original text provided to the object</entry>
                    </row>

                    <row>
                        <entry><methodname>getTextToDisplay()</methodname></entry>
                        <entry><type>String</type></entry>

                        <entry>
                            Return the text to display, including, if activated, the checksum value
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getQuietZone()</methodname></entry>
                        <entry><type>Integer</type></entry>

                        <entry>
                            Return the size of the space needed before and after the barcode
                            without any drawing
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getInstructions()</methodname></entry>
                        <entry><type>Array</type></entry>
                        <entry>Return drawing instructions as an array.</entry>
                    </row>

                    <row>
                        <entry><methodname>getHeight($recalculate = false)</methodname></entry>
                        <entry><type>Integer</type></entry>

                        <entry>
                            Return the height of the barcode calculated after possible rotation
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getWidth($recalculate = false)</methodname></entry>
                        <entry><type>Integer</type></entry>

                        <entry>
                            Return the width of the barcode calculated after possible rotation
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getOffsetTop($recalculate = false)</methodname></entry>
                        <entry><type>Integer</type></entry>

                        <entry>
                            Return the position of the top of the barcode calculated after
                            possible rotation
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getOffsetLeft($recalculate = false)</methodname></entry>
                        <entry><type>Integer</type></entry>

                        <entry>
                            Return the position of the left of the barcode calculated after
                            possible rotation
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>

    <xi:include href="Zend_Barcode-Objects_Details.xml" />
</sect1>