Here is the list of all commands understood by the protocol. They are in alphabetical order. ID are single words which identify the widget/component uniquely in the dialog (form) where they are placed.
Each command is preceded by its numeric ID within parentheses.
Place a button with the given text. If dump_needed is 1, a dump of the state of the dialog is needed when this button is depressed.
Display a button with an Icon previously transfered.
Same, except that the XPM is a given by a file path, so available to the java component. Not really used for the Linuxconf project.
Place a button with the given text. This button is a ack. It will span all the allocated place of its cell. If there is a button like itself before, then the shadow is cut on the left. If there is a buttonfill on the right, the right shadow is not drawn.
This button is used to do list. The interest of using independent button to draw list is that they self align in columns, thanks to the layout policy, and this independent of the font.
This button is a special widget. In the wxXt implementation, it is done "by hand". One may use a normal button also. The look is acceptable.
Place a checkbox (on/off widget) with some text after. The check-box appears in the selected (1) or unselected (0) state.
Place a textual item with a choice list selector on the right. This widget can only accept one value from the choice list. The choice list is transfered using the Choice_item command.
Accept on new value to the choice list of a Choice widget. The ID here is the same ID given with the Choice widget.
Each item of the help list has two information. The first is the selectable value. The second is a comment making the help list more informative.
A Choice list may not have a comment value. In this case, the first value is empty.
A Clist is a multi-columns table with a title for each column. The list has optionnally a scroll bar if it is too large (more than 300 pixels high for example).
Currently, the list behave like a menu. Clicking on one item produce an action.
Add one line to a Clist. The listID identify the list in which we must add an item. The itemID will be used in the "action" message sent to linuxconf, exactly like buttons.
Place a textual item with a choice list selector on the right. The widget accept any input but the user can use the selector to get a list of hint values.
maxlen select the width of the text field.
Add a new item to the help list of the Combo object identified by ID. Each item of the help list has two informations. The first is the value which will go in the text field if selected. The second is a comment making the help list more informative. The second one is optional.
Give focus to one widget of a specific Mainform. The widget receive focus and it made visible. This means that the Page where it is located may be scrolled. IF the page is part of a Book object, it become the current page.
Remove one Mainform identified by ID. The dialog is forgotten.
Return on stdout the content of one Mainform. The ID is used to locate the Mainform and the value of each input widget is printed. This lets Linuxconf grab the values of each fields.
This sets the default action to do when the key "enter" is depressed
in a dialog. Linuxconf sets this action for single field dialog.
The ID is the ID to return in the same way a button with this ID
would talk back to Linuxconf. A dump of the fields is also needed
before sending the
actiontt> command. The format of the action
action form-ID ID
Create an horizontal gauge. This is not an input field, but a visual widget used to present the progress of a process.
"range" is a positive integer and "value" is between 0 and "range".
"width" is expressed in pixels.
Gauge is generally used with the Setval primitive. This interactivly update the Gauge during a process.
Draw an horizontal 3D line that will fill one field cell. Using Dispolast, you can make it larger. If the text argument is not empty, then the text must be drawn centered in the line like this
----------- Some text ----------
Add an icon to the dialog. Not a button, just an icon. Linuxconf use that for error message. The icon has been transfered using Xfer_xpm.
inputgrid defines a grid in a form. The grid has its top left corner as x,y. It is made of nbcellh cells horizontally and nbcellv cells vertically. Each cells has the dimension cellwidth,cellheight.
This is not a visible widget, but simply a control region. Whenever the user click in the inputgrid and there is no widget located there, and action is reported to the application, using the ID, exactly like a button. The coordinate of the mouse as well as the button status are reported, so the application can identify which cells was selected.
Place some text in the dialog. A Label occupy one field cell so contribute to the layout. This is different from many GUI toolkit where the label is generally part of the component.
Define a new list. A list presents various item in a small window generally with a scrollbar. Visible tells how many item should be visible at once. Text represent the current value/selection in the list.
Add one item in the list ID.
Start a new horizontal line of GUI components.
This works like a String widget, except that there is no initial value and the editing is blind (no echo).
Enter one button/checkbox of a radio button set. A radio button is use to present one exclusive choice out of few. Clicking on one radio button UN-clicks the others with the same ID.
Instance is the value of this button. When selected, the object ID will have this value. state is either 0 or 1 and tells if the button is checked (1) or not (0).
This works like the Label command, except that the text may contain some underline and bold command. This is really crude so far. Currently, Linuxconf uses help generated for the ncurses interface. Linuxdoc-sgml is generating a strange pattern to manage underlining and bolding. Mostly, it works by using backspace (ASCII 8). There is really only two cases. For example to produce an underline A and a bold A, you have the following sequences.
This primitive update the value of a field in an existing dialog. This is used for more complex dialog, where some external events may affect the value of the field. For example, a dialog with a reset button will use this feature.
Dialog with gauge will also use this feature. Buttons (both text and icons) may be updated using this command. Clist content also.
Extra parameters may be passed as well to qualify the new value. For example, a new drawing context ($dc=ID) may be passed to modify the way a field (generally a label) is presented.
Set the weight or importance of the last component. This is used when a dialog is resized to spread the extra space available. New component inherit a weight of 0,0 when created. So only the stretchable items you specify will participate to the resizing of the dialog.
A sheet is a grid containing a textual fields. It has a title for each column. The titles are given as col1, col2, etc ... It has one or more lines. It may grow. At the bottom, a widget allows the user to add more lines.
When dumping the value of the sheet to linuxconf, a variation of the dump protocol is used. Since the sheet may grow (or shrink), linuxconf does not know how many line are dumped. The protocol goes like this: The id of the sheet is used to return the number of lines. Then for each item of the sheet, a special ID is built by combining the id of the sheet with the row/column of each field, using minus sign. A three lines, two columns sheet with ID h7 would dump like this.
dump path h7 3 dump path h7-0-0 some_value dump path h7-0-1 other value dump path h7-1-0 some_value dump path h7-1-1 some_value dump path h7-2-0 some_value dump path h7-2-1 some_value
This specifies the initial value of one cell of the sheet. The cell is identified by the row/column coordinate.
Place a side title on the left border of the dialog.
Create an horizontal visual input field. The use may select a value by sliding a select on a scale.
"minval" and "maxval" are integer values. The value must lie between "minval" and "maxval".
"width" is expressed in pixels.
Add one line of text to an accumulator. Some commands refers to this accumulator and clear it after use.
Place a text widget in the dialog. Maxlen is the visible length of the field and it is followed by the initial value.
This defines a multiple line text input (a text editor in fact). The text area must have approximatly "cols" columns (in characters) and "rows" lines. The word approximatly is used because the textarea widget may use a proportional font.
The widget may edit a larger text and may show scrollbars (suggested). The text value is transmitted as a sequence of Str command followed by and End command. Here is an example:
Textarea T0 80 10 Str "Here is one line" Str "Here is another" End
Linuxconf sends the protocol revision requested for the rest of the session. This is sent as the first transaction of the session. The proper action for the frontend is to test with its own protocol revision number (obtain from diajava/protorev.h). If the protocol is the same, then fine. If not, the front end simply prints the message in a window and quits after that.
The front-end may quit by itself or simply set a quit button in the dialog. The button must have the ID "badver". When Linuxconf receives this "action", it quits and this breaks the pipe.
This will make sure that the protocol may change in a safe manner in the future.
Install a copy of an XPM icon in memory. This icon has been transfered line by line using the Str command so is available in some accumulator. The ID will be used to reference to icon later.