we will now present the various commands issued by the script. Those commands will be split by task
All command sent to shellmod are done using the echo shell command. They always looks like:
echo command arg1 arg2 arg3
Arguments are either a single or multiple words (separated with spaces).
To group multiple words as a single argument, quotes must be used.
While this is standard command line practice, there is a catch: Quoting
will only affect the argument as seen by the echo command.
Once process, the whole line will be received as a single stream of
words separated by space and the quote will be gone. The quotes must
be part of the line received by shellmod. Here is an example
echo newf_str name \"Enter your name\" \"Tux the penguin\"
The shellmod-lib.sh define the qecho helper function you may used to get
a more standard shell quoting behavior. Here the same example rewritten
with qecho.
qecho newf_str name "Enter your name" 'Tux the penguin'
As you see, with qecho you can mix the different shell
quoting syntax. The qecho function insures that proper
double quotes surround all arguments.
Shell scripts are not that good at handling and passing multi-line text. The "defval" command was created to fix that. Here is a typical usage:
echo var1 "This is the first line"
echo var1 "This is the second line"
echo error =var1
This creates a popup error message with two lines. "defval" is used repeatedly to define the multi-line text and is referenced as an argument using the = sign. The argument must not be quoted. So you can't use the qecho helper function using a defvar parameter, because qecho insures quoting around all parameters.
A dialog always starts with this command. It requires no further argument. Then you stuff it with field definitions, add optional buttons and then you call the edit function. Here is a sample:
echo DIALOG
echo newf_str var \"field title\" value
edho edit \"Dialog title\" \"Dialog introduction\"
dispatch
echo end
This requires the window manager to present this dialog as an independant window in the middle of the screen. This is usually used for transient dialog requiring immediate attention from the user.
This pops up the dialog. The window title control using the first argument and the longer dialog description is controlled by the introduction field.
The last argument is option and lets you control the buttons displayed at the bottom of the dialog. The value "0" means to display no button (useful to display some gauge for example).
When the last argument is omitted, the button Accept and Cancel are displayed.
This works like edit. It pops up the dialog with the same arguments. But it return immediatly. This is generally used with the newf_gauge command.
This yield control to Linuxconf/shellmod and wait for results. Field variable are updated and the CODE variable is set to the button value selected by the user: This is either "accept" or "cancel".
This deletes the dialog. It is removed from the screen and forgotten. We often issue the end command right after the dispatch command. But more complex dialog may use the end command after a validation loop.
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
main(){
echo DIALOG
echo newf_str name \"User name\"
while true
do
echo edit \"User query\" \"Enter the user name\"
dispatch
if [ "$CODE" = "cancel" ] ; then
break
elif [ "$name" = "" ] ; then
echo error \"Please provide a name\"
else
echo notice \"Doing something with the user account\"
break
fi
done
echo end
}
dispatch
This is handled by the DIALOG_MENU and new_menuitem commands.
This does not require any argument.
This records one menu entry. Each menu entry is associated with one script function (that must be defined). The prompt is generally a keyword. The title is the rest of the menu entry.
This pops the menu. It is followed by a call to dispatch.
This is where everything is done for a menu. The dispatch function will run until the user select the "quit" button. The corrresponding function is called whenever a menu entry is selected. This is handled transparently by the dispatch function.
Note that the dispatch function also exits if the user select an optional buttons (added with the button command). So it is possible to handle a in a loop like the example dialog above.
This deletes the menu.
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
menufunc1(){
echo notice \"menufunc1 selected\"
}
menufunc2(){
echo notice \"menufunc2 selected\"
}
main(){
echo DIALOG_MENU
echo new_menuitem menufunc1 Select \"First option\"
echo new_menuitem menufunc2 \"\" \"Second option\"
echo editmenu \"Main menu\" \"Pick an option\"
dispatch
echo end
}
dispatch
A DIALOG_LIST is just a variation of a menu. The main difference is that the number of entry might be very long. In that case a filter dialog will popup so restrict the amount of diaplayed record. You can deal with very large list of item.
DIALOG_LIST does not require any argument.
You can define the heading of the list. This is optional, but looks much more nicer.
It works like DIALOG_MENU, except that we often supply more columns. There is another variation as the function is defined with arguments. Note that this may be used with DIALOG_MENU as well. We generally define one function per menu entry and a single function to process each record of the list, using the argument to differentiate the processing.
Note also that you can use a mixed solution within the same DIALOG_MENU or DIALOG_LIST: You can use a single function to provide a common processing for some record and different function to manage exception.
Same as with DIALOG_MENU.
This behave like the DIALOG_MENU.
This delete the list.
Here is a realistic example where we display a directory
and let the user pick one file and do something with it.
We see in this example how easy it is to parse the output
of the "ls -l" command and present the file name, the
size and revision date in three formatted column.
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
fileshow(){
echo notice \"Processing file $1\"
}
main(){
echo DIALOG_LIST
echo newf_head \"File name\" Sise \"Revision date\"
ls -l $1 | \
(
read total
while read perm count user group size month day hour name
do
echo new_menuitem \"fileshow $name\" $name $size \"$month $day $hour\"
done
)
echo editmenu \"Current directory\" \"This show all file in the current directory\"
dispatch
echo end
}
dispatch
All commands defining a dialog field start with the prefix newf_.
We have used the same name and same parameter order (when possible)
as the C++ module API.
The first argument is always the name of the shell variable which will receive the value entered by the user. You will often use the following construct to edit (correct the current value) of a given variable.
qecho newf_str var "title" "$var"
.
qecho edit ...
dispatch
if [ "$CODE" = "accept" ] ; then
if [ "$var" = "..." ] ;then
.
.
fi
fi
Here is the list of all field definition commands:
Setup a check box field (on/off or yes/no). The variable var will be setup to either 0 or 1. This field has two title. One on the left of the check box and one on the right. This is often used like this in Linuxconf:
The current feature [ ] is selected
When using newf_chk, you must pass a 0 or 1 as the value. The edit variable will receive the result as 0 or 1. This is not so useful as often shell script are dealing with different type of boolean value. For example, a script dealing with an SQL server may find itself dealing with Y and N values. To avoid translating from one system to the other, the syntax of the initial value has been expanded.
value:on_value:off_value
$var:ON:OFF
Setup of multiple selection field using check boxes. The boxes are presented horizontally. Here is an example followed with the field it produced in text mode:
echo newf_chkm sel \"Which position\" 1 left center right
This produces:
Which position ( ) left (o) center ( ) right
The variable var will take the numerical index of the selected item, starting at 0.
Setup a single line + selector field. The user will be able to pick a value out of a pick list or enter another by hand. The variable var will contain the textual value either entered or selected.
newf_combo is used with the comboitem command. You setup first the combo field and then you pass one by one the possible values using comboitem. Note that the values are followed by a descriptive text (optional). Here is a code sample:
echo newf_combo port \"Which port\" ttyS1
echo comboitem ttyS0 \"COM1 in DOS\"
echo comboitem ttyS1 \"COM2 in DOS\"
echo comboitem ttyS2 \"COM3 in DOS\"
The variable $port will take the value ttyS0, ttyS1, ttyS2 or anything the user dares to enter. See newf_enum and newf_list for a variation of this input field.
Setup a numerical input field with decimal notation. Works
like
newf_num
except that a decimal point is allowed. The number of decimal parameter
control the number of digits allowed after the decimal point as well
as the formatting of the field.
Setup a selector field. The user will be able to pick a value out of a pick list. The variable var will contain the index of the selected item. The user is limited to picking one item of the list.
newf_enum is used with the enumitem command. You setup first the enum field and then you pass one by one the possible values using enumitem. Here is a code sample:
echo newf_enum no \"Which port\" 1
echo enumitem ttyS0 \"COM1 in DOS\"
echo enumitem ttyS1 \"COM2 in DOS\"
echo enumitem ttyS2 \"COM3 in DOS\"
The variable $no will take the value 0 1 or 2. See newf_combo and newf_list for a variation of this input field.
Setup a visual gauge, generally used to display the completion status of a process (loading, installing). The state of the gauge is changed by calling this command again. The first call defines the field, the next ones update the gauge. This widget is generally used with the "show" command so the script never stop in the "edit" state. Here is a small example
echo DIALOG
qecho newf_gauge ID "Status" 0 10
qecho show "Status" ""
i=0
while [ "$i" != "10" ] ; do
i=`expr $i + 1`
sleep 1
qecho newf_gauge ID "Status" $i 10
qecho show "Status" ""
done
Setup a numerical input field (integer). Works like
newf_num
but accept digits and hexa-decimal digits.
Setup an information field. It is presented like an input field with a prompt on the left, but the field value is simply drawn and can't be edited.
Setup a selector field. The user will be able to pick a value out of a pick list only The variable var will contain the textual value selected.
newf_list is used with the listitem command. You setup first the list field and then you pass one by one the possible values using listitem. Note that the values are followed by a descriptive text (optional). Here is a code sample:
echo newf_list port \"Which port\" ttyS1
echo listitem ttyS0 \"COM1 in DOS\"
echo listitem ttyS1 \"COM2 in DOS\"
echo listitem ttyS2 \"COM3 in DOS\"
The variable $port will take the value ttyS0, ttyS1 or ttyS2. See newf_enum and newf_combo for a variation of this input field.
Setup a numerical input field (integer). Works like newf_str
but accept only digit.
Setup a password field. Works like a newf_str field except
the input is not echoed (invisible typing).
Setup a radio button field. Several radio button fields must be defined for each possible selection. All radio buttons sharing the same input variable (var above) operate together: Selecting one De-select the other. The var variable will get the numeric-value of the selected radio button field.
Related radio buttons may be placed anywhere in a dialog. They do not have to be sequential or even on the same page of the notebook dialog
This works like the newf_num, to edit a decimal value. But it is shown as a visual slider. The minimum and maximum value represent the left and right edge of the slider.
qecho newf_slider var "Meeting hour" 15 9 16
Setup a one line text input.
This is not an input field but a way to organize a large dialog in section. The end result is far different in graphic mode than in text or HTML mode. In graphic mode, this will create a notebook dialog and each newf_title defines one page (one pad) of the notebook.
The first argument, pad title, is only used in graphic mode.
The second argument is a number and represent the notebook level. This allows very complex dialogs with notebook within notebook. In text and HTML mode, this argument has no effect.
The third argument, left title, is used only in text and HTML mode. It places a small title on the left of the input fields.
The last argument, text mode title, appears centered between two input fields.
You can add optional buttons simply by using the button command. It requires to arguments. The first is the button ID which will be passed to the script using the CODE variable. The second is the label (title) of the button. Here is an example:
echo DIALOG
echo newf_str name \"User name\" $name
echo button Add \"Add a new user\"
echo edit "title" \"User management\"
dispatch
echo end
if [ "$CODE" = "Add" ] ; then
# Adding a new user
elif [ "$CODE" = "accept" ] ; then
# Inspecting a user record
fi
The "setcurfield" opcode sets the keyboard focus on a specific field. You must pass the field ID as a single argument. Here is an example:
qecho DIALOG
qecho newf_str uid "User id"
qecho newf_str name "Name"
qecho newf_str phone "Name"
qecho setcurfield name
qecho edit "sample" "The focus is now on name"
dispatch
echo end
Remove all fields from a dialog, allowing you to redefine its content.