4 Widgets

Prev		Next

The dialog description language is a simple XML like language capable to denote any complex dialog box containing widgets and boxes.

Widgets are simple GUI elements such as buttons, entry fields, lists, etc. Widget can have attributes, states and actions (*note Actions::).

The widgets are grouped together with containers (*note Containers::), horizontal and vertical boxes or frames. Every widget should placed in one of the containers, no widgets can be alone for it is dangerous outside.

4.1 Static label

Label is a static text widget created with '<text></text>' tag.

The text in a static label, can be set with the '<label>STRING</label>' or the '<input file>FILENAME</input>' expression.

4.2 Pushbutton

The pushbutton is a clickable widget defined with the '<button></button>' tags.

4.2.1 '<label></label>'

The '<label>STRING</label>' directive sets the text label of the pushbutton. If no label and pixmap is given for the button, gtkdialog will use OK as default.

4.2.2 '<input file></input>'

When creating buttons, the '<input file>FILENAME</input>' tag can be used to insert a pixmap into the button. The FILENAME must be a pixmap file. Gtkdialog will find this file with the 'locate' utility if necessary.

The pushbuttons can contain a label and a pixmap simultaneously. For this you have to use the '<label></label>' and the '<input file></input>' as the next example shows:

<button>
  <input file>/usr/share/GUIcompletion/button_save.xpm</input>
  <label>The label</label>
</button>

4.2.3 '<action></action>'

The '<action>COMMAND</action>' directive tells the gtkdialog what to do, when the button is pressed. If the action is not given explicitly the gtkdialog uses the default action, which is to exit the program. In this case the printed variable list will contain a variable named EXIT, with the label of the activated button as value.

The buttons can handle more than one actions simultaneously. If there are more '<action></action>' directive for the given button, they will be executed one by one, in the right order.

4.2.4 '<visible></visible>'

The '<visible>STATE</visible>' specify the initial visibility of the button. The STATE can be either 'enabled' or 'disabled'. When a button is disabled, it is shaded and can not be activated by mouse or keyboard.

4.3 Pre-defined pushbuttons

Gtkdialog supports a few pre-defined pushbuttons for simplify the creation of dialog boxes. The pre-defined buttons can be used the same manner the normal pushbuttons, but they have a default text, pixmap and output variable. Here is the list of available pre-defined pushbuttons:

'<button ok></button>'
'<button cancel></button>'
'<button help></button>'
'<button yes></button>'
'<button no></button>'

4.4 Entry

The entry widget is a simple text input field, which can be used to get a string from the user.

4.4.1 '<default></default>'

The '<default>STRING</default>' directive sets the default content of the entry.

4.4.2 '<visible></visible>'

The '<visible>VISIBILITY</visible>' sets the initial state of the entry widget. The VISIBILITY can be 'enabled', which means the entry can be used, 'disabled', which means the content of the entry can not be altered or 'password'.

The entry widgets with the visibility set to 'password' are editable, but unreadable as it is common with entries holding password style information.

4.4.3 '<action></action>'

The entry widgets are activating actions after their contents are changed.

4.5 Checkbox

The checkbox is a simple widget with a label and a check mark which can be turned on and off by the user. Checkboxes are made with the '<checkbox></checkbox>' directive.

4.5.1 '<label></label>'

The label is the text shown beside the check mark. Every checkbox should have a label.

4.5.2 '<default></default>'

The initial state of the checkbox can be set by the '<default>STATE</default>' directive, where the STATE can be either 'yes' or 'no'.

4.5.3 '<action></action>'

The '<action></action>' directive tells the gtkdialog what to do, when the state of the checkbox is changed. As every widgets, the checkbox can hold multiply actions which are executed serially in the order they are written.

Actions of checkboxes can be written as conditional instructions with 'if true' and 'if false' prefixes as in the next example:

<checkbox>
   <label>This is a checkbox...</label>
   <variable>CHECKBOX</variable>
   <action>echo Checkbox is $CHECKBOX now.</action>
   <action>if true enable:ENTRY</action>
   <action>if false disable:ENTRY</action>
</checkbox>

4.5.4 '<visible></visible>'

The '<visible>STATE</visible>' specify the initial visibility of the checkbox. The STATE can be either 'enabled' or 'disabled'. When a checkbox is disabled, it is shaded and its state can not be altered anyway.

4.5.5 '<variable></variable>'

The value of a checkbox can be 'true' or 'false' and depends only on its state.

4.6 Pixmap

The '<pixmap></pixmap>' defines a static pixmap widget.

4.6.1 '<input file></input>'

The widget must have an input file defined with the '<input file>FILENAME</input>' tags. The FILENAME is the graphic image file for the pixmap. Gtkdialog will load this file if it can be opened for read, or will try to find a file with similar name (using the 'locate' utility program) if the file is unreadable.

The next example defines a static pixmap:

<pixmap>
  <input file>help.png</input>
</pixmap>

4.7 Menubar

The '<menubar></menubar>' defines menu bar which can be placed as any other screen elements. In the menubar widget you have to create menus with the '<menu></menu>' tag, and inside the menu must be at least one menu item created by the '<menuitem></menuitem>' tag.

The next example shows how to create a simple menubar with only one menu:

<menubar>
  <menu>
    <menuitem>
      <label>gtk-open</label>
    </menuitem>
    <menuitem>
      <label>gtk-save</label>
    </menuitem>
    <menuitem>
      <label>gtk-quit</label>
      <action>EXIT="quit"</action>
    </menuitem>
    <label>File</label>
  </menu>
</menubar>

4.8 The tree

OK, it is not complete, but the next example seems to be just fine.

<vbox>
  <tree>
    <label>Device    |Directory        |File         </label>
    <item>Hard drive |/usr/            |letter.tex    </item>
    <item>Hard drive |/etc/            |inittab       </item>
    <item>Hard drive |/etc/            |fstab         </item>
    <item>Network    |alpha:/home      |quota.user    </item>
    <item>Network    |alpha:/home      |quota.group   </item>
    <item>Network    |beta:/home/pipas |tmp           </item>
    <item>Network    |beta:/home/pipas |latexfiles    </item>
    <item>Network    |beta:/home/pipas |book          </item>
    <item>Network    |beta:/home/pipas |bin           </item>
    <item>Network    |beta:/home/pipas |documentation </item>
  </tree>
  <button ok></button>
</vbox>