Gtkdialog1 User's Manual

Table of Contents


Next: , Up: (dir)

Gtkdialog1 User's Manual

This manual documents version 1.4 of the Gtkdialog1 utility. Released April 2015.

Copyright © 2003 Laszlo Pere.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.


Next: , Previous: Top, Up: Top

1 Getting Gtkdialog1

1.1 Download

The source of Gtkdialog1 can be downloaded from http://distro.ibiblio.org/amigolinux/download/AmigoProjects/GtkDialog1/.1

1.2 How to Install the Program

gtkdialog1 uses GTK+, and requires GTK+ 1.2 or higher and gdk-pixbuf-0.21.0; it needs gtk-config in your path in order to build. It uses GNUautomake and autoconf, so it will automatically detect some features of your system that can affect gtkdialog1's performance. The program can be installed using the standard ‘./configure’, make and make install command sequence. If you wish to use GTK+ 2.0 or higher, do ‘./configure --with-gtk2’. Further details can be found in the INSTALL file included.

1.3 Copying

Copyright © 2003 Laszlo Pere.

The gtkdialog1 is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2.0 of the License, or (at your option) any later version.

The program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this software; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.


Next: , Previous: Getting Gtkdialog1, Up: Top

2 Introduction

Gtkdialog1 is a small utility program based on the GTK+ library. The program is mainly made for GUI development for shell scripts but can be used with many other programming languages. The programmer can easily create GUI not just for any shell script or UNIX command but for any interpreted or compiled program capable to start child process and use pipes.


Next: , Previous: Introduction, Up: Top

3 Invoking the Program

3.1 Examples

Our first example program shows how to call the gtkdialog1 from a BASH script.

     #! /bin/bash
     
     export MAIN_DIALOG='
      <vbox>
       <text>
         <label>This is a label...</label>
       </text>
       <hbox>
        <button ok></button>
        <button cancel></button>
       </hbox>
      </vbox>'
     
     gtkdialog1 --program MAIN_DIALOG

This example uses a very plain way to open a dialog box. We store the description of the dialog box in the MAIN_DIALOG environment variable which is exported to the child processes with the BASH export built-in. Then we call the gtkdialog1 program with the --program option which is followed by the name of the variable holding the dialog box description. It is simple and easy to write BASH scripts in this manner.

A similar calling method can be used when user input is needed. The gtkdialog1 send the state of the widgets to the standard output when exiting and this is how we can get user input for the BASH program. The next example code show the reading process.

     #! /bin/bash
     
     export DIALOG='
     <vbox>
       <entry>
         <variable>ENTRY</variable>
       </entry>
       <hbox>
         <button ok></button>
         <button cancel></button>
       </hbox>
     </vbox>'
     
     I=$IFS; IFS=""
     for STATEMENTS in  $(gtkdialog1 --program DIALOG); do
       eval $STATEMENTS
     done
     IFS=$I
     
     if [ "$EXIT" = "OK" ]; then
       echo "You entered: $ENTRY."
     else
       echo "You pressed the Cancel button."
     fi

In the example script we use the for built-in to go through the list gtkdialog1 produced. Changing the field separator (IFS) is a little bit disturbing but necessary since this is the only way to protect the space characters in user input.

In larger software projects it may be a good idea to break the code to separate files. Since gtkdialog1 can read the description program from file it is easy to write self executable programs with it. This is how the next example constructed.

     #! /usr/local/bin/gtkdialog1 -f
     <vbox>
       <checkbox>
         <label>This is a checkbox</label>
         <variable>CHECK1</variable>
       </checkbox>
       <checkbox>
         <label>Another one</label>
         <variable>CHECK2</variable>
       </checkbox>
       <button>
         <label>OK</label>
       </button>
     </vbox>

When used in this fashion the state of the widgets can get from the standard output of the script as usually.


Next: , Previous: Invoking the Program, Up: Top

4 Widgets

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 (see Actions).

