Fvwm3Script

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 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.

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.

CONFIGURATION OPTIONS

The following commands can be used in the config file (see fvwm(1), section MODULE COMMANDS for details). They are used only if the corresponding script commands are not used in the script. *FvwmScript: DefaultFont font *FvwmScript: DefaultFore color *FvwmScript: DefaultBack color *FvwmScript: DefaultHilight color *FvwmScript: DefaultShadow color *FvwmScript: DefaultColorset colorset *FvwmScript: DefaultCursor cursor

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.

HEADING OF A SCRIPT

The syntax is as follows: WindowTitle string WindowSize width height WindowPosition x y ForeColor {color} BackColor {color} HilightColor {color} ShadowColor {color} Colorset {n} Font {font} UseGettext [locale_path] WindowLocaleTitle string

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: 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 fvwm command). For Example 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 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: The flagsOpt option to Flags is a space separated list containing one or more of the keywords Hidden, NoReliefString, NoFocus, Left / Center / Right. Hidden is used to specify if the widget is hidden at startup. NoReliefString 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 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:

LIST OF WIDGETS

There is fifteen types of widgets. CheckBox: Display check box with a string. The Size property is ignored. HDipstick: Display a horizontal dipstick. A minimum size of 30x11 is imposed. HScrollBar: Display an horizontal scrollbar. ItemDraw: Display an icon and/or a string. List: Display a list. Menu: Display a menu whom lets user to choose a option. MiniScroll: Display a very small vertical scrollbar. PopupMenu: Display a pop up menu. PushButton: Display push button with an icon and/or a string. RadioButton: Display radio button with a string. Rectangle: Display a rectangle. SwallowExec TextField: Display a text input field. VDipstick: Display a vertical dipstick. VScrollBar: Display a vertical scrollbar.

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 ChangeMaxValue id1 id2 ChangeMinValue id1 id2 ChangeTitle id1 id2 ChangeWindowTitle string ChangeWindowTitleFromArg numarg ChangeLocaleTitle id1 id2 ChangeIcon id1 id2 ChangeForeColor id1 {color} ChangeBackColor id1 {color} ChangeColorSet id1 id2 ChangePosition id1 x y ChangeSize id1 width height ChangeFont id1 newfont WarpPointer id WriteToFile filename {str1} {str2} etc Do {command args} Set $var={str1} {str2} etc Quit: quit the program., SendSignal id1 id2 SendToScript id_script {str11} {str2} etc Key Keyname Modifier id sig str1 str2 etc

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) (GetValue id) (GetMinValue id) (GetMaxValue id) (GetFore id) (GetBack id) (GetHilight id) (GetShadow id) (GetOutput {str} int1 int2) (NumToHex int) (HexToNum {str}) (Add int1 int2) (Mult int1 int2) (Div int1 int2) (StrCopy {str} int1 int2) (LaunchScript {str}) (GetScriptArgument {int}) (GetScriptFather) (ReceivFromScript {int}) (RemainderOfDiv {int1 int2}): t (GetTime) (GetPid) (Gettext { str}) (SendMsgAndGet { comId} {cmd} bool) (Parse { str} int) (LastString)

CONDITIONAL LOOPS

There are three kinds of conditional loops. The instruction "If-Then-Else" has the following syntax: 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: Two strings can be compared with "==" and two numbers can be compared with "<", "⇐", "==", ">=", ">". The loop "For-Do-Begin-End" has the following syntax:

COMMANDS

The following fvwm command may be executed at any time it sends to any module with alias or name which matches ScriptName the string When an FvwmScript receives 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: Then the command 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 it causes that any module with alias or name which matches ScriptName changes its associated window title to newTitle. The optional argument oldTitle makes sense when there are several instances of the same script. It permits one 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). Without the FvwmStorageSend argument in the last case, the SendToModule command would have changed to HDA1 the name of both instances of FvwmStorageSend.

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. 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 one 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.

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 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 protocol 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: FvwmScript writes the cmd on this fifo. This way the program can read the cmd and can execute the appropriate action (it should remove the in fifo to support multi-communications). 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 ( <[email protected]> or ). <[email protected]>

CONTRIBUTOR

Eddy J. Gurney (). <[email protected]>