Apply window-jump fix (D. Fries).

[fvwm.git] / modules / FvwmScript / FvwmScript.1.in

.\" t
.\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
.de EX          \"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.ta .3i .6i .9i 1.2i 1.5i 1.8i
.TH FvwmScript 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
.UC

.SH NAME
FvwmScript - module to build graphic user interface

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

.SH DESCRIPTION
FvwmScript is a module which allows you to build many graphical
applications such as desktop accessories, button panel with pop up
menus, modal dialogs... At the startup, FvwmScript reads
the file which is specified on the command line. This file contains the script.
This script is not included in the configuration file of Fvwm.

An FvwmScript script is fully controllable by using the keyboard.
(Shift)-Tab circulates around the widgets, Return simulates a mouse
click, the arrows move the cursor or change the values of the
widget and Escape "cancels" for Menu and PopupMenu.

.SH INVOCATION
FvwmScript can be invoked by inserting the line `Module
FvwmScript name_of_script' in the .fvwm2rc file.
The file "name_of_script" can start with a slash, in which case, it's
a fully qualified path, and the file is read.
If "name_of_script" does not start with a slash, FvwmScript will look
in a few different places.
If  the   .fvwm2rc contained   the  command  line  `*FvwmScript: Path
path_of_the_script_directory', FvwmScript will try that directory.
If that doesn't work, FvwmScript tries the system configuration directory
and the user configuration directory as described under the "Read"
command in the fvwm man page.

The command to start FvwmScript 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.

.SH CONFIGURATION OPTIONS
The following commands can be used in the config file (see
.IR fvwm (1),
section
.B "MODULE COMMANDS"
for details). They are used
only if the corresponding script commands are not used in the script.

.IP "*FvwmScript: DefaultFont \fIfont\fP"
Specifies the default font to be used. If not specified with this command
or in the script with the Font command, fixed font is assumed.

.IP "*FvwmScript: DefaultFore \fIcolor\fP"
Specifies the default foreground color to be used. If not specified with
this command or in the script with the ForeColor command, black is used.

.IP  "*FvwmScript: DefaultBack \fIcolor\fP"
Specifies the default background color to be used. If not specified with
this command or in the script with the BackColor command, grey85 is used.

.IP  "*FvwmScript: DefaultHilight \fIcolor\fP"
Specifies the default hilight color to be used. If not specified with
this command or in the script with the HilightColor command, grey100 is used.

.IP  "*FvwmScript: DefaultShadow \fIcolor\fP"
Specifies the default shadow color to be used. If not specified with this
command or in the script with the ShadowColor command, grey55 is used.

.IP "*FvwmScript: DefaultColorset \fIcolorset\fP"
Tells the module to use colorset \fIcolorset\fP as the default colorset.
Refer to the FvwmTheme man page for details about
colorsets.

.SH ANATOMY OF A SCRIPT
FvwmScript uses a particular programming language. A script is composed of
five parts. Heading contains general characteristics 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 contains periodic tasks which are executed every second.
The fourth part contains instructions which are executed at exit.
And the last part contains the description 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, pop up menus, swallowexecs and mini scrollbars.

.SH HEADING OF A SCRIPT
The syntax is as follows:

.IP "WindowTitle \fIstring\fP"
This option sets the window title.

.IP "WindowSize \fIwidth height\fP"
This option sets window size. \fIwidth\fP and \fIheight\fP are numerical value.

.IP "WindowPosition \fIx y\fP"
This option sets window position. \fIx\fP and \fIy\fP are numerical value.

.IP "ForeColor {\fIcolor\fP}"
This option sets the default foreground color for all widgets.

.IP "BackColor {\fIcolor\fP}"
This option sets the default background color for all widgets.

.IP "HilightColor {\fIcolor\fP}"
This option sets the default hilight color for all widgets.

.IP "ShadowColor {\fIcolor\fP}"
This option sets the default shadow color for all widgets.

.IP "Colorset {\fIn\fP}"
This option sets the default colorset for all widgets.