The widgets are grouped together with containers (see 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.


Next: , Up: Widgets

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. The <input file>filename</input> can not be used in combination with <tooltip></tooltip> and <action>command</action>.

4.1.1 <visible></visible>

The <visible>state</visible> specify the initial visibility of the label. The state can be either enabled or disabled. When a label is disabled, it is shaded.

4.1.2 <tooltip></tooltip>

The <tooltip>tooltip</tooltip> specify the tooltip shown when the label has focus. The tooltip must have content if used.

4.1.3 <action></action>

The <action>command</action> directive tells the gtkdialog1 what to do, when the label is pressed. The action must have content if used.


Next: , Previous: Static label, Up: Widgets

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, gtkdialog1 will use OK as default.

4.2.2 <input file></input>

When creating buttons, the <input file>filename</input>, <input file icon="filename"></input> or <input file stock="filename"></input> tag can be used to insert a pixmap into the button. The filename must be a pixmap file.

The icon and stock should be without image extension (ex.: ".png"). Gtkdialog1 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 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>
     <button>
     	<input file stock="gtk-edit"></input>
     	<label>The label</label>
     </button>
     <button>
     	<input file icon="gnome-dev-cdrom-audio"></input>
     	<label>The label</label>
     </button>

4.2.3 <action></action>

The <action>command</action> directive tells the gtkdialog1 what to do, when the button is pressed. If the action is not given explicitly the gtkdialog1 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.2.5 <width></width> <height></height>

The <width>width</width> and <height>height</height> specify the width and height of the button. Both values must be given. This is only applied on buttons with a pixmap.

4.2.6 <default></default>

The <default>state</default> directive sets the default relief style of the edges of the given button. The state can be either none or half and the default is normal.

4.2.7 <tooltip></tooltip>

The <tooltip>tooltip</tooltip> specify the tooltip shown when the button has focus. The tooltip must have content if used.

4.2.8 <position></position>

The <position>state</position> specify the position of the text on the button. The state can be either top or bottom. This is only applied on buttons with both a label and a pixmap.


Next: , Previous: Pushbutton, Up: Widgets

4.3 Pre-defined pushbuttons

Gtkdialog1 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:


Next: , Previous: Pre-defined pushbuttons, Up: Widgets

4.4 Entry

The entry widget is a simple text input field, which can be used to get a string from the user. It can be set with the `<entry>STRING</entry>' or the <entry max_length="INTEGER">STRING</entry>. The max_length= sets the maximum of characters a user can input.

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 when their contents are changed.

4.4.4 <tooltip></tooltip>

The <tooltip>tooltip</tooltip> specify the tooltip shown when the entry has focus. The tooltip must have content if used.

4.4.5 <width></width> <height></height>

The <width>width</width> and <height>height</height> specify the width and height of the entry. Both values must be given.


Next: , Previous: Entry, Up: Widgets

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/true or no/false.

4.5.3 <action></action>

The <action></action> directive tells the gtkdialog1 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.5.6 <tooltip></tooltip>

The <tooltip>tooltip</tooltip> specify the tooltip shown when the checkbox has focus. The tooltip must have content if used.


Next: , Previous: Checkbox, Up: Widgets

4.6 Radiobutton

Radiobutton is a widget that gives a one choice of one of multiple check buttons.

4.6.1 <label></label>

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

4.6.2 <default></default>

The initial state of the radiobutton can be set by the <default>state</default> directive, where the state can be either yes/true or no/false.

4.6.3 <tooltip></tooltip>

The <tooltip>tooltip</tooltip> specify the tooltip shown when the radiobutton has focus. The tooltip must have content if used.

4.6.4 <visible></visible>

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

4.6.5 <action></action>

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

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

     <vbox>
     	<radiobutton>
     		<label>First radiobutton in the group...</label>
     	</radiobutton>
     	<radiobutton>
     		<label>This one is needed for OK button.</label>
     		<action>if true enable:OKBUTTON</action>
     		<action>if false disable:OKBUTTON</action>
     	</radiobutton>
     	<radiobutton>
     		<label>Third radiobutton...</label>
     		<default>true</default>
     	</radiobutton>
     	</frame>
     	<hbox>
     		<button ok>
     			<variable>OKBUTTON</variable>
     			<visible>disabled</visible>
     		</button>
     	</hbox>
     </vbox>


Next: , Previous: Radiobutton, Up: Widgets

4.7 Pixmap

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

4.7.1 <input file></input>

The widget must have an input file defined with one of the <input file>filename</input>, <input file icon="filename"></input> or <input file stock="filename"></input> tags. The filename is the graphic image file for the pixmap. The icon and stock should be without image extension (ex.: ".png"). Gtkdialog1 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 pixmap:

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

4.7.2 <width></width> <height></height>

The <width>width</width> and <height>height</height> specify the width and height of the pixmap. Both values must be given.

4.7.3 <visible></visible>

The <visible>state</visible> specify the initial visibility of the pixmap. The state can be either enabled or disabled. When a pixmap is disabled, it is shaded.

4.7.4 <action></action>

The <action></action> directive tells the gtkdialog1 what to do, when the state of the pixmap is changed. The action must have content if used. The <action></action> can not be used in combination with the Refresh:Name called by another widget.

4.7.5 <tooltip></tooltip>

The <tooltip>tooltip</tooltip> specify the tooltip shown when the pixmap has focus. The tooltip must have content if used. The <tooltip></tooltip> can not be used in combination with the Refresh:Name called by another widget.


Next: , Previous: Pixmap, Up: Widgets

4.8 List

The <list></list> widget is a one column table. Only one item in the list can be selected a time.

4.8.1 <item></item>

The <item>string</item> add a row with the string to the list.

4.8.2 <input></input>

The <input>command</input> fills the list by the output of the command

4.8.3 <action></action>

The <action></action> directive tells the gtkdialog1 what to do, when the state of the list is changed. The action must have content if used.

Example:

     <vbox>
     	<list>
     		<input>ls</input>
     		<item>First item</item>
     		<item>Second item</item>
     		<item>Third item</item>
     	</list>
     </vbox>


Next: , Previous: List, Up: Widgets

4.9 Scale

The <vscale></vscale> defines a vertical slider widget used to select a value from a range. The <hscale></hscale> defines a horizontal slider widget used to select a value from a range.

4.9.1 <default></default>

The <default>string</default> directive sets the default value of the vscale/hscale. Alternative the syntax <vscale range-value="INTEGER"></vscale>" can be used.

4.9.2 <mini></mini>

The <mini>string</mini> directive sets the minimum value of the vscale/hscale. Alternative the syntax <vscale range-min="INTEGER"></vscale>" can be used.

4.9.3 <maxi></maxi>

The <maxi>string</maxi> directive sets the maximum value of the vscale/hscale. Alternative the syntax <vscale range-max="INTEGER"></vscale>" can be used.

4.9.4 <vscale range-step="INTEGER"></vscale>

The <vscale range-step="INTEGER"></vscale> directive sets the stepping value of the vscale/hscale.

4.9.5 <vscale draw-value="TRUE"></vscale>

The <vscale draw-value="TRUE"></vscale> directive will print the current value of the vscale/hscale.

4.9.6 <width></width> <height></height>

The <width>width</width> and <height>height</height> specify the width and height of the vscale/hscale. Both values must be given. Alternative the syntax <vscale width-request="INTEGER"></vscale>" can be used.

4.9.7 <action></action>

The <action></action> directive tells the gtkdialog1 what to do, when the state of the vscale/hscale is changed. The action must have content if used.

4.9.8 <tooltip></tooltip>

The <tooltip>tooltip</tooltip> specify the tooltip shown when the vscale/hscale has focus. The tooltip must have content if used.

4.9.9 <visible></visible>

The <visible>state</visible> specify the initial visibility of the vscale/hscale. The state can be either enabled or disabled. When a vscale/hscale is disabled, it is shaded.

4.9.10 <input></input>

The <input>command</input> fills the vscale/hscale by the output of the command


Next: , Previous: Scale, Up: Widgets

4.10 Vseparator

The vseparator is a simple widget which draw a vertical line between widgets. Vseparator are made with the <vseparator></vseparator> directive.


Next: , Previous: Vseparator, Up: Widgets

4.11 Hseparator

The hseparator is a simple widget which draw a horizontal line between widgets. Hseparator are made with the <hseparator></hseparator> directive.


Next: , Previous: Hseparator, Up: Widgets

4.12 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>
         <separator></separator>
         <menuitem>
           <label>gtk-quit</label>
           <action>EXIT="quit"</action>
         </menuitem>
         <label>File</label>
       </menu>
     </menubar>

4.12.1 <action></action>

The <action></action> directive tells the gtkdialog1 what to do, when the state of the menuitem is changed. The action must have content if used.

4.12.2 <tooltip></tooltip>

The <tooltip>tooltip</tooltip> specify the tooltip shown when the menuitem has focus. The tooltip must have content if used.

4.12.3 <separator></separator>

The <separator></separator> draws a line between the menuitems.


Next: , Previous: Menus, Up: Widgets

4.13 The table

The <table></table> creates a GtkCList widget - a very useful multi-columned scrolling list. It can display data in nicely aligned vertical columns, with titles at the top of the list. The items in the table is autosorted and the width of each column is auto sized to reflect the size of the content. By clicking on the column header the column is sorted.

4.13.1 <label></label>

The <label>label</label give the name of each column - separated with "|".

4.13.2 <item></item>

The <item>string</item> add a row with the string to the table.

4.13.3 <input></input>

The <input>command</input> fills the table by the output of the command

4.13.4 <width></width> <height></height>

The <width>width</width> and <height>height</height> specify the width and height of the table. Both values must be given.

4.13.5 <default></default>

The <default>state</default> directive tells if single or multiple rows can be selected. The state can be either single or multi.

4.13.6 <action></action>

The <action></action> directive tells the gtkdialog1 what to do, when the state of the selection is changed. The action must have content if used. Note that two signals will be emitted - one for the select and one for the unselect.

     <vbox>
       	<table>
     		<label>Permissions|Links|Owner|Group|Size|Date|Time|Name</label>
     		<input>ls -l | grep -v total | tr -s ' '| tr ' ' '|'</input>
     		<width>400</width><height>200</height>
     		<default>multi</default>
     	</table>
       	<button ok></button>
     </vbox>


Previous: Tables, Up: Widgets

4.14 The chooser widget, embedded fileselector

The <chooser></chooser> creates an embedded fileselection widget. The chooser widget emits signals when file-activated, selection changed and when current-folder-changed.

The <default></default> sets the directory to start listing. View example below:

     <vbox>
     	<chooser>
     		<default>/usr/bin</default>
     		<action when="file-activated">echo file activated</action>
     		<action when="selection-changed">echo selection changed</action>
     		<action when="current-folder-changed">echo current folder changed</action>
     	</chooser>
     </vbox>


Next: , Previous: Widgets, Up: Top

5 Containers

The widgets are grouped together with containers, horizontal and vertical boxes or frames.

5.0.1 <vbox></vbox>

The vbox is a container that organizes its child widgets into a single column. Example:

     <vbox margin="30">
     		<button ok></button>
     </vbox>

The "margin=" tag tells which margin between widgets to use.

5.0.2 <hbox></hbox>

The hbox is a container that organizes its child widgets into a single horizontal row. Example:

     <hbox margin="30">
     		<button ok></button>
     </hbox>

The "margin=" tag tells which margin between widgets to use.

5.0.3 <frame></frame>

This code <frame name>string</frame> create a frame widget in which other widgets can be placed. Example:

     <vbox>
     	<frame This is the frame name>
        		<button ok></button>
     	</frame>
     </vbox>

5.0.4 <notebook></notebook>

The notebook widget creates a number of containers set by the number of labels. The content of each container is determined by the widgets included within the <notebook></notebook> tags. Example:

     <vbox>
     	<notebook labels="One|Two" tabpos="top" show-border="yes" scroll="no" show-tabs="no">
     		<text>
     			<label>Some text here</label>
     		</text>
     		<button ok></button>
     	</notebook>
     </vbox>

The labels= give the name of each notebook part - separated with "|". The tabpos= gives the position of the tabs - "top", "right", "button" and "left" can be used. The show-border= tells if borders should be visible - "yes" and "no" can be used. The scroll= replace some tabs with navigating arrows - "yes" and "no" can be used. The show-tabs= makes tabs invisible - cant see reason to use it - any value given is ignored.


Next: , Previous: Containers, Up: Top

6 Actions

When the user changes the state of a widget, gtkdialog1 checks if there is something to do with it. If the tampered widget have one or more actions, the program will execute them for the new situation to be handled.

Every widget can have multiply actions, a list of commands must be executed when the widget changed. Gtkdialog1 executes the actions in the order they found in the dialog description program, so one can write a complete program as a series of instructions.


Next: , Up: Actions

6.1 Start and exit

6.1.1 Start programs

If the action of a widget is created with the simple <action>command</action> directive, gtkdialog1 will execute it in a subshell. That means it will start up /bin/sh to handle the operation. Here is how the subshell operation works:

  1. First gtkdialog1 updates the environment variables holds the state and value of the widgets. This is how the child process will know what is happening in the GUI called it.
  2. Next the include file is checked. If the gtkdialog1 started with the -i file option gtkdialog1 will ask the subshell to include the file before the execution of command.

    This strange method is needed for the action driven programs, where the subshell have to load the shell functions from the calling script.

  3. At the third step gtkdialog1 starts the command and waits for it to complete. (Commands usually can be run in the background by writing a & as last character, so the subshell will not wait the program to complete.)

6.1.2 Exit dialog

The Exit:Value command exits gtkdialog1 immediately. The Value will be printed to standard output as the value of the variable named EXIT.


Previous: Start and exit, Up: Actions

6.2 Widget manipulation

The <action>Instruction:Name</action> tells the program to perform Instruction on widget with variable name Name. Not every widget is capable to perform every instruction. Instruction can be one of the following:

6.2.1 Closewindow:Name

The command closes (hides) the named window opened by the Launch: command. The program remain active if there are more windows active.

6.2.2 Launch:Name

The command opens (shows) a new window using the environment variable Widget.

6.2.3 Disable:Name

The command disables the given widget if it is enabled. If the widget is disabled when the command is activated, nothing happens.

The disabled widgets are insensitive to user actions, their shapes are indicating they are temporary unavailable.

6.2.4 Enable:Name

The command enables the given widget if it is disabled. If the widget is enabled nothing happens.

6.2.5 Refresh:Name

The command refresh the named widget. If the widget have one or more input actions, they will be called by gtkdialog1.

6.2.6 Save:Name

Some widgets can hold much data. (Currently only the edit widget capable to perform this action.)

The Save: action will save the data found in the named widget to the filename found in <output file> attribute.

6.2.7 Clear:Widget

The command clears the content of the target widget.

6.2.8 RemoveSelected:Widget

The command remove the selected item from the target widget.

6.2.9 Fileselection:Widget

The fileselection widget launch a popup widget where the user can select a file or directory. The return value is the selected file or directory and can be set to fill another widget with the file or directory name and path. If the target widget is an edit widget the file will be opened in the edit widget.

     <vbox>
     	<hbox>
     		<entry>
     			<variable>FILE</variable>
     		</entry>
     		<button>
     			<action fileselection>FILE</action>
     		</button>
     	</hbox>
     </vbox>


Previous: Actions, Up: Top

7 Comments

Comments can be made inside the gtkdialog1 instruction code. The following syntax can be used:

XML/HTML-style comments: <!--the comment goes here-->

C-style comments: /*the comment goes here*/

Shell-style comments: #the comment goes here