\input texinfo   @c -*-texinfo-*-
@include version.texi
@c %**start of header
@setfilename gtkdialog.info
@settitle NAME-OF-MANUAL VERSION
@c %**end of header

@copying
This manual documents version @value{VERSION} of the Gtkdialog utility.

Copyright @copyright{} 2003-2007 Laszlo Pere. 

WARNING: This documentation is very incomplete and has not been updated
since at least 2007 although it is still informative for beginners.

@quotation
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.  
@end quotation
@end copying

@titlepage
@title Gtkdialog User's Manual
@subtitle Incomplete introduction
@c subtitle SUBTITLE-IF-ANY
@c subtitle SECOND-SUBTITLE
@author Laszlo Pere

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@c Published by ...
@end titlepage
                                                                           
@c So the toc is printed in the right place.
@contents
                                                                           
@ifnottex
@node Top
@top Gtkdialog User's Manual
                                                                           
@insertcopying
@end ifnottex
                                                                           
@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.
@end menu


@node Getting Gtkdialog
@chapter Getting Gtkdialog
@section Download 
The source of Gtkdialog can be downloaded from Anonymous FTP at URL
@uref{ftp://linux.pte.hu/pub/gtkdialog/}.

@section How to Install the Program
The program can be installed using the standard @command{./configure},
@command{make} and @command{make install} command sequence. Further
details can be found in the @file{INSTALL} file included.


@section Copying
Copyright @copyright{} 2003-2007 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.

@node Introduction 
@chapter 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.

@node Invoking the Program
@chapter Invoking the Program
@section Examples
Our first example program shows how to call the @command{gtkdialog}
from a BASH script. 

@example
#! /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
@end example

This example uses a very plain way to open a dialog box. We store the
description of the dialog box in the @code{MAIN_DIALOG} environment
variable which is exported to the child processes with the BASH
@code{export} built-in. Then we call the @code{gtkdialog} program with
the @option{--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
@command{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.
@example
#! /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
@end example

In the example script we use the @code{for} built-in to go through the
list @code{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 @code{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.

@example
#! /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>
@end example

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


@node Widgets
@chapter 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 (@pxref{Actions}).

The widgets are grouped together with containers (@pxref{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
* Static label::                Labels containing static text
* 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
* Menus::                       Making menubars, menus and menuitems
* Trees::                       Complex widget for trees
@end menu

@c -----------------------------------------------------------------
@node Static label 
@section Static label
Label is a static text widget created with @code{<text></text>} 
tag. 

The text in a static label, can be set with the
@code{<label>@var{string}</label>} or the 
@code{<input file>@var{filename}</input>} expression.

@c -----------------------------------------------------------------
@node Pushbutton
@section Pushbutton
The pushbutton is a clickable widget defined with the 
@code{<button></button>} tags. 

@subsection @code{<label></label>}
The @code{<label>@var{string}</label>} directive sets the text label of
the pushbutton. If no label and pixmap is given for the button,
gtkdialog will use @var{OK} as default.

@subsection @code{<input file></input>}
When creating buttons, the @command{<input file>@var{filename}</input>}
tag can be used to insert a pixmap into the button. The @var{filename}
must be a pixmap file. Gtkdialog will find this file with the
@command{locate} utility if necessary.

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

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

@subsection @code{<action></action>}
The @code{<action>@var{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 @var{EXIT}, with the label of the activated 
button as value.

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

@subsection @code{<visible></visible>}
The @code{<visible>@var{state}</visible>} specify the initial visibility 
of the button. The @var{state} can be either @code{enabled} or 
@code{disabled}. When a button is disabled, it is shaded and can not be 
activated by mouse or keyboard.

@c -----------------------------------------------------------------
@node Pre-defined pushbuttons
@section 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:

@itemize @bullet
 @item @code{<button ok></button>}
 @item @code{<button cancel></button>}
 @item @code{<button help></button>}
 @item @code{<button yes></button>}
 @item @code{<button no></button>}
@end itemize

@c -----------------------------------------------------------------
@node Entry
@section Entry
The entry widget is a simple text input field, which can be used to
get a string from the user. 

@subsection @code{<default></default>}
The @code{<default>@var{string}</default>} directive sets the
default content of the entry.

@subsection @code{<visible></visible>}
The @code{<visible>@var{visibility}</visible>} sets the initial 
state of the entry widget. The @var{visibility} can be @code{enabled},
which means the entry can be used, @code{disabled}, which means
the content of the entry can not be altered or @code{password}.

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

@subsection @code{<action></action>}
The entry widgets are activating actions after their contents are
changed. 

@c -----------------------------------------------------------------
@node Checkbox
@section 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
@code{<checkbox></checkbox>} directive.

@subsection @code{<label></label>}
The label is the text shown beside the check mark. Every checkbox
should have a label.

@subsection @code{<default></default>}
The initial state of the checkbox can be set by the 
@code{<default>@var{state}</default>} directive, where the @var{state}
can be either @code{yes} or @code{no}.

@subsection @code{<action></action>}
The @code{<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 
@command{if true} and @command{if false} prefixes as in the next 
example:

@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>
@end example

@subsection @code{<visible></visible>}
The @code{<visible>@var{state}</visible>} specify the initial
visibility of the checkbox. The @var{state} can be either
@code{enabled} or @code{disabled}. When a checkbox is disabled, it is
shaded and its state can not be altered anyway.

@subsection @code{<variable></variable>}
The value of a checkbox can be @code{true} or @code{false} and depends 
only on its state.

@c -----------------------------------------------------------------
@node Pixmap
@section Pixmap
The @code{<pixmap></pixmap>} defines a static pixmap widget. 

@subsection @code{<input file></input>}

The widget must have an input file defined with the 
@code{<input file>@var{filename}</input>} tags. The @var{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 @code{locate} utility program) if the file
is unreadable.  

The next example defines a static pixmap:

@example
<pixmap>
  <input file>help.png</input>
</pixmap>
@end example

@c -----------------------------------------------------------------
@node Menus 
@section Menubar 
The @code{<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 @code{<menu></menu>} tag, and inside the menu
must be at least one menu item created by the
@code{<menuitem></menuitem>} tag.

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

@example
<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>
@end example

@c -----------------------------------------------------------------
@node Trees
@section The tree
OK, it is not complete, but the next example seems to be just fine.

@example
<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>
@end example

@c -----------------------------------------------------------------
@node Containers
@chapter Containers

@c -----------------------------------------------------------------
@node Actions
@chapter 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
* Start and exit::	Actions that starts programs and exits dialogs
* Widget manipulation:: Actions affect widgets
@end menu

@c -----------------------------------------------------------------
@node Start and exit
@section Start and exit

@subsection Start programs

If the action of a widget is created with the simple 
@code{<action>@var{command}</action>} directive, gtkdialog will execute
it in a subshell. That means it will start up @code{/bin/sh} to handle 
the operation. Here is how the subshell operation works:
@enumerate
 @item 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.
 
 @item Next the include file is checked. If the gtkdialog started
 with the @option{-i @var{file}} option gtkdialog will ask the
 subshell to include the @var{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.

 @item 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 @code{&} as last character, so the subshell will not wait 
 the program to complete.)
@end enumerate

@subsection Exit dialog

The @code{Exit:@var{Value}} command exits @command{gtkdialog}
immediately. The @var{Value} will be printed to standard output as the
value of the variable named @var{EXIT}.

@c -----------------------------------------------------------------
@node Widget manipulation
@section Widget manipulation

@subsection @code{Closewindow:@var{Name}}
The command closes the named window opened by the @code{Launch:}
command. The program remain active if there are more windows active.

@subsection @code{Launch:@var{Name}}
The command opens a new window using the environment variable
@code{Widget}.

@subsection @code{Disable:@var{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.

@subsection @code{Enable:@var{Name}}
The command enables the given widget if it is diabled. If the widget
is enabled nothing happens.

@subsection @code{Refresh:@var{Name}}
The command refresh the named widget. If the widget have one or more
input actions, they will be called by @command{gtkdialog}.

@subsection @code{Save:@var{Name}}
Some widgets can hold much data. (Currently only the edit widget
capable to perform this action.)

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

FIXME: This function is not working now, need to be fixed.

@subsection @code{Fileselect:@var{Widget}}
@subsection @code{Clear:@var{Widget}}
@subsection @code{RemoveSelected:@var{Widget}}


@bye



