This is gtkdialog.info, produced by makeinfo version 4.3 from
gtkdialog.texi.

This manual documents version {No value for `VERSION'} of the Gtkdialog
utility.

   Copyright (C) 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.
   

File: gtkdialog.info,  Node: Top,  Next: Getting Gtkdialog,  Up: (dir)

Gtkdialog User's Manual
***********************

This manual documents version {No value for `VERSION'} of the Gtkdialog
utility.

   Copyright (C) 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.
   
* Menu:

* Getting Gtkdialog::      How to find, download and install the program.
* Introduction::           A brief description of the package.
* Invoking the Program::   How to call the program from various languages.
* Widgets::    		   The elements of dialog boxes.
* Containers::		   Dialog elements grouping widgets together.
* Actions::		   What is happening when something happening.


File: gtkdialog.info,  Node: Getting Gtkdialog,  Next: Introduction,  Prev: Top,  Up: Top

Getting Gtkdialog
*****************

Download
========

   The source of Gtkdialog can be downloaded from Anonymous FTP at URL
`ftp://linux.pte.hu/pub/gtkdialog/'.

How to Install the Program
==========================

   The program can be installed using the standard `./configure',
`make' and `make install' command sequence. Further details can be
found in the `INSTALL' file included.

Copying
=======

   Copyright (C) 2003 Laszlo Pere.

   The gtkdialog 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.


File: gtkdialog.info,  Node: Introduction,  Next: Invoking the Program,  Prev: Getting Gtkdialog,  Up: Top

Introduction
************

   Gtkdialog is a small utility program based on the GTK+ library. The
program 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.


File: gtkdialog.info,  Node: Invoking the Program,  Next: Widgets,  Prev: Introduction,  Up: Top

Invoking the Program
********************

Examples
========

   Our first example program shows how to call the `gtkdialog' 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>'
     
     gtkdialog --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 `gtkdialog' 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
`gtkdialog' 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  $(gtkdialog --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 `gtkdialog' 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 `gtkdialog' 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/gtkdialog -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.


File: gtkdialog.info,  Node: Widgets,  Next: Containers,  Prev: Invoking the Program,  Up: Top

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 (*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.

* Menu:

* Pushbutton::			Pushbutton widgets
* Pre-defined pushbuttons::	Pushbuttons with pixmap and text label
* Entry::			One line text entry widgets
* Checkbox::			Checkbox widgets
* Pixmap::			Static pixmap widgets


File: gtkdialog.info,  Node: Pushbutton,  Next: Pre-defined pushbuttons,  Up: Widgets

Pushbutton
==========

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

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

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

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

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


File: gtkdialog.info,  Node: Pre-defined pushbuttons,  Next: Entry,  Prev: Pushbutton,  Up: Widgets

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>'


File: gtkdialog.info,  Node: Entry,  Next: Checkbox,  Prev: Pre-defined pushbuttons,  Up: Widgets

Entry
=====

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

`<default></default>'
---------------------

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

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

`<action></action>'
-------------------

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


File: gtkdialog.info,  Node: Checkbox,  Next: Pixmap,  Prev: Entry,  Up: Widgets

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.

`<label></label>'
-----------------

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

`<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'.

`<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>

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

`<variable></variable>'
-----------------------

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


File: gtkdialog.info,  Node: Pixmap,  Prev: Checkbox,  Up: Widgets

Pixmap
======

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

`<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>


File: gtkdialog.info,  Node: Containers,  Next: Actions,  Prev: Widgets,  Up: Top

Containers
**********


File: gtkdialog.info,  Node: Actions,  Prev: Containers,  Up: Top

Actions
*******

   When the user changes the state of a widget, gtkdialog 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. Gtkdialog executes the axtions in the
order they found in the dialog description program, so one can write a
complet program as a series of instructions.

* Menu:

* Shell commands::	Actions that starts programs as child processes


File: gtkdialog.info,  Node: Shell commands,  Up: Actions

Shell commands
==============

   If the action of a widget is created with the simple
`<action>COMMAND</action>' directive, gtkdialog 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 gtkdialog 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 gtkdialog started  with
     the `-i FILE' option gtkdialog 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 gtkdialog 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.)



Tag Table:
Node: Top79
Node: Getting Gtkdialog1462
Node: Introduction2689
Node: Invoking the Program3184
Node: Widgets5856
Node: Pushbutton6695
Node: Pre-defined pushbuttons8186
Node: Entry8776
Node: Checkbox9674
Node: Pixmap11316
Node: Containers11937
Node: Actions12045
Node: Shell commands12686

End Tag Table
