           FvwmScript - module to build graphic user interface

## SYNOPSIS

           FvwmScript must be spawned by Fvwm.  It will not work from
           the command line.

## DESCRIPTION

           FvwmScript is a module which allows to build many  graphi-
           cal applications such as desktop accessories, button panel
           with popup menu, modal dialog...  At  the  startup,  Fvwm-
           Script  reads  the  file which is specified in the command
           line. This file contains the script.  This script  is  not
           included in the configuration file of Fvwm.

## INVOCATION

           FvwmScript  can  be  invoked by inserting the line `Module
           FvwmScript  name_of_script'  in  the  .fvwmrc  file.   All
           scripts used by FvwmScript are located in a directory whom
           is specified in .fvwmrc by the command line  `*FvwmScript-
           Path path_of_the_script_directory'.  This can be placed on
           a line by itself, if FvwmScript is to  be  spawned  during
           fvwm's  initialization, or can be bound to a menu or mouse
           button or keystroke to invoke it later. Fvwm  will  search
           directory specified in the ModulePath configuration option
           to attempt to locate FvwmScript.

           Be sure to set ModulePath in your .fvwmrc file to  include
           FvwmScript's path.

## ANATOMY OF A SCRIPT

           FvwmScript uses a particular programming langage. A script
           is composed of four parts. Heading contains general  char-
           acteristics  of  the window and default properties for all
           widgets. The second part contains  instructions  whom  are
           executed at the startup of the script. The third part con-
           tains periodic tasks whom is executed every 1 second.  And
           the last one contains the desciption of widgets.  A widget
           consists of eleven types of items:  text  labels,  single-
           line  text  inputs, radio buttons, checkbox, push buttons,
           horizontal and  vertical  scrollbars,  rectangles,  popup-
           menus, swallowexecs and mini scrollbars.

## HEADING OF A SCRIPT

           The syntaxe is as follow:

           WindowTitle string
                  This option sets the window title.

           WindowSize width height

           WindowPosition x y
                  This option sets  window  position.  x  and  y  are
                  numerical value.

           ForeColor {color}
                  This  option  sets the default foreground color for
                  all widgets.

           BackColor {color}
                  This option sets the default background  color  for
                  all widgets.

           HilightColor {color}
                  This  option sets the default hilight color for all
                  widgets.

           ShadowColor {color}
                  This option sets the default shadow color  for  all
                  widgets.

           Font {font}
                  This  option  sets  the  default font color for all
                  widgets.

## INITIALISATION

           This part contains instructions which will be executed  at
           the startup.  For example:

                Init
                 Begin
                  Do "Exec cat tada.voc > /dev/dsp"
                  WarpPointer 1
                  Set $ToDo=Restart
                 End

           These  instructions  are  used  to  play a sound, move the
           pointer to widget 1 and to initialize $ToDo  to  "Restart"
           at every startup.

## PERIODIC TASKS

           This  part  of  the script contains some instructions whom

                Periodic Task
                 Begin
                  If (RemainderOfDiv (GetTime) 10)==0 Then
                   Do {Exec xcalc}
                 End

           This example shows how to launch xcalc every 10 seconds.

## MAIN OF A SCRIPT

           The second part of the script contains the description for
           every  widget  which  will  be  used  in  the  program.  A
           description of widget is composed of two parts. Fisrt part
           describes  initial  properties  and  second  part contains
           instructions  which  will  be  executed  when  the  widget
           receives  messages.  All widgets can send and receive mes-
           sages. All message are identify by a number.  The  message
           "UserAction"  is  sent  to  a widget when user has altered
           this one. The syntax is as following:

                Widget         id   # Set the id widget
                Property
                 Type          string
                 Size width    height
                 Position      x y
                 Title         { string }
                 Value         int
                 MaxValue      int
                 MinValue      int
                 Font          string
                 ForeColor     { color }
                 BackColor     { color }
                 HilightColor  { color }
                 ShadowColor   { Color }
                 Flags         Hidden and/or NoReliefString

           The option 'Flags` is used to specify  if  the  widget  is
           hidden  or not and if strings are drew with relief or not.

                Main
                 Case Message of
                  SingleClic:
                  Begin
                   # list of instructions which will be
                   # executed when widget receives
                   # message "SingleClic". This message is
                   # generated by the user.
                  End
                  1:
                  Begin
                   # message 1
                  End
                 End

