documentation/manual/en/module_specs/Zend_Text_Figlet.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.text.figlet">
   4     <title>Zend_Text_Figlet</title>
   5
   6     <para>
   7         <classname>Zend_Text_Figlet</classname> is a component which enables developers to
   8         create a so called FIGlet text. A FIGlet text is a string, which is
   9         represented as <acronym>ASCII</acronym> art. FIGlets use a special font format, called
  10         FLT (FigLet Font). By default, one standard font is shipped with
  11         <classname>Zend_Text_Figlet</classname>, but you can download additional fonts at
  12         <ulink url="http://www.figlet.org/fontdb.cgi">http://www.figlet.org</ulink>.
  13     </para>
  14
  15     <note>
  16         <title>Compressed fonts</title>
  17
  18         <para>
  19             <classname>Zend_Text_Figlet</classname> supports gzipped fonts. This means that
  20             you can take an <code>.flf</code> file and gzip it. To allow
  21             <classname>Zend_Text_Figlet</classname> to recognize this, the gzipped font
  22             must have the extension <code>.gz</code>. Further, to be able to use
  23             gzipped fonts, you have to have enabled the GZIP extension of <acronym>PHP</acronym>.
  24         </para>
  25     </note>
  26
  27     <note>
  28         <title>Encoding</title>
  29
  30         <para>
  31             <classname>Zend_Text_Figlet</classname> expects your strings to be UTF-8 encoded
  32             by default. If this is not the case, you can supply the character
  33             encoding as second parameter to the <methodname>render()</methodname> method.
  34         </para>
  35     </note>
  36
  37     <para>
  38         You can define multiple options for a FIGlet. When instantiating
  39         <classname>Zend_Text_Figlet</classname>, you can supply an array or an instance of
  40         <classname>Zend_Config</classname>.
  41
  42         <itemizedlist>
  43             <listitem>
  44                 <para>
  45                     <code>font</code> - Defines the font which should be used
  46                     for rendering. If not defines, the built-in font will be
  47                     used.
  48                 </para>
  49             </listitem>
  50
  51             <listitem>
  52                 <para>
  53                     <code>outputWidth</code> - Defines the maximum width of the
  54                     output string. This is used for word-wrap as well as
  55                     justification. Beware of too small values, they may result
  56                     in an undefined behaviour. The default value is 80.
  57                 </para>
  58             </listitem>
  59
  60             <listitem>
  61                 <para>
  62                     <code>handleParagraphs</code> - A boolean which indicates,
  63                     how new lines are handled. When set to <constant>TRUE</constant>, single new
  64                     lines are ignored and instead treated as single spaces. Only multiple
  65                     new lines will be handled as such. The default value is
  66                     <constant>FALSE</constant>.
  67                 </para>
  68             </listitem>
  69
  70             <listitem>
  71                 <para>
  72                     <code>justification</code> - May be one of the values of
  73                     <classname>Zend_Text_Figlet::JUSTIFICATION_*</classname>. There is
  74                     <constant>JUSTIFICATION_LEFT</constant>,
  75                     <constant>JUSTIFICATION_CENTER</constant> and
  76                     <constant>JUSTIFICATION_RIGHT</constant> The default justification
  77                     is defined by the <code>rightToLeft</code> value.
  78                 </para>
  79             </listitem>
  80
  81             <listitem>
  82                 <para>
  83                     <code>rightToLeft</code> - Defines in which direction the
  84                     text is written. May be either
  85                     <constant>Zend_Text_Figlet::DIRECTION_LEFT_TO_RIGHT</constant> or
  86                     <constant>Zend_Text_Figlet::DIRECTION_RIGHT_TO_LEFT</constant>. By
  87                     default the setting of the font file is used. When justification
  88                     is not defined, a text written from right-to-left is
  89                     automatically right-aligned.
  90                 </para>
  91             </listitem>
  92
  93             <listitem>
  94                 <para>
  95                     <code>smushMode</code> - An integer bitfield which defines,
  96                     how the single characters are smushed together. Can be the
  97                     sum of multiple values from <classname>Zend_Text_Figlet::SM_*</classname>.
  98                     There are the following smush modes: SM_EQUAL, SM_LOWLINE,
  99                     SM_HIERARCHY, SM_PAIR, SM_BIGX, SM_HARDBLANK, SM_KERN and
 100                     SM_SMUSH. A value of 0 doesn't disable the entire smushing,
 101                     but forces SM_KERN to be applied, while a value of -1 disables
 102                     it. An explanation of the different smush modes can be found
 103                     <ulink url="http://www.jave.de/figlet/figfont.txt">here</ulink>.
 104                     By default the setting of the font file is used. The smush mode
 105                     option is normally used only by font designers testing the various
 106                     layoutmodes with a new font.
 107                 </para>
 108             </listitem>
 109         </itemizedlist>
 110     </para>
 111
 112     <example id="zend.text.figlet.example.using">
 113         <title>Using Zend_Text_Figlet</title>
 114
 115         <para>
 116             This example illustrates the basic use of <classname>Zend_Text_Figlet</classname>
 117             to create a simple FIGlet text:
 118         </para>
 119
 120         <programlisting language="php"><![CDATA[
 121 $figlet = new Zend_Text_Figlet();
 122 echo $figlet->render('Zend');
 123 ]]></programlisting>
 124
 125         <para>
 126             Assuming you are using a monospace font, this would look as follows:
 127         </para>
 128
 129         <programlisting language="text"><![CDATA[
 130   ______    ______    _  __   ______
 131  |__  //   |  ___||  | \| || |  __ \\
 132    / //    | ||__    |  ' || | |  \ ||
 133   / //__   | ||___   | .  || | |__/ ||
 134  /_____||  |_____||  |_|\_|| |_____//
 135  `-----`'  `-----`   `-` -`'  -----`
 136 ]]></programlisting>
 137     </example>
 138 </sect1>
 139 <!--
 140 vim:se ts=4 sw=4 et:
 141 -->