
<section id='WCF_SymbolicFieldsTextControl_id'>
    <title>
        Symbolic Fields Text Control
    </title>
    <para>
        A Symbolic Field Text Control allows you to enter text that contains
        <termtext> symbolic fields</termtext>: placeholders for information
        that is automatically inserted when the text is displayed. For
        example, in the text "You are using {AppName} version {AppVersion}",
        {AppName} and {AppVersion} are fields representing, respectively,
        the name and version of the application you are using. The text
        would be displayed as "You are using &app_name; version &app_version;".
    </para>
    <para>
        A Symbolic Fields Text Control is a text control with a button
        located to its right.
    </para>
    <exhibit>
        <img src='WCF_SymbolicFieldsTextControl_Figure_Control.png'/>
    </exhibit>
    <para>
        Edit the text as you would using a regular text control. To insert
        a symbolic field at the caret location, either press <keytext>Alt
        + Space Bar</keytext>, or press the Insert Symbolic Field button
        <img src='WCF_SymbolicFieldsTextControl_InsertFieldButton_ScreenCap.png'/>. The Select Symbolic
        Field To Insert dialog box is displayed.
    </para>
    <exhibit>
        <img
        src='WCF_SymbolicFieldsTextControl_Figure_SelectFieldDialogBox.png'/>
    </exhibit>
    <para>
        Select the symbol to insert, then press the OK button.
    </para>
    <para>
        Note that the list of symbols is hierarchical. Click on one of
        the small + signs to display subsymbols. Often, these subsymbols
        are alternative ways of formatting the parent symbol. For example,
        in the screen capture of the Select Symbolic Field To Insert dialog
        box above, symbols for several ways of formatting the current
        time are shown.
    </para>
    <section>
    <title>Conditional Inclusion of Text</title>
    <para>
        It is possible to conditionally include text based upon the value of a symbol.  For
        example, suppose you are working with a weather data application that defines
        the symbols {Temp}, {Rain}, and {Wind}; these symbols represent the
        current temperature, rainfall, and wind speed, respectively.  You want the
        temperature and humidity to always be displayed, but the rainfall to be displayed
        only if it is greater than zero.  You can do so by using the following symbolic text:
    </para>
    <pre>
    Temperature = {Temp} F
    {IfNotZero {Rain} Rainfall = {Rain} inches
    }Wind Speed = {Wind} miles/hour
  </pre>
    <para>
         If the {Rain} symbol expanded to, say, 1.5, then the text would appear as...
    </para>
<pre>
    Temperature = 75 F
    Rainfall = 1.5 inches
    Wind Speed = 8 miles/hour
</pre>
    <para>
        If, however, the {Rain} symbol expanded to 0, then the text would appear as...
    </para>
<pre>
    Temperature = 75 F
    Wind Speed = 8 miles/hour
</pre>
    <para>
        IfNotZero is a special command symbol that is followed by a symbol name and
        some additional text.  If the symbol name expands to 0, then the additional text
        is discarded.  Note that the additional text can itself contain symbols.
    </para>
    <para>
        IfNotZero is intended to be used with symbols that expand to numeric values.
        There is a corresponding command, IfNotNull, that is used with symbols that
        expand to text --- the additional text is discarded if the symbol expands to
        the null string (i.e., to zero-length text).
    </para>
    </section>
</section>

