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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.barcode.renderers">
    <title>Zend_Barcode Renderers</title>

    <para>
        Renderers have some common options. 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>As discrete values passed to individual setters.</para>
        </listitem>
    </itemizedlist>

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

        <programlisting language="php"><![CDATA[
$options = array('topOffset' => 10);

// Case 1
$renderer = new Zend_Barcode_Renderer_Pdf($options);

// Case 2
$renderer = new Zend_Barcode_Renderer_Pdf();
$renderer->setOptions($options);

// Case 3
$config   = new Zend_Config($options);
$renderer = new Zend_Barcode_Renderer_Pdf();
$renderer->setConfig($config);

// Case 4
$renderer = new Zend_Barcode_Renderer_Pdf();
$renderer->setTopOffset(10);
]]></programlisting>
    </example>

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

        <para>
            In the following list, the values have no unit; 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. The individual setters are obtained by uppercasing the initial
            letter of the option and prefixing the name with "set" (e.g. "barHeight" =>
            "setBarHeight"). All options have a correspondant getter prefixed with "get" (e.g.
            "getBarHeight"). Available options are:
        </para>

        <table id="zend.barcode.renderers.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>rendererNamespace</emphasis></entry>
                        <entry><type>String</type></entry>
                        <entry><classname>Zend_Barcode_Renderer</classname></entry>

                        <entry>
                            Namespace of the renderer; for example, if you need to extend the
                            renderers
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>horizontalPosition</emphasis></entry>
                        <entry><type>String</type></entry>
                        <entry>"left"</entry>

                        <entry>
                            Can be "left", "center" or "right". Can be useful with
                            <acronym>PDF</acronym> or if the <methodname>setWidth()</methodname>
                            method is used with an image renderer.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>verticalPosition</emphasis></entry>
                        <entry><type>String</type></entry>
                        <entry>"top"</entry>

                        <entry>
                            Can be "top", "middle" or "bottom". Can be useful with
                            <acronym>PDF</acronym> or if the <methodname>setHeight()</methodname>
                            method is used with an image renderer.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>leftOffset</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>0</entry>

                        <entry>
                            Top position of the barcode inside the renderer. If used, this value
                            will override the "horizontalPosition" option.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>topOffset</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>0</entry>

                        <entry>
                            Top position of the barcode inside the renderer. If used, this value
                            will override the "verticalPosition" option.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>automaticRenderError</emphasis></entry>
                        <entry><type>Boolean</type></entry>
                        <entry><constant>TRUE</constant></entry>

                        <entry>
                            Whether or not to automatically render errors. If an exception occurs,
                            the provided barcode object will be replaced with an Error
                            representation. Note that some errors (or exceptions) can not be
                            rendered.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>moduleSize</emphasis></entry>
                        <entry><type>Float</type></entry>
                        <entry>1</entry>
                        <entry>Size of a rendering module in the support.</entry>
                    </row>

                    <row>
                        <entry><emphasis>barcode</emphasis></entry>
                        <entry><classname>Zend_Barcode_Object</classname></entry>
                        <entry><constant>NULL</constant></entry>
                        <entry>The barcode object to render.</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            An additional getter exists: <methodname>getType()</methodname>. It returns the name of
            the renderer class without the namespace (e.g.
            <classname>Zend_Barcode_Renderer_Image</classname> returns "image").
        </para>
    </sect2>

    <sect2 id="zend.barcode.renderers.image">
        <title>Zend_Barcode_Renderer_Image</title>

        <para>
            The Image renderer will draw the instruction list of the barcode object in an image
            resource. The component requires the GD extension.
            The default width of a module is 1 pixel.
        </para>

        <para>Available option are:</para>

        <table id="zend.barcode.renderers.image.table">
            <title>Zend_Barcode_Renderer_Image 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>height</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>0</entry>

                        <entry>
                            Allow you to specify the height of the result image. If "0",
                            the height will be calculated by the barcode object.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>width</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>0</entry>

                        <entry>
                            Allow you to specify the width of the result image. If "0",
                            the width will be calculated by the barcode object.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>imageType</emphasis></entry>
                        <entry><type>String</type></entry>
                        <entry>"png"</entry>

                        <entry>
                            Specify the image format. Can be "png", "jpeg", "jpg" or "gif".
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.barcode.renderers.pdf">
        <title>Zend_Barcode_Renderer_Pdf</title>

        <para>
            The <acronym>PDF</acronym> renderer will draw the instruction list of the barcode
            object in a <acronym>PDF</acronym> document.
            The default width of a module is 0.5 point.
        </para>

        <para>
            There are no particular options for this renderer.
        </para>
    </sect2>

    <sect2 id="zend.barcode.renderers.svg">
        <title>Zend_Barcode_Renderer_Svg</title>

        <para>
            The <acronym>SVG</acronym> renderer will draw the instruction list of the barcode
            object in a <acronym>SVG</acronym> document.
            The default width of a module is 1 pixel.
        </para>

        <para>Available option are:</para>

        <table id="zend.barcode.renderers.svg.table">
            <title>Zend_Barcode_Renderer_Svg 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>height</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>0</entry>

                        <entry>
                            Allow you to specify the height of the result image. If "0",
                            the height will be calculated by the barcode object.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis>width</emphasis></entry>
                        <entry><type>Integer</type></entry>
                        <entry>0</entry>

                        <entry>
                            Allow you to specify the width of the result image. If "0",
                            the width will be calculated by the barcode object.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>
</sect1>