## LIST OF WIDGETS

           There is fifteen types of widgets.

           ItemDraw: Display an icon and/or a string.

                  Title: string to display.

                  Icon: icon to display.

           PushButton: Display push button with an icon and/or a
                  string.

                  Title:  this string has the following syntax {Title
                  of the button|Option 1|Option 2| Option3|...|Option
                  N}.  "Option  1|Option 2|...|Option N" is the popup
                  menu which is displayed  when  pressing  the  right
                  button.

                  Icon: icon to display.

           RadioButton: Display radio button with a string.

                  Title: title of the radio button.

                  Value:  if  Value is equal to 1, the box is checked
                  else it is not.

           CheckBox: Display check box with a string.

                  Title: title of the check box.

                  Value: if Value is equal to 1, the box  is  checked
                  else it is not.

           TextField:  Display  a text input field. The text input
                  field can be used to edit a single-line string.

                  Title: content of text field.

                  Value: position of the insert point.

                  Value: position of the thumb.

                  MaxValue: upper limit of Value.

                  MinValue: lower limit of Value.

           VScrollBar: Display a vertical scrollbar.

                  Value: position of the thumb.

                  MaxValue: upper limit of Value.

                  MinValue: lower limit of Value.

           MiniScrollBar: Display a very small vertical scrollbar.

                  Value: position of the thumb.

                  MaxValue: upper limit of Value.

                  MinValue: lower limit of Value.

           Rectangle:  Display  a rectangle. This type of widget can
                  be used to decorate window.

           SwallowExec:  This  type  of widget causes FvwmScript to
                  spawn an      process, and capture the first window
                  whose name or  resource  is     equal to Title, and
                  display it in the script window.

                  Title: specify the window name  which  be  captured
                  and displayed in the script window.

                  SwallowExec: specify the command line to execute to
                  spawn the process. Modules canalso be swallowed.

                  Value: specify the looking of the border.  Possible
                  value: -1, 0, 1.

           PopupMenu: Display a popup menu.

                  Value: specify what option is selected.

                  Title:  the title has the following syntax: {Option
                  1|Option    2|...|Option    N}."Option     1|Option
                  2|...|Option  N"  is  the  popup menu which is dis-
                  be used to display disk usage.

                  Value: specify the current value of the dipstick.

                  MinValue: specify the minimum  value  of  the  dip-
                  stick.

                  MaxValue:  specify  the  maximum  value of the dip-
                  stick.

           VDipstick: Display a vertical dipstick.

                  Value: specify the current value of the dipstick.

                  MinValue: specify the minimum  value  of  the  dip-
                  stick.

                  MaxValue:  specify  the  maximum  value of the dip-
                  stick.

           List: Display a list. List lets user to  choose  between
                  various options.

                  Value: specify which option is selected.

                  Title: title  contains  options  displayed  in  the
                  list.   The   syntaxe  is  the  following:  {Option
                  1|Option 2|...|Option N}. All menus  are  displayed
                  at the top of window.

           Menu: Display a menu whom lets user to choose a option.

                  Value: specify which option is selected.

                  Title:  title  contains  options  displayed  in the
                  menu.  The  syntaxe  is  the   following:   {Option
                  1|Option 2|...|Option N}.

