repo_zf1Php7/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 ASCII 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 <code>.flf</code> file and gzip it. To allow
            <classname>Zend_Text_Figlet</classname> to recognize this, the gzipped font
            must have the extension <code>.gz</code>. Further, to be able to use
            gzipped fonts, you have to have enabled the GZIP extension of PHP.
        </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 <code>render()</code> 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>
                    <code>font</code> - Defines the font which should be used
                    for rendering. If not defines, the built-in font will be
                    used.
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>outputWidth</code> - 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>
                    <code>handleParagraphs</code> - A boolean which indicates,
                    how new lines are handled. When set to true, 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>
                    <code>justification</code> - May be one of the values of
                    <classname>Zend_Text_Figlet::JUSTIFICATION_*</classname>. There is
                    <code>JUSTIFICATION_LEFT</code>, <code>JUSTIFICATION_CENTER</code>
                    and <code>JUSTIFICATION_RIGHT</code> The default justification
                    is defined by the <code>rightToLeft</code> value.
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>rightToLeft</code> - Defines in which direction the
                    text is written. May be either
                    <classname>Zend_Text_Figlet::DIRECTION_LEFT_TO_RIGHT</classname> or
                    <classname>Zend_Text_Figlet::DIRECTION_RIGHT_TO_LEFT</classname>. 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>
                    <code>smushMode</code> - 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:
-->