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 to build many graphical applications such as desktop accessories, button panel with pop up menu, modal dialog... At the startup, FvwmScript 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. 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 `*FvwmScriptPath 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 initialization, or can be bound to a menu or mouse button or keystroke to invoke it later.

CONFIGURATION OPTIONS
The following commands can be placed in the .fvwm2rc file. They are used only if the corresponding script commands are not used in the script.

*FvwmScriptDefaultFont font
    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.

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

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

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

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

*FvwmScriptDefaultColorset 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 four 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. 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
    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 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 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.

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. The first part describes initial properties and the second part contains instructions which will be executed when the widget receives messages. All widgets can send and receive messages. 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	# A number between 1 and 99 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		Hidden and/or NoReliefString
The option 'Flags` is used to specify if the widget is hidden or not and if strings are drawn with relief or not. The position of every widget must be specified.
    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 dipstick. MaxValue: specify the maximum value of the dipstick. 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 therefore should have a minimum width of 48.

ItemDraw: Display an icon and/or a string.
    Title: string to display. Icon: icon to display. 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 displayed 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 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 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 dipstick. MaxValue: specify the maximum value of the dipstick. 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...

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.

(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 widget numbered id in the hex format RRGGBB.

(GetBack id)
    Return the current RGB background value of the widget 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 launch the script named str and return an identification number. This number is necessary to use these functions SendToScript and ReceiveFromScript. 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}): t
    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
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" 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

EXAMPLES
You will find examples of scripts in the fvwm configuration directory. ScriptFvwmBellSetup, ScriptFvwmKeyboardSetup, ScriptFvwmPointerSetup and ScriptFvwmScreenSetup 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. ScriptFvwmBaseConfig 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). ScriptFvwmButtons is a buttons panel which can replace FvwmButtons (this script supports popup menus and requires xload, xclock, FvwmPager, TkDesk). ScriptFvwmColorset allows you to edit your colorset (see FvwmTheme). ScriptFvwmDate allows you to set date and time. ScriptFvwmFileBrowser is a file browser used by the other scripts. ScriptFvwmFind is an elementary front-end to find. ScriptFvwmQuit allows to quit fvwm, restart fvwm or some other window manager, or shut down and reboot the computer. ScriptFvwmScreenDump is a screen dumper. ScriptFvwmWidgetDemo is a pure example script.

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

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