## INSTRUCTIONS

           Here is the description of all instructions.

           HideWidget id : hide the widget numbered id.

           ShowWidget id: show the widget numbered id.

                  id1 to id2.

           ChangeMaxValue  id1 id2: set the maximum value of the
                  widget num- bered id1 to id2.

           ChangeMinValue  id1 id2: set the minimum value of the
                  widget num- bered id1 to id2.

           ChangeTitle  id1 id2: set the title of the widget numbered
                  id1 to id2.

           ChangeIcon  id1  id2:  set the icon of the widget numbered
                  id1 to id2.

           ChangeForeColor id1 {color}: set the foreground color of
                  the wid- get numbered id1 to {color}.

           ChangeBackColor id1 {color}: set the background color of
                  the wid- get numbered id1 to {color}.

           ChangePosition  id1 x y: move the widget numbered id1 to
                  position (x,y).

           ChangeSize  id1 width height: set the size of the widget
                  numbered id1 to (width,height).

           ChangeFont  id1  newfont: set the font of the widget
                  numbered id1 to newfont.

           WarpPointer  id:  warp the mouse pointer into the widget
                  numbered id.

           WriteToFile  filename  {str1} {str2} etc: write to the
                  file file-             name the string which is the
                  concatenation of all arguments str1, str2, etc.

           Do {str1} {str2} etc: execute the command which is the
                  concatena- tion of all arguments str1, str2, etc.

                  string and set the variable $var to this string.

           Quit: quit the program.

           SendSignal id1 id2: send a message numbered id2 to widget
                  id1.

           SendToScript id_script {str11} {str2} etc: send a message
                  to  the        script  identified by id_script. The
                  message is the concatenation of str1, str2...

## ARGUMENTS

           Most of commands use arguments.  There  is  two  kinds  of
           argument:  numbers and strings.  A numerical argument is a
           value which is between -32000  and  +32000.  A  string  is
           always  surrounded with brace. Variables always begin with
           the character "$" and can contains both number and string.

## FUNCTIONS

           All  functions  are used as argument. Functions can return
           both string and number.  The syntax is:

                (function argument1 argument2 etc)

           Here is the complete list of arguments:

           (GetTitle id): return the title of the widget numbered id.

           (GetValue  id):  return  the current value of the widget
                  numbered id.

           (GetOutput  {str}  int1 int2): executes the command str,
                  gets the standart output and returns the word which
                  is in  the  line  int1       and  in  the  position
                  int2.  If  int2 is equal to -1, GetOutput   returns
                  the complete line.

           (NumToHex int): return the hexadecimal value of int.

           (HexToNum {str}): return the decimal value of str, str
                  must be an hexadecimal value.

           (Mult int1 int2): return the result of (int1*int2).

           (Div int1 int2): return the result of (int1/int2).

           (StrCopy {str} int1 int2): return  the  string  whom  is
                  between   position  int1  and  int2.  For  example,
                  (StrCopy  {Hello} 1 2) returns {He}

           (LaunchScript {str}): this function launch the script
                  named  str    and  return an identification number.
                  This number is necessary to     use these functions
                  SendToScript and ReceivFromScript. The string   str
                  contains the script name and some arguments.

           (GetScriptArgument  {int}):  this  function  return  the
                  argument  script used in the function LaunchScript.
                  If  int  is  equal  to      zero, GetScriptArgument
                  return the name of the script.

           (GetScriptFather): this function return the identification
                  number of the script father.

           (ReceivFromScript {int}): this function return the message
                  sended by the script numbered int.

           (RemainderOfDiv {int1 int2}): this function return the
                  remainder of the division (int1/int2).

           (GetTime): this function return the time in second.

## CONDITIONAL LOOPS

           There is three kind of conditional loops. The  instruction
           "If-Then-Else" has the following syntax:

                If $ToDo=={Open xcalc} Then
                 Do {Exec xcalc &}            # List of instructions
                Else
                Begin
                 Do {Exec killall xcalc &}    # List of instructions
                 Do {Exec echo xcalc killed > /dev/console}
                End

           contains only one instruction, Begin and End can be  omit-
           ted. The instruction "While-Do" as the following syntax:

                While $i<5 Do
                Begin
                 Set $i=(Add i 1)             # List of instructions
                End

           Two  strings can be compared with "==" and two numbers can
           be compared with "<", "<=",  "==",  ">=",  ">".  The  loop
           "For-Do-Begin-End" has the following syntax:

                For $i=1 To 20 Do
                Begin
                 Do {Exec xcalc &}            # List of instructions
                End

## AUTHOR

                  Frederic   Cordier   (cordie97@cui.unige.ch  or  f-
           cord96@univ-lyon1.fr).

## CONTRIBUTOR

                  Eddy J. Gurney (eddy@gizmo.aa.ans.net).