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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.barcode.objects" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>Zend_Barcode Objects</title>
   5
   6     <para>
   7         Barcode objects allow you to generate barcodes independently of the rendering support. After
   8         generation, you can retrieve the barcode as an array of drawing instructions that you can
   9         provide to a renderer.
  10     </para>
  11
  12     <para>
  13         Objects have a large number of options. Most of them are common to all objects. These
  14         options can be set in four ways:
  15     </para>
  16
  17     <itemizedlist>
  18         <listitem>
  19             <para>
  20                 As an array or a <classname>Zend_Config</classname> object passed to the
  21                 constructor.
  22             </para>
  23         </listitem>
  24
  25         <listitem>
  26             <para>
  27                 As an array passed to the <methodname>setOptions()</methodname> method.
  28             </para>
  29         </listitem>
  30
  31         <listitem>
  32             <para>
  33                 As a <classname>Zend_Config</classname> object passed to the
  34                 <methodname>setConfig()</methodname> method.
  35             </para>
  36         </listitem>
  37
  38         <listitem>
  39             <para>Via individual setters for each configuration type.</para>
  40         </listitem>
  41     </itemizedlist>
  42
  43     <example id="zend.barcode.objects.configuration">
  44         <title>Different ways to parameterize a barcode object</title>
  45
  46         <programlisting language="php"><![CDATA[
  47 $options = array('text' => 'ZEND-FRAMEWORK', 'barHeight' => 40);
  48
  49 // Case 1: constructor
  50 $barcode = new Zend_Barcode_Object_Code39($options);
  51
  52 // Case 2: setOptions()
  53 $barcode = new Zend_Barcode_Object_Code39();
  54 $barcode->setOptions($options);
  55
  56 // Case 3: setConfig()
  57 $config  = new Zend_Config($options);
  58 $barcode = new Zend_Barcode_Object_Code39();
  59 $barcode->setConfig($config);
  60
  61 // Case 4: individual setters
  62 $barcode = new Zend_Barcode_Object_Code39();
  63 $barcode->setText('ZEND-FRAMEWORK')
  64         ->setBarHeight(40);
  65 ]]></programlisting>
  66     </example>
  67
  68     <sect2 id="zend.barcode.objects.common.options">
  69         <title>Common Options</title>
  70
  71         <para>
  72             In the following list, the values have no units; we will use the term "unit." For
  73             example, the default value of the "thin bar" is "1 unit". The real units depend on the
  74             rendering support (see <link linkend="zend.barcode.renderers">the renderers
  75                 documentation</link> for more information). Setters are each named by uppercasing
  76             the initial letter of the option and prefixing the name with "set" (e.g. "barHeight"
  77             becomes "setBarHeight"). All options have a corresponding getter prefixed with "get"
  78             (e.g. "getBarHeight"). Available options are:
  79         </para>
  80
  81         <table id="zend.barcode.objects.common.options.table">
  82             <title>Common Options</title>
  83
  84             <tgroup cols="4">
  85                 <thead>
  86                     <row>
  87                         <entry>Option</entry>
  88                         <entry>Data Type</entry>
  89                         <entry>Default Value</entry>
  90                         <entry>Description</entry>
  91                     </row>
  92                 </thead>
  93
  94                 <tbody>
  95                     <row>
  96                         <entry><emphasis>barcodeNamespace</emphasis></entry>
  97                         <entry><type>String</type></entry>
  98                         <entry><classname>Zend_Barcode_Object</classname></entry>
  99
 100                         <entry>
 101                             Namespace of the barcode; for example, if you need to extend the
 102                             embedding objects
 103                         </entry>
 104                     </row>
 105
 106                     <row>
 107                         <entry><emphasis>barHeight</emphasis></entry>
 108                         <entry><type>Integer</type></entry>
 109                         <entry>50</entry>
 110                         <entry>Height of the bars</entry>
 111                     </row>
 112                     <row>
 113                         <entry><emphasis>barThickWidth</emphasis></entry>
 114                         <entry><type>Integer</type></entry>
 115                         <entry>3</entry>
 116                         <entry>Width of the thick bar</entry>
 117                     </row>
 118
 119                     <row>
 120                         <entry><emphasis>barThinWidth</emphasis></entry>
 121                         <entry><type>Integer</type></entry>
 122                         <entry>1</entry>
 123                         <entry>Width of the thin</entry>
 124                     </row>
 125
 126                     <row>
 127                         <entry><emphasis>factor</emphasis></entry>
 128                         <entry><type>Integer</type></entry>
 129                         <entry>1</entry>
 130                         <entry>Factor by which to multiply bar widths and font sizes</entry>
 131                     </row>
 132
 133                     <row>
 134                         <entry><emphasis>foreColor</emphasis></entry>
 135                         <entry><type>Integer</type></entry>
 136                         <entry>0 (black)</entry>
 137
 138                         <entry>
 139                             Color of the bar and the text. Could be provided as an integer
 140                             or as a <acronym>HTML</acronym> value (e.g. "#333333")
 141                         </entry>
 142                     </row>
 143
 144                     <row>
 145                         <entry><emphasis>backgroundColor</emphasis></entry>
 146                         <entry><type>Integer</type> or <type>String</type></entry>
 147                         <entry>16777125 (white)</entry>
 148
 149                         <entry>
 150                             Color of the background. Could be provided as an integer
 151                             or as a <acronym>HTML</acronym> value (e.g. "#333333")
 152                         </entry>
 153                     </row>
 154
 155                     <row>
 156                         <entry><emphasis>reverseColor</emphasis></entry>
 157                         <entry><type>Boolean</type></entry>
 158                         <entry><constant>FALSE</constant></entry>
 159                         <entry>Allow switching the color of the bar and the background</entry>
 160                     </row>
 161
 162                     <row>
 163                         <entry><emphasis>orientation</emphasis></entry>
 164                         <entry><type>Integer</type></entry>
 165                         <entry>0</entry>
 166                         <entry>Orientation of the barcode</entry>
 167                     </row>
 168
 169                     <row>
 170                         <entry><emphasis>font</emphasis></entry>
 171                         <entry><type>String</type> or <type>Integer</type></entry>
 172                         <entry><constant>NULL</constant></entry>
 173
 174                         <entry>
 175                             Font path to a <acronym>TTF</acronym> font or a number between 1 and 5
 176                             if using image generation with GD (internal fonts)
 177                         </entry>
 178                     </row>
 179
 180                     <row>
 181                         <entry><emphasis>fontSize</emphasis></entry>
 182                         <entry><type>Integer</type></entry>
 183                         <entry>10</entry>
 184                         <entry>Size of the font (not applicable with numeric fonts)</entry>
 185                     </row>
 186
 187                     <row>
 188                         <entry><emphasis>withBorder</emphasis></entry>
 189                         <entry><type>Boolean</type></entry>
 190                         <entry><constant>FALSE</constant></entry>
 191                         <entry>Draw a border around the barcode and the quiet zones</entry>
 192                     </row>
 193
 194                     <row>
 195                         <entry><emphasis>withQuietZones</emphasis></entry>
 196                         <entry><type>Boolean</type></entry>
 197                         <entry><constant>TRUE</constant></entry>
 198                         <entry>Leave a quiet zone before and after the barcode</entry>
 199                     </row>
 200
 201                     <row>
 202                         <entry><emphasis>drawText</emphasis></entry>
 203                         <entry><type>Boolean</type></entry>
 204                         <entry><constant>TRUE</constant></entry>
 205                         <entry>Set if the text is displayed below the barcode</entry>
 206                     </row>
 207
 208                     <row>
 209                         <entry><emphasis>stretchText</emphasis></entry>
 210                         <entry><type>Boolean</type></entry>
 211                         <entry><constant>FALSE</constant></entry>
 212                         <entry>Specify if the text is stretched all along the barcode</entry>
 213                     </row>
 214
 215                     <row>
 216                         <entry><emphasis>withChecksum</emphasis></entry>
 217                         <entry><type>Boolean</type></entry>
 218                         <entry><constant>FALSE</constant></entry>
 219
 220                         <entry>
 221                             Indicate whether or not the checksum is automatically added to
 222                             the barcode
 223                         </entry>
 224                     </row>
 225
 226                     <row>
 227                         <entry><emphasis>withChecksumInText</emphasis></entry>
 228                         <entry><type>Boolean</type></entry>
 229                         <entry><constant>FALSE</constant></entry>
 230
 231                         <entry>
 232                             Indicate whether or not the checksum is displayed in the textual
 233                             representation
 234                         </entry>
 235                     </row>
 236
 237                     <row>
 238                         <entry><emphasis>text</emphasis></entry>
 239                         <entry><type>String</type></entry>
 240                         <entry><constant>NULL</constant></entry>
 241                         <entry>The text to represent as a barcode</entry>
 242                     </row>
 243                 </tbody>
 244             </tgroup>
 245         </table>
 246
 247         <sect3 id="zend.barcode.objects.common.options.barcodefont">
 248             <title>Particular case of static setBarcodeFont()</title>
 249
 250             <para>
 251                 You can set a commont font for all your objects by using the static method
 252                 <methodname>Zend_Barcode_Object::setBarcodeFont()</methodname>. This value
 253                 can be always be overridden for individual objects by using the
 254                 <methodname>setFont()</methodname> method.
 255             </para>
 256
 257             <programlisting language="php"><![CDATA[
 258 // In your bootstrap:
 259 Zend_Barcode_Object::setBarcodeFont('my_font.ttf');
 260
 261 // Later in your code:
 262 Zend_Barcode::render(
 263     'code39',
 264     'pdf',
 265     array('text' => 'ZEND-FRAMEWORK')
 266 ); // will use 'my_font.ttf'
 267
 268 // or:
 269 Zend_Barcode::render(
 270     'code39',
 271     'image',
 272     array(
 273         'text' => 'ZEND-FRAMEWORK',
 274         'font' => 3
 275     )
 276 ); // will use the 3rd GD internal font
 277 ]]></programlisting>
 278         </sect3>
 279     </sect2>
 280
 281     <sect2 id="zend.barcode.objects.common.getters">
 282         <title>Common Additional Getters</title>
 283
 284         <para></para>
 285
 286         <table id="zend.barcode.objects.common.getters.table">
 287             <title>Common Getters</title>
 288
 289             <tgroup cols="3">
 290                 <thead>
 291                     <row>
 292                         <entry>Getter</entry>
 293                         <entry>Data Type</entry>
 294                         <entry>Description</entry>
 295                     </row>
 296                 </thead>
 297
 298                 <tbody>
 299                     <row>
 300                         <entry><methodname>getType()</methodname></entry>
 301                         <entry><type>String</type></entry>
 302
 303                         <entry>
 304                             Return the name of the barcode class without the namespace (e.g.
 305                             <classname>Zend_Barcode_Object_Code39</classname> returns simply
 306                             "code39")
 307                         </entry>
 308                     </row>
 309
 310                     <row>
 311                         <entry><methodname>getRawText()</methodname></entry>
 312                         <entry><type>String</type></entry>
 313                         <entry>Return the original text provided to the object</entry>
 314                     </row>
 315
 316                     <row>
 317                         <entry><methodname>getTextToDisplay()</methodname></entry>
 318                         <entry><type>String</type></entry>
 319
 320                         <entry>
 321                             Return the text to display, including, if activated, the checksum value
 322                         </entry>
 323                     </row>
 324
 325                     <row>
 326                         <entry><methodname>getQuietZone()</methodname></entry>
 327                         <entry><type>Integer</type></entry>
 328
 329                         <entry>
 330                             Return the size of the space needed before and after the barcode
 331                             without any drawing
 332                         </entry>
 333                     </row>
 334
 335                     <row>
 336                         <entry><methodname>getInstructions()</methodname></entry>
 337                         <entry><type>Array</type></entry>
 338                         <entry>Return drawing instructions as an array.</entry>
 339                     </row>
 340
 341                     <row>
 342                         <entry><methodname>getHeight($recalculate = false)</methodname></entry>
 343                         <entry><type>Integer</type></entry>
 344
 345                         <entry>
 346                             Return the height of the barcode calculated after possible rotation
 347                         </entry>
 348                     </row>
 349
 350                     <row>
 351                         <entry><methodname>getWidth($recalculate = false)</methodname></entry>
 352                         <entry><type>Integer</type></entry>
 353
 354                         <entry>
 355                             Return the width of the barcode calculated after possible rotation
 356                         </entry>
 357                     </row>
 358
 359                     <row>
 360                         <entry><methodname>getOffsetTop($recalculate = false)</methodname></entry>
 361                         <entry><type>Integer</type></entry>
 362
 363                         <entry>
 364                             Return the position of the top of the barcode calculated after
 365                             possible rotation
 366                         </entry>
 367                     </row>
 368
 369                     <row>
 370                         <entry><methodname>getOffsetLeft($recalculate = false)</methodname></entry>
 371                         <entry><type>Integer</type></entry>
 372
 373                         <entry>
 374                             Return the position of the left of the barcode calculated after
 375                             possible rotation
 376                         </entry>
 377                     </row>
 378                 </tbody>
 379             </tgroup>
 380         </table>
 381     </sect2>
 382
 383     <xi:include href="Zend_Barcode-Objects_Details.xml" />
 384 </sect1>