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

  <refnamediv>
    <refname>FLbutton</refname>
    <refpurpose>
      A FLTK widget opcode that creates a button.
      <indexterm id="IndexFlbutton"><primary>FLbutton</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      A FLTK widget opcode that creates a button.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis>kout, ihandle <command>FLbutton</command> &quot;label&quot;, ion, ioff, itype, iwidth, iheight, ix, iy, iopcode [, kp1] [, kp2] [, kp3] [, kp4] [, kp5] [....] [, kpN]</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>FLbutton</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 the corresponding widget.
    </para>

    <para>
      Notice that with <emphasis>FLbutton</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>ion</emphasis> -- value output when the button is checked.
    </para>

    <para>
      <emphasis>ioff</emphasis> -- value output when the button is unchecked.
    </para>

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

    <para>
      Several kind of buttons are possible, according to the value of <emphasis>itype</emphasis> argument:

      <itemizedlist>
        <listitem><para>1 - normal button</para></listitem>
        <listitem><para>2 - light button</para></listitem>
        <listitem><para>3 - check button</para></listitem>
        <listitem><para>4 - round button</para></listitem>
      </itemizedlist>
    </para>

    <para>
      This is the appearance of the buttons:

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

        <textobject>
          <phrase>FLbutton.</phrase>
        </textobject>

        <caption>
          <para>FLbutton.</para>
        </caption>
      </mediaobject>
    </para>

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

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

    <para>
      <emphasis>ix</emphasis> -- horizontal position of 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 upper left corner of the valuator, relative to the upper left corner of corresponding window (expressed in pixels).
    </para>

    <para>
      <emphasis>iopcode</emphasis> -- score opcode type. You have to provide the ascii code of the letter corresponding to the score opcode. At present time only <quote>i</quote> (ascii code 105) score statements are supported. A zero value refers to a default value of <quote>i</quote>. So both 0 and 105 activates the <link linkend="i"><citetitle>i</citetitle></link> opcode. A value of -1 disables this opcode feature.
    </para>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kout</emphasis> -- output value
    </para>

    <para>
      <emphasis>kp1</emphasis>, <emphasis>kp2</emphasis>, ..., <emphasis>kpN</emphasis> -- arguments of the activated instruments.
    </para>

    <para>
      Buttons of type 2, 3, and 4 also output (<emphasis>kout</emphasis> argument) the value contained in the <emphasis>ion</emphasis> argument when checked, and that contained in <emphasis>ioff</emphasis> argument when unchecked.
    </para>

    <para>
      By adding 10 to <emphasis>itype</emphasis> argument (i.e. by setting 11 for type 1, 12 for type 2, 13 for type 3 and 14 for type 4) it is possible to skip the button value when getting/setting snapshots (see later section). <emphasis>FLbutton</emphasis> not only outputs a value, but can also activate (or schedule) an instrument provided by the user each time a button is pressed. 
    </para>

    <para>
      If the <emphasis>iopcode</emphasis> argument is set to a negative number, no instrument is activated. So this feature is optional. In order to activate an instrument, <emphasis>iopcode</emphasis> must be set to 0 or to 105 (the ascii code of character <quote>i</quote>, referring to the <link linkend="i"><citetitle>i</citetitle></link> score opcode). 
    </para>

    <para>
      P-fields of the activated instrument are <emphasis>kp1</emphasis> (instrument number), <emphasis>kp2</emphasis> (action time), <emphasis>kp3</emphasis> (duration) and so on with user p-fields. Notice that in dual state buttons (light button, check button and round button), the instrument is activated only when button state changes from unchecked to checked (not when passing from checked to unchecked).
    </para>
  </refsect1>

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

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

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

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

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="flbox"><citetitle>FLbox</citetitle></link>,
      <link linkend="flbutbank"><citetitle>FLbutBank</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>
