repo_zf1/documentation/manual/en/module_specs/Zend_Text_Figlet.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.text.figlet">
    <title>Zend_Text_Figlet</title>

    <para>
        <classname>Zend_Text_Figlet</classname> is a component which enables developers to
        create a so called FIGlet text. A FIGlet text is a string, which is
        represented as <acronym>ASCII</acronym> art. FIGlets use a special font format, called
        FLT (FigLet Font). By default, one standard font is shipped with
        <classname>Zend_Text_Figlet</classname>, but you can download additional fonts at
        <ulink url="http://www.figlet.org/fontdb.cgi">http://www.figlet.org</ulink>.
    </para>

    <note>
        <title>Compressed fonts</title>

        <para>
            <classname>Zend_Text_Figlet</classname> supports gzipped fonts. This means that
            you can take an <filename>.flf</filename> file and gzip it. To allow
            <classname>Zend_Text_Figlet</classname> to recognize this, the gzipped font
            must have the extension <filename>.gz</filename>. Further, to be able to use
            gzipped fonts, you have to have enabled the GZIP extension of <acronym>PHP</acronym>.
        </para>
    </note>

    <note>
        <title>Encoding</title>

        <para>
            <classname>Zend_Text_Figlet</classname> expects your strings to be UTF-8 encoded
            by default. If this is not the case, you can supply the character
            encoding as second parameter to the <methodname>render()</methodname> method.
        </para>
    </note>

    <para>
        You can define multiple options for a FIGlet. When instantiating
        <classname>Zend_Text_Figlet</classname>, you can supply an array or an instance of
        <classname>Zend_Config</classname>.

        <itemizedlist>
            <listitem>
                <para>
                    <property>font</property> - Defines the font which should be used
                    for rendering. If not defines, the built-in font will be
                    used.
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>outputWidth</property> - Defines the maximum width of the
                    output string. This is used for word-wrap as well as
                    justification. Beware of too small values, they may result
                    in an undefined behaviour. The default value is 80.
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>handleParagraphs</property> - A boolean which indicates,
                    how new lines are handled. When set to <constant>TRUE</constant>, single new
                    lines are ignored and instead treated as single spaces. Only multiple
                    new lines will be handled as such. The default value is
                    <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>justification</property> - May be one of the values of
                    <classname>Zend_Text_Figlet::JUSTIFICATION_*</classname>. There is
                    <constant>JUSTIFICATION_LEFT</constant>,
                    <constant>JUSTIFICATION_CENTER</constant> and
                    <constant>JUSTIFICATION_RIGHT</constant> The default justification
                    is defined by the <property>rightToLeft</property> value.
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>rightToLeft</property> - Defines in which direction the
                    text is written. May be either
                    <constant>Zend_Text_Figlet::DIRECTION_LEFT_TO_RIGHT</constant> or
                    <constant>Zend_Text_Figlet::DIRECTION_RIGHT_TO_LEFT</constant>. By
                    default the setting of the font file is used. When justification
                    is not defined, a text written from right-to-left is
                    automatically right-aligned.
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>smushMode</property> - An integer bitfield which defines,
                    how the single characters are smushed together. Can be the
                    sum of multiple values from <classname>Zend_Text_Figlet::SM_*</classname>.
                    There are the following smush modes: SM_EQUAL, SM_LOWLINE,
                    SM_HIERARCHY, SM_PAIR, SM_BIGX, SM_HARDBLANK, SM_KERN and
                    SM_SMUSH. A value of 0 doesn't disable the entire smushing,
                    but forces SM_KERN to be applied, while a value of -1 disables
                    it. An explanation of the different smush modes can be found
                    <ulink url="http://www.jave.de/figlet/figfont.txt">here</ulink>.
                    By default the setting of the font file is used. The smush mode
                    option is normally used only by font designers testing the various
                    layoutmodes with a new font.
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <example id="zend.text.figlet.example.using">
        <title>Using Zend_Text_Figlet</title>

        <para>
            This example illustrates the basic use of <classname>Zend_Text_Figlet</classname>
            to create a simple FIGlet text:
        </para>

        <programlisting language="php"><![CDATA[
$figlet = new Zend_Text_Figlet();
echo $figlet->render('Zend');
]]></programlisting>

        <para>
            Assuming you are using a monospace font, this would look as follows:
        </para>

        <programlisting language="text"><![CDATA[
  ______    ______    _  __   ______
 |__  //   |  ___||  | \| || |  __ \\
   / //    | ||__    |  ' || | |  \ ||
  / //__   | ||___   | .  || | |__/ ||
 /_____||  |_____||  |_|\_|| |_____//
 `-----`'  `-----`   `-` -`'  -----`
]]></programlisting>
    </example>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->