Next Previous Contents

3. Protocol

we will now present the various commands issued by the script. Those commands will be split by task

3.1 Command layout and quoting

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.

3.2 Sending multi-line parameters

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.

3.3 Building a dialog

echo DIALOG

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
        

echo show \"title\" \"Introduction\"

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.

dispatch

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

echo end

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.

A complete example

#!/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
        

3.4 Building a menu

This is handled by the DIALOG_MENU and new_menuitem commands.

echo DIALOG_MENU

This does not require any argument.

echo new_menuitem function prompt title

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.

echo editmenu \"Menu title\" \"Introduction\"

This pops the menu. It is followed by a call to dispatch.

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.

echo end

This deletes the menu.

A complete example

#!/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
        

3.5 Managing a list of records

echo DIALOG_LIST

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.

echo newf_head \"Column1 title\" \"Column2 title\" ...

You can define the heading of the list. This is optional, but looks much more nicer.

echo new_menuitem \"function args\" \"Column1 value\" \"Column2 value\" ...

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.

echo editmenu \"List title\" \"Introduction\"

Same as with DIALOG_MENU.

dispatch

This behave like the DIALOG_MENU.

echo end

This delete the list.

A complete example

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

3.6 Defining fields

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
        

3.7 Command list

Here is the list of all field definition commands:

echo newf_chk var \"field title\" \"Initial 0 or 1 value\" \"Suffix title\"

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
        

Variation of the newf_chk syntax

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.

echo newf_chkm var \"field title\" \"Initial numeric value\" \"value1\" \"value2\" ...

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.

echo newf_combo var \"field title\" \"Initial value\"

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.

echo newf_dbl var \"field title\" \"Initial numeric value\" number-of-decimal

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.

echo newf_enum var \"field title\" \"Initial numeric value\"

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.

echo newf_gauge ID \"field title\" \"Initial decimal value\" \"Maximum value\"

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
        

echo newf_hexnum var \"field title\" \"Initial hexa-decimal value\"

Setup a numerical input field (integer). Works like newf_num but accept digits and hexa-decimal digits.

echo newf_list var \"field title\" \"Initial value\"

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.

echo newf_num var \"field title\" \"Initial numeric value\"

Setup a numerical input field (integer). Works like newf_str but accept only digit.

echo newf_pass var \"field title\" \"Initial value\"

Setup a password field. Works like a newf_str field except the input is not echoed (invisible typing).

echo newf_radio var \"field title\" numeric-value instance-value \"suffix title\"

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

echo newf_slider var \"field title\" \"Initial decimal value\" \"minimum value\" \"Maximum value\"

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
        

echo newf_str var \"field title\" \"Initial value\"

Setup a one line text input.

echo newf_title "Pad title" level "Left title" "Text mode title"

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.

3.8 Adding buttons

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
        

3.9 Set the current input field

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 
        


Next Previous Contents