
ACTIONS
     An action is a  command  performed  when  a  user  interface
     object  has  changed  its  state. e.g. a button is pushed, a
     list item is chosen, a slider is moved. Actions ca be speci-
     fied in two forms, the simple "action={}" syntax or the con-
     ditional "test={}" syntax. If more than one action  or  test
     is  specified  for  an  object then the separate actions are
     performed in the order in which they are  specified  in  the
     script file.

     There are seven basic types of action  NONE,  QUIT,  SYSTEM,
     PRINT, STRING, ASSIGN, and SET.

     If no action is specified (or the  action  is  specified  as
     "NONE") the action type is NONE. In this case an object will
     just maintain its string representation.  For  dialogs,  the
     string  is  the contents of the text field; for sliders, the
     slider value; for choice, menubutton and list  objects,  the
     value associated with the selected item. When an object with
     action=NONE is modified, its string is kept up to date,  but
     nothing else happens.


     The next five action types (QUIT, SYSTEM, PRINT, STRING  and
     ASSIGN)  are  more complicated.  Each uses the format speci-
     fied in the action command to generate a string.

     If the action is QUIT, the string is converted to an integer
     (using  "atoi").   The  xtpanel program then quits using the
     integer as its exit code.  The simple quit button is written
     as:
     button={ label=QUIT action=QUIT }

     If the action is SYSTEM, then that string  is  executed.  If
     the  action  type is PRINT then the string is printed to the
     standard output. If the action is STRING then the string  is
     stored as the internal string representation of the object.

     If the action type is ASSIGN the value of the  other  object
     is set to the string. Additionally the screen representation
     of the object is updated to reflect the  new  value  (if  it
     makes sense to do so).  For example if the value of a dialog
     is updated the text field of the  dialog  will  contain  the
     updated string. If a slider is updated the slider thumb will
     be moved to the corresponding position.

     The format  specified  can  contain  the  names  of  objects
     preceded by a dollar "$" sign. The value of the string asso-
     ciated with the  object  is  substituted  in  the  generated
     string.  The  special  symbol "$val" is used to refer to the
     string associated with the current object.  An  object  name
     can  be  enclosed  in brackets to avoid syntactic ambiguity.
     You can use "$(val)" or "$val", the  first  form  is  recom-
     mended.  If  you do not enclose the name in brackets it will
     be assumed to end at the next space, dollar sign  or  quote.
     You  should  give  an object a name if you intend to use its
     string in the action of another  object.   A  double  dollar
     sign  "$$"  is  used to generate a single dollar in the gen-
     erated string.

     The rules for expanding a format  string  are  the  same  as
     those  described above for general strings in scripts. First
     the values of  other  objects  are  expanded  and  then  any
     backquoted  strings  are  evaluated. The major difference in
     actions is that the format  string  is  expanded  at  action
     time.  This means that the object value in the string is the
     value at action time. However it also means that  you  won't
     be informed of any errors until action time.

     The ASSIGN action is special because  the  word  immediately
     following  the word ASSIGN (separated by blanks) is the name
     of an object that will have its value modified.  The  format
     is thus assumed to start at the second word after ASSIGN.

     The SET action is  another  special  case.  The  set  action
     allows  you to modify not the value of an object, but one of
     its resources, such as foreground or background color, font,
     orientation,  etc.   The word immediately following the word
     SET is the name of the object; the next word is the resource
     you  wish  to set. Following that is the resource specifica-
     tion.  See the section above on MISCELLANEOUS PARAMETERS  to
     see which attributes can be changed with the SET action.

     An action type of PRINT is used for any action command  that
     begins with PRINT (It must be in upper case and start at the
     first character of the action string).  An  action  type  of
     STRING  is  used for any command that begins with STRING. An
     action type of ASSIGN is used for any  command  that  begins
     with  the word ASSIGN. An action type of SET is used for any
     command that begins with SET.  An action type of  SYSTEM  is
     used  for  any command that doesn't begin with QUIT, STRING,
     PRINT, SET or ASSIGN or if it begins with SYSTEM.


     Following are two examples of using actions.

     Here is a choice object that uses its value as  a  parameter
     for an imaginary system command, showcolor:

     choice={ label=colors value="255 0 0" action="showcolor -rgb $(val)"
              item={ label=red value="255 0 0" }
              item={ label=green value="0 255 0" }
              item={ label=blue value="0 0 255" }
            }

     In this next example, the list item has no action specified.
     Actions  default  to  type  NONE;  the  list will maintain a
     string containing the value of the selected list  item,  but
     will  do nothing more.  Here a separate button is used to do
     something with the list's output:

     message={ label="press button to find out which item is selected" }
     list={ label=numbers name=listout
              itemlist={ list="1 2 3"
            }
     button={ label="press for answer"
              action="PRINT list selection is $(listout)" }

     In this example the assign action is used to reset the value
     of  a  dialog  to  a  known  string (fred). The reset button
     assigns the string to the dialog.  The dialog itself has two
     actions,  the  first  prints the value of the text field and
     the second action quits xtpanel.

     dialog={ label=dialog value="fred"
              action="PRINT I am $(val)"
              action=QUIT
            }

     button={ label=RESET action="ASSIGN dialog fred" }


     In the final example the user can select a file from all the
     ".ps"  files  in  the  current  directory.  The file is then
     viewed with the ghostview program:

     button={ label=QUIT action=QUIT }
     list={ label="Choose a file" action="ghostview $(val)"
              itemlist={ list=`echo *.ps`  }
            }
