<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="flbox">
  <refmeta>
    <refentrytitle>FLbox</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>FLbox</refname>
    <refpurpose>
      A FLTK widget that displays text inside of a box.
      <indexterm id="IndexFlbox"><primary>FLbox</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      A FLTK widget that displays text inside of a box.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis>ihandle <command>FLbox</command> &quot;label&quot;, itype, ifont, isize, iwidth, iheight, ix, iy [, image]</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ihandle</emphasis> -- a handle value (an integer number) that unequivocally references a corresponding widget. This is used by other opcodes that modify a widget's properties (see <link linkend="ControlFltkAppearance"><citetitle>Modifying FLTK Widget Appearance</citetitle></link>). It is automatically output by <emphasis>FLbox</emphasis> and must not be set by the user label. (The user label is a double-quoted string containing some user-provided text placed near the widget.)
    </para>
    <para>
      <emphasis><quote>label</quote></emphasis> -- a double-quoted string containing some user-provided text, placed near corresponding widget.
    </para>

    <para>
      Notice that with <emphasis>FLbox</emphasis>, it is not necessary to call the <link linkend="flsettexttype"><citetitle>FLsetTextType</citetitle></link> opcode at all in order to use a symbol. In this case, it is sufficient to set a label starting with <quote>@</quote> followed by the proper formatting string.
    </para>

    <para>
      The following symbols are supported:

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/symbols.png" format="PNG">
        </imageobject>

        <textobject>
          <phrase>FLTK label supported symbols.</phrase>
        </textobject>

        <caption>
          <para>FLTK label supported symbols.</para>
        </caption>
      </mediaobject>
    </para>

    <para>
      The @ sign may be followed by the following optional <quote>formatting</quote> characters, in this order:

      <orderedlist>
        <listitem><para><quote>#</quote> forces square scaling rather than distortion to the widget's shape.</para></listitem>
        <listitem><para>+[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.</para></listitem>
        <listitem><para>[1-9] rotates by a multiple of 45 degrees. <quote>6</quote> does nothing, the others point in the direction of that key on a numeric keypad.</para></listitem>
      </orderedlist>
    </para>

    <para>
      <emphasis>itype</emphasis> -- an integer number denoting the appearance of the widget.
    </para>

    <para>
      The following values are legal for <emphasis>itype</emphasis>:
      <itemizedlist>
        <listitem><para>1 - flat box</para></listitem>
        <listitem><para>2 - up box</para></listitem>
        <listitem><para>3 - down box</para></listitem>
        <listitem><para>4 - thin up box</para></listitem>
        <listitem><para>5 - thin down box</para></listitem>
        <listitem><para>6 - engraved box</para></listitem>
        <listitem><para>7 - embossed box</para></listitem>
        <listitem><para>8 - border box</para></listitem>
        <listitem><para>9 - shadow box</para></listitem>
        <listitem><para>10 - rounded box</para></listitem>
        <listitem><para>11 - rounded box with shadow</para></listitem>
        <listitem><para>12 - rounded flat box</para></listitem>
        <listitem><para>13 - rounded up box</para></listitem>
        <listitem><para>14 - rounded down box</para></listitem>
        <listitem><para>15 - diamond up box</para></listitem>
        <listitem><para>16 - diamond down box</para></listitem>
        <listitem><para>17 - oval box</para></listitem>
        <listitem><para>18 - oval shadow box</para></listitem>
        <listitem><para>19 - oval flat box</para></listitem>
      </itemizedlist>
    </para>

    <para>
      <emphasis>ifont</emphasis> -- an integer number denoting the font of <emphasis>FLbox</emphasis>.
    </para>

    <para>
      <emphasis>ifont</emphasis> argument to set the font type. The following values are legal for <emphasis>ifont</emphasis>:
      <itemizedlist>
        <listitem><para>1 - helvetica (same as &quot;Arial&quot; under Windows)</para></listitem>
        <listitem><para>2 - helvetica bold</para></listitem>
        <listitem><para>3 - helvetica italic</para></listitem>
        <listitem><para>4 - helvetica bold italic</para></listitem>
        <listitem><para>5 - courier</para></listitem>
        <listitem><para>6 - courier bold</para></listitem>
        <listitem><para>7 - courier italic</para></listitem>
        <listitem><para>8 - courier bold italic</para></listitem>
        <listitem><para>9 - times</para></listitem>
        <listitem><para>10 - times bold</para></listitem>
        <listitem><para>11 - times italic</para></listitem>
        <listitem><para>12 - times bold italic</para></listitem>
        <listitem><para>13 - symbol</para></listitem>
        <listitem><para>14 - screen</para></listitem>
        <listitem><para>15 - screen bold</para></listitem>
        <listitem><para>16 - dingbats</para></listitem>
      </itemizedlist>
    </para>

    <para>
      <emphasis>isize</emphasis> -- size of the font.
    </para>

    <para>
      <emphasis>iwidth</emphasis> -- width of widget.
    </para>

    <para>
      <emphasis>iheight</emphasis> -- height of widget.
    </para>

    <para>
      <emphasis>ix</emphasis> -- horizontal position of the upper left corner of the valuator, relative to the upper left corner of corresponding window. (Expressed in pixels.)
    </para>

    <para>
      <emphasis>iy</emphasis> -- vertical position of the upper left corner of the valuator, relative to the upper left corner of corresponding window. (Expressed in pixels.)
    </para>

    <para>
      <emphasis>image</emphasis> -- a handle referring to an eventual image opened with <emphasis>bmopen</emphasis> opcode. If it is set, it allows a skin for that widget.
    </para>

    <note>
      <title>Note about the bmopen opcode</title>
      <para>
        Although the documentation mentions the <emphasis>bmopen</emphasis> opcode, it has not been implemented in Csound 4.22.
      </para>
    </note>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>FLbox</emphasis> is useful to show some text in a window. The text is bounded by a box, whose aspect depends on <emphasis>itype</emphasis> argument. 
    </para>

    <para>
      Note that <emphasis>FLbox</emphasis> is not a valuator and its value is fixed. Its value cannot be modified.
    </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the flbox opcode. It uses the files <ulink url="examples/flbox.orc"><citetitle>flbox.orc</citetitle></ulink> and <ulink url="examples/flbox.sco"><citetitle>flbox.sco</citetitle></ulink>.

      <example>
        <title>Example of the flbox opcode.</title>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/flbox.orc" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/flbox.sco" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>
      </example>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="flbutbank"><citetitle>FLbutBank</citetitle></link>,
      <link linkend="flbutton"><citetitle>FLbutton</citetitle></link>,
      <link linkend="flprintk"><citetitle>FLprintk</citetitle></link>,
      <link linkend="flprintk2"><citetitle>FLprintk2</citetitle></link>,
      <link linkend="flvalue"><citetitle>FLvalue</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>Author: &namegabriel;</para>
    <para>New in version 4.22</para>
    <para>Example written by Iain McCurdy, edited by &namekevin;.</para>
  </refsect1>
</refentry>