.IP "Font {\fIfont\fP}"
This option sets the default font for all widgets.

.IP "UseGettext  [\fIlocale_path\fP]"
Enable the use of the gettext mechanism which is used by the
WindowLocaleTitle, LocaleTitle, ChangeLocaleTitle instructions and
the Gettext function.
If no argument is given, the default FvwmScript locale catalog is used.
This catalog is under the locale fvwm installation directory and the text
domain is FvwmScript (install_prefix/share/locale/*/LC_MESSAGES/FvwmScript.mo).
You can reset this catalog or add some catalogs exactly in the same way
than with the
.B LocalePath
fvwm command (see the fvwm manual page).
This instruction should be placed before the WindowLocaleTitle
instruction.

.IP "WindowLocaleTitle \fIstring\fP"
This option sets the window title, but use the locale catalog(s) defined
with UseGettext.

.SH INITIALISATION
This part contains instructions which will be executed at the startup.
For example:
.EX
Init
 Begin
  Do "Exec cat tada.voc > /dev/dsp"
  WarpPointer 1
  Set $ToDo=Restart
 End
.EE
These instructions are used to play a sound, move the pointer
to widget 1 and to initialize $ToDo to "Restart" at every startup.

.SH PERIODIC TASKS
This part of the script contains instructions that are executed every
second.  For example:
.EX
PeriodicTasks
 Begin
  If (RemainderOfDiv (GetTime) 10)==0 Then
   Do {Exec xcalc}
 End
.EE
This example shows how to launch xcalc every 10 seconds.

.SH THE QUIT FUNCTION
This part of the script contains instructions that are executed when
the script exits (after the Quit instruction or if you close the window with
the Close, Delete or Destroy fvwm command). For Example
.EX
QuitFunc
 Begin
  Do {Echo bye, bye}
 End
.EE
Be aware that if you used the KillModule fvwm command to close the script,
some instructions or functions which rely on the existence of a
communication link between the script and fvwm will not be executed
(for example the Do command). To smoothly kill a script with an fvwm command
see the
.B COMMANDS
section.

.SH MAIN OF A SCRIPT
The second part of the script contains the description for every widget
in the script.
Each widget description has two parts.
The first part describes initial properties,
the second part contains instructions that are executed
when the widget receives messages.
All widgets can send and receive messages.
All messages are identified by a number.
The message "UserAction" is sent to a widget when the user operates the widget.
The syntax for the first part is:
.EX
Widget          id      # A number between 1 and 999 inclusive
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 }
 Colorset       int
 Flags          flagsOpt
.EE
The flagsOpt option to Flags is a space separated list containing one or
more  of  the  keywords
.IR "Hidden" ,
.IR "NoReliefString" ,
.IR "NoFocus" ,
.IR Left " / " Center " / " Right "."
.I Hidden
is used to specify if the widget is hidden at startup.
.I NoReliefString
specifies if strings are drawn with relief or not.
.I NoFocus
specifies if the widget can get the keyboard focus or not.
By default all widgets take focus, except Rectangle, HDipstick and VDipstick
which cannot. Moreover, the NoFocus widgets are skipped when you
circulate around the widgets with the (Shift-)Tab short cut.
.IR Left " / " Center " / " Right
specifies the text position. These apply only to ItemDraw, List, Menu,
PopupMenu and PushButton. The default is
.I Center
for ItemDraw and PushButton and
.I Left
for the other widgets.

LocaleTitle can be used in place of Title, for using the locale catalog(s)
defined with UseGettext.

The position of every widget must be specified.

The syntax for the second part is:
.EX
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
   # list of instructions which will be
   # executed when widget receives
   # message 1
  End
 End
.EE

.SH LIST OF WIDGETS
There is fifteen types of widgets.

.IP "\fBCheckBox\fP: Display check box with a string."

\fBTitle\fP: title of the check box.

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

The \fBSize\fP property is ignored.

.IP "\fBHDipstick\fP: Display a horizontal dipstick."
This widget can be used to display disk usage.

\fBValue\fP: specify the current value of the dipstick.

\fBMinValue\fP: specify the minimum value of the dipstick.

\fBMaxValue\fP: specify the maximum value of the dipstick.

A minimum size of 30x11 is imposed.

.IP "\fBHScrollBar\fP: Display an horizontal scrollbar."

\fBValue\fP: position of the thumb.

\fBMaxValue\fP: upper limit of Value.

\fBMinValue\fP: lower limit of Value.

The height property is ignored and a minimum width is imposed.  The width
should be at least the range plus 37 if all values are to be selectable e.g.
a min of 0 and max of 10 has a range of 11 and therefore should have a
minimum width of 48.

.IP "\fBItemDraw\fP: Display an icon and/or a string."

\fBTitle\fP: string to display.

\fBIcon\fP: icon to display.

\fBMaxValue\fP: x coordinate of the cursor.

\fBMinValue\fP: y coordinate of the cursor.

The size is made large enough to contain the title and/or the icon.

.IP "\fBList\fP: Display a list."
List lets user to choose between various options.

\fBValue\fP: specify which option is selected.

\fBMinValue\fP: First visible option.

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

A minimum height of three items is imposed and the width is made to be at
least 108.

.IP "\fBMenu\fP: Display a menu whom lets user to choose a option."
Items of type Menu are layed out from left to right along the top
of the window. The size and position properties are ignored.

\fBValue\fP: specify which option is selected.

\fBTitle\fP: title contains options displayed in the menu. The syntax is the
following:
{Option 1|Option 2|...|Option N}.

.IP "\fBMiniScroll\fP: Display a very small vertical scrollbar."

\fBValue\fP: position of the thumb.

\fBMaxValue\fP: upper limit of Value.

\fBMinValue\fP: lower limit of Value.

The size is set to 19x34.

.IP "\fBPopupMenu\fP: Display a pop up menu."

\fBValue\fP: specify what option is selected.

\fBTitle\fP: the title has the following syntax:
{Option 1|Option 2|...|Option N}."Option 1|Option 2|...|Option N" is the
pop up menu which is displayed when pressing mouse button.

The size property is ignored.

.IP "\fBPushButton\fP: Display push button with an icon and/or a string."

\fBTitle\fP: 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
pop up menu which is displayed when pressing the right button.

\fBIcon\fP: icon to display.

The button is made large enough to fit the icon and or label.

.IP "\fBRadioButton\fP: Display radio button with a string."

\fBTitle\fP: title of the radio button.

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

The size property is ignored

.IP "\fBRectangle\fP: Display a rectangle."
 This type of widget can be used to decorate window.

.IP "\fBSwallowExec\fP"
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.

\fBTitle\fP: specify the window name which be captured and displayed in the
script window.

\fBSwallowExec\fP: specify the command line to execute to spawn the process.
Modules can also be swallowed.

\fBValue\fP: specify the looking of the border. Possible value: -1, 0, 1.

The size is made to be at least 30x30

.IP "\fBTextField\fP: Display a text input field."
The text input field can be used to edit a single-line string.

\fBTitle\fP: content of text field.

\fBValue\fP: position of the insert point.

\fBMinValue\fP: position of the end of the selection.

\fBMaxValue\fP: first visible character of the title

The height property is ignored, the width is made to be at least 40 pixels
wider than the initial contents.

.IP "\fBVDipstick\fP: Display a vertical dipstick."

\fBValue\fP: specify the current value of the dipstick.

\fBMinValue\fP: specify the minimum value of the dipstick.

\fBMaxValue\fP: specify the maximum value of the dipstick.

The size is made to be at least 11x30.

.IP "\fBVScrollBar\fP: Display a vertical scrollbar."

\fBValue\fP: position of the thumb.

\fBMaxValue\fP: upper limit of Value.

\fBMinValue\fP: lower limit of Value.

The width property is ignored and a minimum height is imposed.  The height
should be at least the range plus 37 if all values are to be selectable e.g.
a min of 0 and max of 10 has a range of 11 and therefore should have a
minimum height of 48.

.SH INSTRUCTIONS

Here is the description of all instructions.

.IP "HideWidget \fIid\fP : hide the widget numbered \fIid\fP."

.IP "ShowWidget \fIid\fP: show the widget numbered \fIid\fP."

.IP "ChangeValue \fIid1 id2\fP"
Set the value of the widget numbered \fIid1\fP to \fIid2\fP.

.IP "ChangeMaxValue \fIid1 id2\fP"
Set the maximum value of the widget numbered \fIid1\fP to \fIid2\fP.

.IP "ChangeMinValue \fIid1 id2\fP"
Set the minimum value of the widget numbered \fIid1\fP to \fIid2\fP.

.IP "ChangeTitle \fIid1 id2\fP"
Set the title of the widget numbered \fIid1\fP to \fIid2\fP.

.IP "ChangeWindowTitle \fIstring\fP"
Set the title of the window to \fIstring\fP.

.IP "ChangeWindowTitleFromArg \fInumarg\fP"
Set the title of the window to the value of the \fInumarg\fP-th script argument.

.IP "ChangeLocaleTitle \fIid1 id2\fP"
As ChangeTitle but use the locale catalog(s) defined with UseGettext.

.IP "ChangeIcon \fIid1 id2\fP"
Set the icon of the widget numbered \fIid1\fP to \fIid2\fP.

.IP "ChangeForeColor \fIid1\fP {\fIcolor\fP}"
Set the foreground color of the widget numbered \fIid1\fP to {\fIcolor\fP}.

.IP "ChangeBackColor \fIid1\fP {\fIcolor\fP}"
Set the background color of the widget numbered \fIid1\fP to {\fIcolor\fP}.

.IP "ChangeColorSet \fIid1\fP \fIid2\fP"
Set the colorset of the widget numbered \fIid1\fP to \fIid2\fP. Specifying
widget 0 sets the main window colorset.

.IP "ChangePosition \fIid1 x y\fP"
Move the widget numbered \fIid1\fP to position (\fIx\fP,\fIy\fP).

.IP "ChangeSize \fIid1 width height\fP"
Set the size of the widget numbered \fIid1\fP to (\fIwidth\fP,\fIheight\fP).

.IP "ChangeFont \fIid1 newfont\fP"
Set the font of the widget numbered \fIid1\fP to \fInewfont\fP.

.IP "WarpPointer \fIid\fP"
Warp the mouse pointer into the widget numbered \fIid\fP.

.IP "WriteToFile \fIfilename\fP {\fIstr1\fP} {\fIstr2\fP} etc"
Write to the file \fIfilename\fP the string which is the concatenation of all
arguments \fIstr1\fP, \fIstr2\fP, etc.

.IP "Do {\fIcommand args\fP}"
Execute the fvwm command inside the Do block.
Any fvwm command as described in the fvwm2
man page can be used.
Commands are sent from this module to the fvwm
main program for processing.
The length of the command and arguments can not exceed 988 characters.

.IP "Set $\fIvar\fP={\fIstr\fP1} {\fIstr2\fP} etc"
Concatenate all arguments to a string and set the variable $\fIvar\fP to this
string.

.IP "Quit: quit the program."

.IP "SendSignal \fIid1 id2\fP"
Send a message numbered \fIid2\fP to widget \fIid1\fP.

.IP "SendToScript \fIid_script\fP {\fIstr1\fP1} {\fIstr2\fP} etc"
Send a message to the script identified by id_script. The message is the
concatenation of str1, str2...

.TP
.RI "Key " Keyname " " Modifier " " id " " sig " " str1 " " str2 " etc"
Binds a keyboard key to the instruction

.RI "SendSignal " id " " sig

and sets the "last string" to the concatenation of str1, str2...
(see the LastString function).
The
.I Keyname
and
.I Modifiers
fields are defined as in the fvwm Key command.

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

.SH FUNCTIONS
All functions use arguments. Functions can return both a string and
a number.  The syntax is:
.EX
(function argument1 argument2 etc)
.EE
Here is the complete list of arguments:

.IP "(GetTitle \fIid\fP)"
Return the title of the widget numbered \fIid\fP.

.IP "(GetValue \fIid\fP)"
Return the current value of the widget numbered \fIid\fP.

.IP "(GetMinValue \fIid\fP)"
Return the current Min value of the widget numbered \fIid\fP.

.IP "(GetMaxValue \fIid\fP)"
Return the current Max value of the widget numbered \fIid\fP.

.IP "(GetFore \fIid\fP)"
Return the current RGB foreground value of the widget numbered \fIid\fP in the
hex format RRGGBB.

.IP "(GetBack \fIid\fP)"
Return the current RGB background value of the widget numbered \fIid\fP in the
hex format RRGGBB.

.IP "(GetHilight \fIid\fP)"
Return the current RGB hilight value of the widget numbered \fIid\fP in the
hex format RRGGBB.

.IP "(GetShadow \fIid\fP)"
Return the current RGB shadow value of the widget numbered \fIid\fP in the
hex format RRGGBB.

.IP "(GetOutput {\fIstr\fP} \fIint1 int2\fP)"
Executes the command \fIstr\fP, gets the standard output and returns the word
which is in the line \fIint1\fP and in the position \fIint2\fP. If \fIint2\fP
is equal to -1, GetOutput returns the complete line.

.IP "(NumToHex \fIint\fP)"
Return the hexadecimal value of \fIint\fP.

.IP "(HexToNum {\fIstr\fP})"
Return the decimal value of \fIstr\fP, \fIstr\fP must be an hexadecimal value.

.IP "(Add \fIint1 int2\fP)"
Return the result of (\fIint1\fP+\fIint2\fP).

.IP "(Mult \fIint1 int2\fP)"
Return the result of (\fIint1\fP*\fIint2\fP).

.IP "(Div \fIint1 int2\fP)"
Return the result of (\fIint1\fP/\fIint2\fP).

.IP "(StrCopy {\fIstr\fP} \fIint1 int2\fP)"
Return the string whom is between position int1 and int2. For example,
(StrCopy {Hello} 1 2) returns {He}

.IP "(LaunchScript {\fIstr\fP})"
This function launches the script named str and returns
an identification number.
This number is necessary to use the functions SendToScript and
ReceiveFromScript. The string str contains the script name and some arguments.

.IP "(GetScriptArgument {\fIint\fP})"
This function returns the argument script used in the function LaunchScript.
If int is equal to zero, GetScriptArgument returns the name of the script.

.IP "(GetScriptFather)"
This function returns the identification number of the script father.

.IP "(ReceivFromScript {\fIint\fP})"
This function returns the message sent by the script numbered int.

.IP "(RemainderOfDiv {\fIint1 int2\fP}): t"
This function returns the remainder of the division (\fIint1\fP/\fIint2\fP).

.IP "(GetTime)"
This function returns the time in seconds.

.TP
.RI "(GetPid)"
This function returns the process id of the script.

.TP
.RI "(Gettext {\fIstr\fP})"
This function return the translation of
.I str
by using the locale catalog(s) defined with UseGettext.

.TP
.RI "(SendMsgAndGet {" comId "} {" cmd "} " bool ")"
Sends the command
.I cmd
with identifier
.I comId
to an external
program ready to communicate with the script using a protocol
specific to FvwmScript. If
.I bool
is 0 FvwmScript does not wait for an
answer from the external program. In this case the returned value is 1 if
the message can be sent to the external program and 0 if this is not the case.
If
.I bool
is 1, then FvwmScript waits for an answer from the external program
and the return value is this answer (a line of no more
than 32000 characters). If the communication fails, the returned value is 0.
See the section
.B A COMMUNICATION PROTOCOL
for a description of the communication protocol used.

.TP
.RI "(Parse {" str "} " int ")"
where
.I str
must be a string of the form:
.EX
        X1S1X2S2X3S3...SnXn
.EE
where the Xn are numbers containing four decimal digits and where
Sn are strings of length exactly Xn. The returned value is the
string
.RI "S" int "."
If
.I int
is out of range (e.g., >n) the returned value is the empty string. If
.I str
is not of the specified form, the return value is unpredictable
(but empty in the average). This function is useful to handle
strings returned by the SendMsgAndGet function.

.TP
.RI "(LastString)"
This function returns the "current working string" for the Key instruction
and the SendString command
(see the
.B COMMANDS
section). At startup this string is empty, but when a Key binding is
detected (respectively, a SendString command is received), then this string
is set to the string associated to the instruction (respectively,
to the command).

.SH CONDITIONAL LOOPS
There are three kinds of conditional loops. The instruction "If-Then-Else"
has the following syntax:
.EX
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
.EE
The second part "Else-Begin-End" is optional. If the loop contains only one
instruction, Begin and End can be omitted. The instruction "While-Do" has the
following syntax:
.EX
While $i<5 Do
Begin
 Set $i=(Add i 1)                       # List of instructions
End
.EE
Two strings can be compared with "==" and two numbers can be compared with "<",
"<=", "==", ">=", ">". The loop "For-Do-Begin-End" has the following syntax:
.EX
For $i=1 To 20 Do
Begin
 Do {Exec xcalc &}                      # List of instructions
End
.EE

.SH COMMANDS
The following fvwm command may be executed at any time

.RI "SendToModule " ScriptName " SendString " id " " sig " " str

it sends to any module with alias or name which matches
.I  ScriptName
the string

.RI "SendString " id " " sig " " str

When an FvwmScript receives such a message it sends to the Widget
.I id
the signal numbered
.I sig
and the string
.I str
can be obtained with the LastString function. Let us give an example.
Say that you have a script MyScript with the widget:
.EX
Widget 50
Property
 Type PushButton
 Title {Quit}
 ...
Main
Case message of

  SingleClic:
  Begin
    Quit
  End

  1 :
  Begin
    Set $str = (LastString)
    If $str == {Quit} Then
      Quit
    Else
      ChangeTitle 33 $str
  End

End
.EE
Then the command
.EX
SendToModule MyScript SendString 50 1 str
.EE
forces MyScript to exit if str is equal to "Quit" and if not it changes
the title of Widget 33 to str.


This command can be used to change the window title

.RI "SendToModule " ScriptName " ChangeWindowTitle  " newTitle " " [oldTitle]

it causes that any module with alias or name which matches
.I  ScriptName
changes its associated window title to \fInewTitle\fP. The optional argument
\fIoldTitle\fP makes sense when there are several instances of
the same script. It permits to avoid changing the name  of all these instances
by specifying the name of the window associated to the target script (see the
example below).

.EX
+ I Module FvwmScript FvwmStorageSend "/dev/hda6"
+ I Wait FvwmStorageSend
+ I SendToModule FvwmStorageSend ChangeWindowTitle HDA6
+ I Module FvwmScript FvwmStorageSend "/dev/hda1"
+ I Wait FvwmStorageSend
+ I SendToModule FvwmStorageSend ChangeWindowTitle HDA1 FvwmStorageSend
.EE

Without the FvwmStorageSend argument in the last case, the SendToModule command would
have changed to HDA1 the name of both instances of FvwmStorageSend.


.SH EXAMPLES
You will find examples of scripts in the fvwm configuration directory.

FvwmScript-BellSetup, FvwmScript-KeyboardSetup, FvwmScript-PointerSetup and
FvwmScript-ScreenSetup are a set of scripts that modify X settings.
These scripts save preferences into a file named ~/.xinit-fvwmrc (If you want
to use another file name, give it as the first argument of the script).
If you want to load these preferences at every startup, you have to include
the line  ".xinit-fvwmrc" in your .xinitrc (or .xsession) file before
starting fvwm.

FvwmScript-BaseConfig modifies fvwm
focus and paging mouse policy, window placement, opacity and
other features of the move and resize commands, snap attraction and
shading animation.
This script saves preferences into a file named .FvwmBaseConfig in the
user's data directory (i.e., $HOME/.fvwm or $FVWM_USERDIR if set).
If you want to load these preferences at every startup you must add
the line "Read .FvwmBaseConfig" in your fvwm configuration file.
If you want to use another file name, give it as the first
argument of the script.
When you click on Ok or Apply an fvwm function that you may define
named BaseConfigOkFunc or BaseConfigApplyFunc is called.
This allows for reloading specific application styles
that the script has destroyed
(e.g., AddToFunc  BaseConfigOkFunc I Read MyAppStyle).

FvwmScript-Buttons is a buttons panel which can replace FvwmButtons (this
script supports popup menus and requires xload, xclock, FvwmPager, TkDesk).
FvwmScript-Colorset allows you to edit your colorset (see FvwmTheme).
FvwmScript-Date allows you to set date and time.
FvwmScript-FileBrowser is a file browser used by the other scripts.
FvwmScript-Find is an elementary front-end to find.
FvwmScript-Quit allows to quit fvwm, restart fvwm or some other window
manager, or shut down and reboot the computer.
FvwmScript-ScreenDump is a screen dumper. FvwmScript-WidgetDemo is a pure
example script. See the next section for FvwmScript-ComExample.

.SH A COMMUNICATION PROTOCOL
FvwmScript is a weak (but simple) programming language. If you need to
deal with a lot of data and/or you need to use complex algorithms you
should use an external program (in perl for example) and "send" the desired
information
to your FvwmScript script. The first approach is to use the GetOutput function.
This is simple but you should rerun your external program each time
you need information from it (and this may cause performances problems).
The second approach is to use the SendMsgAndGet function which
extends FvwmScript by using any programming language which can deal with
named pipes (fifos). We describe this solution in this section.
(A third approach is to use fvwm-themes-com from the fvwm-themes
package, but in fact the SendMsgAndGet method is an implementation
of fvwm-themes-com inside FvwmScript and this gives better performance).

Basically, you start an "external" program (the program for short) from your
FvwmScript script (the script for short). This
program runs in the background and you use the SendMsgAndGet function
in your script to ask questions or to give instructions to the program.
The program must strictly respect a certain communication protocol.
First of all there is an identifier
.I comId
for the communication, it should contain the process id of the script
for a good implementation of the protocol (use the GetPid function and
pass the
.I comId
via an option to the program). The protocol uses two fifos, in the fvwm user
directory, named:
.RI ".tmp-com-in-" comId " and .tmp-com-out-" comId "."
The program should create and listen on the
.RI ".tmp-com-in-" comId
fifo. Then, when FvwmScript executes a function of the form:

.RI "       Set $answer = (SendMsgAndGet {" comId "} {" cmd "} " bool ")"

FvwmScript writes the
.I cmd
on this fifo.
This way the program can read the
.IR cmd
and can execute the appropriate action (it should remove the in fifo
to support multi-communications). If
.I bool
is 0, FvwmScript does not wait for an answer from the program and
return 1 if the previous actions succeed and 0 if they failed
(then the program should "go back" to the in fifo).
If
.I bool
is 1, then FvwmScript waits (20 sec) for an answer from the program and
in turn returns the answer to the script (note that
.I bool
is not passed to the program as it must know which commands need
an answer). To answer, the program creates the
.RI ".tmp-com-out-" comId
fifo and writes the answer on it. The program should wait until
FvwmScript reads the answer and then it should remove the out fifo
and go back to the in fifo. The answer should consist of
one line of no more than 32000 characters (take a look at the Parse
function to handle multiple lines as one line).

A simple way to understand this protocol and to write scripts and
programs that use it is to take a look at
the (not useful) example FvwmScript-ComExample and
fvwm-script-ComExample.pl (that can found in the fvwm data
directory). Moreover, this implementation of the protocol solves
questions as: What to do if the script exits for a bad reason?
What to do if the program exits for a bad reason? ...etc.

.SH BUGS
FvwmScript crashes if widgets are accessed that have not been defined.

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

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