|
Simple Settings Dialog (ssd)
Table of Contents
NameSimple Settings Dialog Synopsisssd [OPTIONS] [FILE] DescriptionSimple Settings Dialog (ssd) enables a script author to easily construct a simple dialog (for e.g. configuration purposes) which can be be presented to the user during script execution. It is build on TrollTech QT4 (a cross platform gui toolkit - www.trolltech.com) and implements the most common used widgets from QT. On exit, ssd outputs the values of the widgets to stdout. This is on the form BUTTON='ok' TEXT='This is the text entered in a line edit widget...' which can easily be interpreted by e.g. bash. It knows two options: -v, --version -h, --help Their names pretty much give away what they do :-) If a file is given on the command line, the setup of widgets is read from the file, and interaction with widgets can be done through stdin. If no file is given on the command line, the setup of widgets is read from stdin. (End input from stdin with CTRL-D.) File syntaxThe basic syntax of the input to ssd is Begin: <widget> <options> ... End Begin: <widget> ... Options is on the format: <option> = <value> Empty lines and lines beginning with the character '#' are treated as comments. White space in the beginning of a line or around ':' and '=' are ignored. Furthermore ':' and '=' are interchangeable and the case is insensitive. The following lines are in that sense all identical: Text: This is some text... Text: This is some text... Text = This is some text... Text =This is some text... tExT : This is some text... InteractionIf ssd was started with a file on the command line (reading the widget setup from that file), interaction with widgets can be done through stdin. The basic format is like the file syntax: <id> = <text> If the specified id can be found, text is passed to that widget. Most widgets parses the passed text as a string to use, except the progress bar, which parses the text as an integer between 0 and 100 to set the displayed progress. Special keywords are quit or exit, which will cause ssd to exit. The Button-specification in the output will be set to EXTERNAL. WidgetsThe window in ssd is build up of widgets. Widgets are buttons, check boxes, labels and so on. They are started with a begin statement and ended with an end statement. Example:
Begin: LineEdit
Position: 1x1
Id: usercmd
Text: lp print.ps
End
There are two types of widgets: Normal widgets and parents. Parent widgets can hold other widgets. Example:
Begin: Tabs
Position = 1x1
Begin: Page
Text = Page 1
Begin: Label
Text = This is a text label
Position = 1x1
End
End
End
The (normal) widgets are placed on a parent and placed in a grid layout maintained by QT. The list of normal widgets is: Button, CheckBox, Combo, DropDown, Label, LineEdit, Toggle, Radio, Progress. The list of parent widgets is: The Main Window, Box, Page, Tabs. Note that The Main Window is a pseudo widget representing the dialog window. It is implicitly begun at beginning of file (BOF) and implicitly ended at end of file (EOF). To each widget, a number of options are associated, which gives meaning for that particular widget. Below is a description of each widget, along with a list of supported options. See the section "options" for descriptions of what each options does. Normal widgetsButtonThis is a regular push button. When clicked, ssd exits and prints out the values of the widgets. Note that ssd may also be closed on external requests - e.g. from the window manager when the user clicks close button in the window decoration. See the output section for further details. Available options: Position, Cancel, Default, Id, Image, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Text on button. CheckBoxA standard check box. It can be stand alone or grouped with other state-containing widgets (Toggle and Radio). Available options: Position, Group, Id, Image, State, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Label text. ComboThis is a combination of a LineEdit and a DropDown box. Items can be inserted with the AddItem option, but the user is also allowed to enter text not available from the drop down list. An entry can be set to a default (pre selected) item, or another string may be specified by the text option. The id tag of the AddItem options is ignored. Available options: Position, AddItem, Id, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Integer between 0 and count-1 - denoting the item to select from drop down menu. DropDownPresents the user with a drop down list, allowing the user to select one (and only one) entry from the list. Available options: Position, AddItem, Id, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Integer between 0 and count-1 - denoting the item to select from drop down menu. LabelThis is a simple label for presenting some text or an image. There is no user interaction with this widget, and thus no output is written for this widget when ssd exits. The text and image options are mutually exclusive. That is, only a string or an image may be placed in a label. Available options: Position, Image, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Text on label. LineEditPresents a field for editing a single line of text. An initial text may be specified with the text option. Note that line breaks in the text option are ignored. Furthermore, an echo mode may be specified to e.g. hide a password. Available options: Position, Id, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize, EchoMode. Input parsed as: Text in edit field. TogglePresents a toggle button. It looks like the Button widget, but does not cause ssd to exit. Instead the button toggles up and down. It can be stand alone or grouped with other state-containing widgets (CheckBox and Radio), using the Group option. Available options: Position, Group, Id, Image, State, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Text on button. RadioThis is the classic radio button most often used to present the user with the option of selecting one out of several choices. It can be stand alone or grouped with other state-containing widgets (CheckBox and Toggle), using the Group option. Available options: Position, Group, Id, Image, State, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Text on label. ProgressPresents a progress bar. There is no user interaction with this widget. It is only used to display the progress of some process. Available options: Position, Id, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Integer between 0 and 100, specifying the progress to display. Parental widgetsThe Main windowThis is a pseudo widget representing the dialog window of ssd. It is implicitly begun at beginning of file (BOF) and implicitly ended at end of file (EOF). It cannot be begun or ended with a begin or end statement. The text option set the title of the window. The style option sets the main style of the window. The default styles available with QT are cde, windows, motif, plastique, cleanlooks, macintosh (OS dependent) and windowsxp (OS dependent). The options for The Main Window are specified in the options section of The Main Window. Since it is begun at BOF and ended at EOF, the option section of The Main Window is simply outside any begin-end statements. Example:
Style = plastique
Text = The title of the window :-)
Begin: Button
Position = 1x1
Text = Press me...
End
Available options: Style, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize, Center. Input parsed as: Title text. BoxThis is a box, (graphically) grouping other widgets. It has no functionality in the sense of grouping CheckBoxes, Radios or Toggles. Their grouping is specified with the group option. The box may be equipped with a check box, enabling and disabling the widgets placed in the box accordingly to the state of the check box. The check box is enabled by specifying the State option. The check box of the box can (unfortunately) not be grouped with the other state-containing widgets (CheckBox, Radio and Toggle). This is due to a limitation in QT. A work around could maybe be implemented in the future (if there is a feature request for it), but this has not been considered important for now. There will only be output (telling if the check box is checked or not) if the check box has been enabled with the state option. Available options: Position, Id, State, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Text on label. PageThis is a special (parental) widget, in that it can only be placed on a tab widget. It has the sole purpose of adding a tab (page) to the tab bar setup. See the example under the Tabs widget. Available options: Image, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Text on page tab. TabsThis is a special widget, in that it is a parental widget that only allows Page widgets to be placed on it. Together, the Tabs and Page widgets produce a tab bar setup, where one page (containing other widgets) is visible at a time. This widgets does not produce any output. Example for both tab and page:
Begin: Tabs
Position: 1x1
Begin: Page
Text: Page 1
# Place other widgets here...
End
Begin: Page
Text: Page 2
# Place other widgets here...
End
End
Available options: Position, BackgroundColor, ForegroundColor, MaxSize, MinSize. Input parsed as: Ignored. OptionsThis section describes the options available to the widgets. In order to see which options applies to which widgets, see the description of the widgets (previous section) or consult the table in the next section. Most options take an argument and its syntax is <option> = <value> The most important option is the position option, which applies to almost all widgets. For further info, see below. The available options are: AddItem, Cancel, Default, Group, Id, Image, Position, State, Style, Text, BackgroundColor, ForegroundColor, MaxSize, MinSize. DescriptionsAddItemItem is a synonym for AddItem. This option inserts entries into drop downs and combos. It is a bit special in that it has optional fields. The syntax is AddItem<*><: id>: Entry text The '<>' denoting the optional fields and the '*' is literally the star. The '*' denotes the default item. If several default items is specified, the last specified item is selected. If (for the combo) the text option is given to the widget as well, the text option value is used. If the id field is specified, this will be outputted from the widget when ssd exits. Otherwise the Entry text is outputted. The id field applies to the DropDown widget only. For the combo widget, the text field in the widget is always outputted. Example:
Begin: DropDown
Position: 1x1
AddItem: First thing
AddItem*: 2nd thing - Default
AddItem: AltId: Entry with alternative id
Item: The short form
End
Applies to: Combo, DropDown. BackgroundColorSpecify the background color of the widget. Applies to: The Main Window, Box, Button, CheckBox, Combo, DropDown, Label, LineEdit, Toggle, Page, Progress, Radio, Tabs. Cancel
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Widget \ Option | AddItem Item |
BackgroundColor ForegroundColor |
Cancel Default |
Center | EchoMode | Group | Id | Image | MaxSize MinSize |
Position | State | Style | Text | Is a parent | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Button | X | X | X | X | X | X | X | ||||||||
| CheckBox | X | X | X | X | X | X | X | X | |||||||
| Combo | X | X | X | X | X | X | |||||||||
| DropDown | X | X | X | X | X | ||||||||||
| Label | X | X | X | X | X | ||||||||||
| LineEdit | X | X | X | X | X | X | |||||||||
| Progress | X | X | X | X | |||||||||||
| Radio | X | X | X | X | X | X | X | X | |||||||
| Toggle | X | X | X | X | X | X | X | X | |||||||
| The Main Window | X | X | X | X | X | Yes | |||||||||
| Box | X | X | X | X | X | X | Yes | ||||||||
| Page | X | X | X | X | Yes | ||||||||||
| Tabs | X | X | X | For Page only | |||||||||||
When ssd exits, the status of the various widgets is printed to stdout. The output is on the form
<tag>=<value>
Example:
BUTTON='ok' TEXT='This is the text entered in a line edit widget...'
For most widgets, the tag is simply their Id, but there are exceptions. These are the Buttons, Grouped widgets and widgets that do not produce any output.
The first line of the output specifies how the application was exited. This can either be
BUTTON='EXTERNAL'
if it was closed with the keywords quit or exit on stdin (see the interaction section), from e.g. the window manager decoration, with a kill signal, or with CTRL-C. Otherwise it will be
BUTTON='<id of button clicked>'
This output relates to the state-containing widgets that can be grouped together. This is CheckBox, Toggle and Radio.
If the widget has been assigned to a group, the output is:
<group name>='<id of checked widget>'
Otherwise the output will be the standard output below.
Note: If no widget in a group has been checked (this may happen if no default checked widget has been set with the state option), the group will not produce any output.
These widgets produces the standard output on the form:
<id>=<value>
Below is a description of the value produced by the various widgets:
These widgets has the output '1' if checked and '0' otherwise. Example
MyCheckBox='1'
The value is the content of the LineEdit that is a part of the widget. In contrast to the DropDown widget, the id-part of the AddItem option is ignored.
The value is either
The value is simply the content of the widget. Example
NAME='This is my name entered in a LineEdit widget...'
Index count (from zero) of the selected tab page.
The following widgets does not produce any output: The Main Window, Box (if State has not been specified), Label, Page, Progress.
This section provides some examples of the use of ssd. The examples can either be saved to a file and given as an argument to ssd, or pasted to stdin of ssd (end the input with CTRL-D, Enter).
Begin: Label
Position: 1x1-3
Text = Are you sure you want to continue with whatever you are doing? In other words: Do you KNOW what you are doing?
Wordwrap = true
End
Begin: Button
Position: 2x1
Cancel
Text = Cancel
Id=no
End
Begin: Button
Position: 2x3
Default
Text = OK
Id=yes
End
Begin: Tabs
Position: 1x1-3
Begin: Page
Text = Page no 1
Begin: CheckBox
Text = CheckBox no 1
Group = mygroup
Position: 1x1
State = 1
End
Begin: CheckBox
Text = CheckBox no 2
Group = mygroup
Position: 2x1
End
Begin: CheckBox
Text = CheckBox no 3
Group = mygroup
Position: 3x1
End
Begin: CheckBox
Text = CheckBox no 4
Group = mygroup
Position: 4x1
End
End
Begin: Page
Text = Page no 2
Begin: Label
Text = Notice that an empty label has been\ninserted at the bottom in order for the\nextra space to be placed down there.
Position: 1x1
End
Begin: Button
Position: 2x1
Text = Just a dummy button.
Default
Cancel
End
Begin: Label
Position: 3x1
# Empty label creating space...
End
End
End
Begin: LineEdit
Text = The default text in LineEdit
Position: 1x1
End
Begin: DropDown
Position: 2x1
AddItem: First thing
AddItem*: 2nd thing - Default
AddItem: AltId: Entry with alternative id
Item: The short form
End
Begin: Combo
Position: 3x1
AddItem: First thing
AddItem: 2nd thing (cannot be default)
AddItem: No entry with alternative id
Item: The short form
Text: This is the default text
End
Begin: Box
Position: 1x1
Text = Normal box
Begin: Label
Position: 1x1
Text = State-containing widgets in this\nbox have been grouped together.
End
Begin: Toggle
Text = A toggle button
State = 1
Position: 2x1
Group = DaGroup
End
Begin: CheckBox
Text = A check box
Position: 3x1
Group = DaGroup
End
Begin: Radio
Text = A radio button
Position: 4x1
Group = DaGroup
End
End
Begin: Box
Position: 1x2
Text = Box with check box
State = 1
Begin: Label
Position: 1x1
Text = State-containing widgets in this\nbox is stand-alone.
End
Begin: Toggle
Text = A toggle button
State = 1
Position: 2x1
End
Begin: CheckBox
Text = A check box
Position: 3x1
End
Begin: Radio
Text = A radio button
Position: 4x1
End
End
The following two files should be saved and made executable. Be sure to correct the path to both bash and ssd (first line of each file). Then run prefs.sh.
It illustrates how to easily implement some functionality with bash. Notice that the file to ssd is created as a sh-bang (the first line).
#!/bin/bash
eval `./prefs.ssd`
if [ "$BUTTON" != "OK" ]; then
echo "The user canceled the dialog box."
exit
fi
echo "The user choose the following:"
echo "Internet: $INTERNET"
echo "Mail: $MAIL"
echo "Screen saver: $SCR"
#!/path/to/ssd
# Main Window settings
Text = Global user settings
Style = plastique
# A label at the top
Begin: Label
Position: 1x1-4
Text = Please specify your preferences:
End
# Three labels
Begin: Label
Text = Favorite browser:
Position: 2x1-2
End
Begin: Label
Text = Favorite mail client:
Position: 3x1-2
End
Begin: Label
Text = Favorite screen saver:
Position: 4x1-2
End
# Three choices
Begin: DropDown
Position: 2x3-4
AddItem*: firefox : Firefox
AddItem: opera : Opera
AddItem: xterm -e lynx : Lynx
Id = INTERNET
End
Begin: DropDown
Position: 3x3-4
Item*: thunderbird : Thunderbird
Item: xterm -e pine : Pine
Id = MAIL
End
Begin: Combo
Position: 4x3-4
Item*: xlock -mode blank
Item: xlock -mode xjack
Id = SCR
End
# Two buttons - cancel and ok
Begin: Button
Text = Cancel
Cancel
Position: 5x1
Id = CANCEL
End
Begin: Button
Text = OK
Default
Position: 5x4
Id = OK
End
#!/bin/bash
(
for i in 10 20 30 40 50 60 70 80 90; do
echo prgbar = $i
sleep 0.5
done
echo prgbar = 100
echo lbl = Done.
echo CANCEL = Ok.
sleep 2
echo quit
) | /usr/bin/ssd <(
cat - << EOF
Begin: Progress
Position: 1x1
id=prgbar
End
Begin: Label
Position: 2x1
Text = Applying settings, please wait...
id = lbl
End
Begin: Button
Position: 3x1
Default
Text = Cancel
Id=CANCEL
End
EOF
)
No known bugs at the moment. Most likely a couple of unknown...
ssd has been written by Jørn V. Christensen (mail@mettle.dk).
Patches contributed by Vasya Novikov (vasiliy.novikov@gmail.com) and Rene Reucher (rene.reucher@batcom-it.net).