Index of Section 1 Manual Pages
| Interix / SUA | FvwmScript.1 | Interix / SUA |
FvwmScript(1) FvwmScript(1)
NAME
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 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 com-
mand 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.
INVOCATION
FvwmScript can be invoked by inserting the line `Module
FvwmScript name_of_script' in the .fvwmrc 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 .fvwmrc
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
fvwm2 man page.
The command to start FvwmScript can be placed on a line by
itself, if FvwmScript is to be spawned during fvwm's ini-
tialization, or can be bound to a menu or mouse button or
keystroke to invoke it later.
CONFIGURATION OPTIONS
The following commands can be used in the config file (see
fvwm2(1), section MODULE COMMANDS for details). They are
used only if the corresponding script commands are not
used in the script.
*FvwmScript: DefaultFont font
Specifies the default font to be used. If not spec-
ified with this command or in the script with the
Font command, fixed font is assumed.
*FvwmScript: DefaultFore color
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.
*FvwmScript: DefaultBack color
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.
*FvwmScript: DefaultHilight color
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.
*FvwmScript: DefaultShadow color
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.
*FvwmScript: DefaultColorset colorset
Tells the module to use colorset colorset as the
default colorset. Refer to the FvwmTheme man page
for details about colorsets.
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, rectan-
gles, pop up menus, swallowexecs and mini scrollbars.
HEADING OF A SCRIPT
The syntax is as follows:
WindowTitle string
This option sets the window title.
WindowSize width height
This option sets window size. width and height are
numerical value.
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.
Colorset {n}
This option sets the default colorset for all wid-
gets.
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 instructions that are
executed every second. For example:
Periodic Task
Begin
If (RemainderOfDiv (GetTime) 10)==0 Then
Do {Exec xcalc}
End
This example shows how to launch xcalc every 10 seconds.
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 fvwm2 command). For Example
QuitFunc
Begin
Do {Echo bye, bye}
End
Be aware that if you used the KillModule fvwm2 command to
close the script, some instructions or functions which
rely on the existence of a communication link between the
script and fvwm2 will not be executed (for example the Do
command). To smoothly kill a script with an fvwm2 command
see the COMMANDS section.
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:
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
The flagsOpt option to Flags is a space separated list
containing one or more of the keywords Hidden, NoRe-
liefString, NoFocus, Left / Center / Right. Hidden is
used to specify if the widget is hidden at startup. NoRe-
liefString specifies if strings are drawn with relief or
not. 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. Left / Center
/ Right specifies the text position. These apply only to
ItemDraw, List, Menu, PopupMenu and PushButton. The
default is Center for ItemDraw and PushButton and Left for
the others widgets.
The position of every widget must be specified.
The syntax for the second part is:
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
LIST OF WIDGETS
There is fifteen types of widgets.
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.
The Size property is ignored.
HDipstick: Display a horizontal dipstick.
This widget can 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.
A minimum size of 30x11 is imposed.
HScrollBar: Display an horizontal scrollbar.
Value: position of the thumb.
MaxValue: upper limit of Value.
MinValue: 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 there-
fore should have a minimum width of 48.
ItemDraw: Display an icon and/or a string.
Title: string to display.
Icon: icon to display.
MaxValue: x coordinate of the cursor.
MinValue: y coordinate of the cursor.
The size is made large enough to contain the title
and/or the icon.
List: Display a list.
List lets user to choose between various options.
Value: specify which option is selected.
MinValue: First visible option.
Title: 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.
Menu: 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.
Value: specify which option is selected.
Title: title contains options displayed in the
menu. The syntax is the following: {Option 1|Option
2|...|Option N}.
MiniScroll: Display a very small vertical scrollbar.
Value: position of the thumb.
MaxValue: upper limit of Value.
MinValue: lower limit of Value.
The size is set to 19x34.
PopupMenu: Display a pop up 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 pop up menu which is dis-
played when pressing mouse button.
The size property is ignored.
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 pop up
menu which is displayed when pressing the right
button.
Icon: icon to display.
The button is made large enough to fit the icon and
or label.
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.
The size property is ignored
Rectangle: Display a rectangle.
This type of widget can be used to decorate win-
dow.
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 can also be swallowed.
Value: specify the looking of the border. Possible
value: -1, 0, 1.
The size is made to be at least 30x30
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.
MinValue: position of the end of the selection.
MaxValue: 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.
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.
The size is made to be at least 11x30.
VScrollBar: Display a vertical scrollbar.
Value: position of the thumb.
MaxValue: upper limit of Value.
MinValue: 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.
INSTRUCTIONS
Here is the description of all instructions.
HideWidget id : hide the widget numbered id.
ShowWidget id: show the widget numbered id.
ChangeValue id1 id2
Set the value of the widget numbered id1 to id2.
ChangeMaxValue id1 id2
Set the maximum value of the widget numbered id1 to
id2.
ChangeMinValue id1 id2
Set the minimum value of the widget numbered 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 widget numbered id1
to {color}.
ChangeBackColor id1 {color}
Set the background color of the widget numbered id1
to {color}.
ChangeColorSet id1 id2
Set the colorset of the widget numbered id1 to id2.
Specifying widget 0 sets the main window colorset.
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 filename the string which is the
concatenation of all arguments str1, str2, etc.
Do {str1} {str2} etc
Execute the command which is the concatenation of
all arguments str1, str2, etc.
Set $var={str1} {str2} etc
Concatenate all arguments to a 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...
Key Keyname Modifier id sig str1 str2 etc
Binds a keyboard key to the instruction
SendSignal id sig
and sets the "last string" to the concatenation of
str1, str2... (see the LastString function). The
Keyname and Modifiers fields are defined as in the
fvwm2 Key command.
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.
FUNCTIONS
All functions use arguments. Functions can return both a
string and a 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.
(GetMinValue id)
Return the current Min value of the widget numbered
id.
(GetMaxValue id)
Return the current Max value of the widget numbered
id.
(GetFore id)
Return the current RGB foreground value of the wid-
get numbered id in the hex format RRGGBB.
(GetBack id)
Return the current RGB background value of the wid-
get numbered id in the hex format RRGGBB.
(GetHilight id)
Return the current RGB hilight value of the widget
numbered id in the hex format RRGGBB.
(GetShadow id)
Return the current RGB shadow value of the widget
numbered id in the hex format RRGGBB.
(GetOutput {str} int1 int2)
Executes the command str, gets the standard 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.
(Add int1 int2)
Return the result of (int1+int2).
(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 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.
(GetScriptArgument {int})
This function returns the argument script used in
the function LaunchScript. If int is equal to
zero, GetScriptArgument returns the name of the
script.
(GetScriptFather)
This function returns the identification number of
the script father.
(ReceivFromScript {int})
This function returns the message sent by the
script numbered int.
(RemainderOfDiv {int1 int2}): t
This function returns the remainder of the division
(int1/int2).
(GetTime)
This function returns the time in seconds.
(GetPid)
This function returns the process id of the script.
(SendMsgAndGet {comId} {cmd} bool)
Sends the command cmd with identifier comId to an
external program ready to communicate with the
script using a protocol specific to FvwmScript. If
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 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 charac-
ters). If the communication fails, the returned
value is 0. See the section A COMMUNICATION PROTO-
COL for a description of the communication protocol
used.
(Parse {str} int)
where str must be a string of the form:
X1S1X2S2X3S3...SnXn
where the Xn are numbers containing four decimal
digits and where Sn are strings of length exactly
Xn. The returned value is the string Sint. If int
is out of range (e.g., >n) the returned value is
the empty string. If 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.
(LastString)
This function returns the "current working string"
for the Key instruction and the SendString command
(see the 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).
CONDITIONAL LOOPS
There are three kinds of conditional loops. The instruc-
tion "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
The second part "Else-Begin-End" is optional. If the loop
contains only one instruction, Begin and End can be omit-
ted. The instruction "While-Do" has 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
COMMANDS
The following FVWM command may be executed at any time
SendToModule ScriptName SendString id sig str
it sends to any module with alias or name which matches
ScriptName the string
SendString id sig str
When an FvwmScript recieves such a message it sends to the
Widget id the signal numbered sig and the string str can
be obtained with the LastString function. Let us give an
example. Say that you have a script MyScript with the
widget:
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
Then the command
SendToModule MyScript SendString 50 1 str
forces MyScript to exit if str is equal to "Quit" and if
not it changes the title of Widget 33 to str.
EXAMPLES
You will find examples of scripts in the fvwm configura-
tion directory.
FvwmScript-BellSetup, FvwmScript-KeyboardSetup, Fvwm-
Script-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 start-
ing 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 reload-
ing specific application styles that the script has
destroyed (e.g., AddToFunc BaseConfigOkFunc I Read MyApp-
Style).
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). Fvwm-
Script-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. Fvwm-
Script-Quit allows to quit fvwm, restart fvwm or some
other window manager, or shut down and reboot the com-
puter. FvwmScript-ScreenDump is a screen dumper. Fvwm-
Script-WidgetDemo is a pure example script. See the next
section for FvwmScript-ComExample.
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 solu-
tion 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 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 comId via an option to the program). The pro-
tocol uses two fifos, in the FVWM user directory, named:
.tmp-com-in-comId and .tmp-com-out-comId. The program
should create and listen on the .tmp-com-in-comId fifo.
Then, when FvwmScript executes a function of the form:
Set $answer = (SendMsgAndGet {comId} {cmd} bool)
FvwmScript writes the cmd on this fifo. This way the pro-
gram can read the cmd and can execute the appropriate
action (it should remove the in fifo to support multi-com-
munications). If 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 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
bool is not passed to the program as it must know which
commands need an answer). To answer, the program creates
the .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.
BUGS
FvwmScript crashes if widgets are accessed that have not
been defined.
AUTHOR
Frederic Cordier (cordie97@cui.unige.ch or f-
cord96@univ-lyon1.fr).
CONTRIBUTOR
Eddy J. Gurney (eddy@gizmo.aa.ans.net).
3 July 2001 FvwmScript(1)