# man pages for gnocl commands
# txt2html.tcl converts this file to html-pages
#
# Copyright (c) 2001 - 2002 P.G. Baum
#
# TODO: .CMDOPTION:
#       .DEFINE qqq llllll
#
.HEADING:   Miscellaneous

.NAME:      info
.SHORTDESCR: Return <b>gnocl</b> related information.

.NAME:      bind
.SHORTDESCR: Arrange for X events to invoke Tcl scripts.
.SYNOPSIS:  bind widget-ID signal script
.DESCRIPTION: <b>script</b> is evaluated at global scope whenever
               widget or canvas item <b>widget-ID</b> receives signal 
               <b>signal</b>.
               If <b>script</b> is the empty string, the binding is deleted.
               <br>Valid signals are: 
               <b>enter</b>, <b>leave</b>, <b>motion</b>, 
               <b>button</b> (synonym for buttonPress), <b>buttonPress</b>, 
               <b>buttonRelease</b>, 
               <b>key</b> (synonym for keyPress), <b>keyPress</b>, 
               or <b>keyRelease</b>.
               <br>For <b>button</b>, <b>buttonPress</b> and 
               <b>buttonRelease</b> <b>signal</b> can be a list 
               "signal number", where <b>number</b> is an integer 
               describing the button number.
               <br>For <b>key</b>, <b>keyPress</b> and <b>keyRelease</b>
               <b>signal</b> can be a list "signal detail". If detail
               starts with a "#" the following characters must be the
               name of a keysym symbol as defined in gdkkeysyms.h without
               the preceeding "GDK_" otherwise <b>detail</b> is the ASCII 
               representation of a key. Example:
               <br>"key 1" binds on a key, that produces the ASCII value "1"
               be it on the numpad or on the keyboard.
               <br>"key #1" binds on the key with the symbol "1" that is
               on the "1" on the keyboard.
               <br>"key #KP_1" binds on the key with the symbol "KP_1" that is
               on the "1" on the numpad if Num is on.
               <br><br>Before evaluating every percent (%) and its following
               character is substituted in <b>script</b>: 
               <table>
               <tr><th>%% </th><td>by %</td></tr>
               <tr><th>%A </th><td>by the ASCII representation of the key 
                     that was pressed or released</td></tr> 
               <tr><th>%b </th><td>by the number  of  the  button  that  
                     was  pressed   or released</td></tr> 
               <tr><th>%k </th><td>by the keysym as integer of the key 
                     that was pressed or released</td></tr> 
               <tr><th>%K </th><td>by the keysym as symbol of the key 
                     that was pressed or released</td></tr> 
               <tr><th>%s </th><td>by the state of the modifier keys as 
                     bitfield</td></tr>
               <tr><th>%x </th><td>by the x coordinate of the event</td></tr> 
               <tr><th>%y </th><td>by the y coordinate of the event</td></tr>
               </table>
               <br><br>

.NAME:      bonobo
.SHORTDESCR: Provide functionality for remote activation (not yet very usefull)
.SYNOPSIS:  bonobo command VAROPTS
.DESCRIPTION: This command is in its infancy and disabled in the Makefile
               by default.
               <b>command</b> is one of listServices, 
               activateService, activateRepoID, getObject.

.NAME:      dnd
.SHORTDESCR: Provide drag and drop functionality.
.SYNOPSIS:  dnd cmd widget-ID list-of-targets command VAROPTS
.DESCRIPTION: <b>cmd</b> can either be <b>setDestination</b> or 
               <b>setSource</b>. <b>list-of-targets</b> are the targets
               accepted by the destination or provided by the source
               (example: 
               "STRING text/plain text/uri-list application/x-color").
               <b>command</b> is a string
               which is evaluated when data is received (for setDestination)
               or data should provied (for setSource). 
               <br><br>Before evaluating every percent (%) and its following
               character is substituted in <b>command</b>: 
               <table>
               <tr><th>%d </th><td>by the dropped data 
                     (only for setDestination)</td></tr>
               <tr><th>%l </th><td>by the length of the data 
                     (only for setDestination)</td></tr>
               <tr><th>%t </th><td>by the time</td></tr>
               <tr><th>%T </th><td>by the type of the data</td></tr>
               <tr><th>%w </th><td>by the widget-ID</td></tr>
               <tr><th>%x </th><td>by the x coordinate 
                     (only for setDestination)</td></tr>
               <tr><th>%y </th><td>by the y coordinate 
                     (only for setDestination)</td></tr>
               </table>
               <br>If <b>command</b> for setDestination returns "delete"
               the source is signaled to delete the data (for move
               operations).
               <br>For setSource <b>command</b> must return the data to
               be dragged.
               <br>Valid options are:
               <br><b>-actions</b>: one of default, copy, move, link, private
               <br><b>-buttons</b>: list of button numbers which initiate
                  the drag (only for setSource).

.NAME:      mainLoop
.SHORTDESCR: Enter gtk main loop.
.SYNOPSIS:  mainLoop VAROPTS
.OPTIONS:
            -timeout; integer; 500
            The intervall in millisecond in which the tcl event loop
            is called. If the value is 0 the tcl event loop is
            never called.

.DESCRIPTION: <b>mainLoop</b> never returns. It enters the gtk main
            loop and calls in regular intervalls the tcl event loop.

.NAME:      update
.SHORTDESCR: Process pending gtk events.
.DESCRIPTION: Returns the number of gtk events processed

.HEADING:   Widgets

.NAME:      about
.SHORTDESCR: Create the standard GNOME about dialog 
.SYNOPSIS:  about VAROPTS
.OPTIONS:
            -title; string; ""
                  Title of the dialog box

            -version; string; ""
                  Version of the software
            
            -authors; list of strings; ""
                  Authors of the software. This option is required.
            
            -comments; string; ""
                  Additional comments
            
            -logo; string; ""
                  Logo of the software

.NAME:         app
.SHORTDESCR:   Create and manipulate a GNOME top level container
.SYNOPSIS:   app VAROPTS
.OPTIONS:      
            -title; string; ""
                  Title of top window (name of the application)
            
            -contents; string; ""
                  ID of a previously created widget, which is displayed in
                  the content area of <b>app</b>
            
            -menubar; string; ""
                  ID of a previously created <a href="menubar.html">menubar</a>
            
            -statusbar; string; ""
                  ID of a previously created 
                  <a href="statusbar.html">statusbar</a>
            
            -toolbar; string; ""
                  ID of a previously created 
                  <a href="toolbar.html">toolbar</a>

            -resizable; boolean; true

            -width; integer; -1
               Default width of window.

            -height; integer; -1
               Default height of window.
            
.COMMANDS:
            message txt
                  show <b>txt</b> as message
                  
            flash txt
                  show <b>txt</b> as flash message

            warning txt
                  show <b>txt</b> as warning message

            error txt
                  show <b>txt</b> as erro message

            progress val
                  show progressbar with <b>val</b> percent done 
                  (0 &lt;= <b>val</b> &lt;= 100)

            addToolbar toolbar-ID VAROPTS
                  Adds a toolbar to the application.
                  <b>toolbar-ID</b> is the ID of a toolbar created
                  by the <a href="toolbar.html">toolbar</a> command.
                  <br>Valid options are:
                  <br>-name, string 
                  <br>-behavior, list of one or more of normal, exclusive, 
                        neverFloating, neverVertical, neverHorizontal, locked
                  <br>-placement, one of top, right, bottom, left, floating
                  <br>-bandNum, integer
                  <br>-bandPos, integer
                  <br>-offset, integer

.NAME:      appBar
.SHORTDESCR: Create and manipulate an application bar
.SYNOPSIS:  appBar VAROPTS
.OPTIONS:      
            -hasStatus; boolean; true
               Determines whether the widget has a status bar 

            -hasProgress; boolean; true
               Determines whether the widget has a progress bar 

            -interactivity; never, user, or always; user

.COMMANDS:
            push text

            pop 

            clear


.NAME:       button
.SHORTDESCR: Create and manipulate a button widget
.SYNOPSIS:   button VAROPTS
.OPTIONS:
            -text; <a href="percentstring.html">percent string</a>; ""
                  Text or icon of the button

            -command; string; ""
                  Tcl command which is executed if the button is pressed 
            
            -tooltip; string; ""
                  Message that appear next to this widget when the mouse 
                  pointer is held over it for a short amount of time.

            -sensitive; boolean; 1
                  Whether or not the item is sensitve to user input.

.DESCRIPTION: A button widget executes a command on mouse click.

.COMMANDS:
            invoke
            Invoke  the  Tcl command associated with the button, if there 
            is one. This command is ignored if the button's state is not 
            sensitve.

.NAME:       box
.SHORTDESCR: Create and manipulate a box (frame) widget 
.SYNOPSIS:   box VAROPTS
.OPTIONS:
            -orientation; horizontal, vertical; horizontal
                  orientation of the child widgets
            
            -homogeneous; boolean; true
                  Whether or not all children of box are given equal space 
                  in the box

            -spacing; integer; 0
                  how many pixel beween the children
            
            -buttonType; boolean; false
                  Whether box is a button box.
            
            -children; list, ""
                  list of widget ids
            
            -expand; boolean; true
                  Whether the children is to be given extra space allocated 
                  to box. The extra space will be divided evenly between all 
                  children of box
            
            -fill; boolean; true
                  Whether space given to the children by the expand option is 
                  actually allocated to the children, rather than just padding
                  them. This parameter has no effect if <b>expand</b> is set 
                  to <b>false</b>. If <b>horizontal</b> is <b>true</b>, 
                  this effects only the width,
                  else it effects only the height of the children.
            
            -label; string; ""
                  label of the frame
            
            -shadow; none, in, out, etchedIn, etchedOut; none
                  type of shadow of the frame
            
            -xAlign; double (0 &lt;= xAlign &lt;= 1); 0
                  alignement of label

            -layout; default, spread, edge, start, end; default
                  Layout of box, only valid if the box is a button box.
            
.DESCRIPTION:  The gnocl box widget is a combination of the gtk box 
               (or button box) and the gtk frame. If necessary gtk
               alignment widgets are used when adding children.

.COMMANDS:
            add widgetList VAROPTS
            Add widgets to the box. Valid options are <b>-homogeneous</b>, 
            <b>-spacing</b>, <b>-expand</b>, <b>-fill</b>, <b>-scale</b>
            and </align>.

            addBegin widgetList VAROPTS
            Synonym for <b>add</b>.

            addEnd widgetList VAROPTS
            Same as <b>add</b> but adds widgets at the end.

.NAME:      canvas
.SHORTDESCR: Create and manipulate a widget which is a generic engine for structured graphics
.SYNOPSIS:  canvas VAROPTS
.OPTIONS:
            -heigth; integer; 500
                  height of canvas
            
            -width; integer; 500
                  width of canvas
            
            -antialiased; boolean; true
                  Determines if the antialiased version of the canvas 
                  widget should be used. It seems, that only this version 
                  can rotate items.

.DESCRIPTION:
            Canvas widgets implement structured graphics. A canvas
            displays any number of items, which may be 
            rectangles, circles, lines, and text. Items may be manipulated 
            (e.g. moved or re-colored) and commands may be
            associated with items with the <a href="bind.html">bind</a>
            command. For example, a particular command may be associated 
            with the &lt;button&gt;-event so that the command is invoked 
            whenever 
            a button is pressed with the mouse cursor over an item. This
            means that items in a canvas can have behaviors defined by
            the Tcl scripts bound to them.

.COMMANDS:
            create type list-of-coordinates VAROPTS
            Create a new item. Returns an item identifier. 
            Valid types are <b>line</b>, <b>rectangle</b>, <b>ellipse</b>, 
            <b>text</b>, and <b>widget</b>.
            Valid options are dependent of the type. 

            delete id
            delete item <tt>id</tt>
            <br><tt>delete all</tt> deletes all items. In future versions the
            complete support of tags is planned (see Tk).

            itemHide id
            hide item <tt>id</tt>

            itemShow id
            show item <tt>id</tt>

            itemConfigure VAROPTS
            configure item <tt>id</tt>. Valid options are dependent of type 
            of item

            coords
            not yet implemented

            affine id list-of-coordinates 
            make affine transformation of id. Length of list-of-coordinates 
            must be 6· The new coordinates are calculated by
            <pre>
               x_new = af[0] * x_old + af[2] * y_old + af[4];
               y_new = af[1] * x_old + af[3] * y_old + af[5];
            </pre>

            scale id list-of-coordinates 
            Scales id. Length of list-of-coordinates must
            be 3 (center point and scale) or 4 (center point, x scale, and 
            y scale).

            move id list-of-coordinates 
            Moves id. Length of list-of-coordinates must
            be 2 (delta x and delta y)· 

            rotate id list-of-coordinates 
            Rotates id. Length of list-of-coordinates must
            be 3 (center point and angle)· 

            windowToWorld list-of-coordinates 
            Converts window coordinates to world coordinates.

            worldToWindow list-of-coordinates
            Converts world coordinates to window coordinates.

            findItemAt x y 
            Returns id of item at the world coordinates x and y.

            getBounds id 
            Returns the bounds (x1, y1, x2, y2) of id in world coordinates.

.NAME:      clist
.SHORTDESCR: Create and manipulate a clist widget.
.SYNOPSIS:  clist VAROPTS
.OPTIONS:
            -columns; integer; 1
               Number of columns

            -selectionMode; single, browse, multiple, or extended; ?
               Determines whether one or more rows can be selected
               at a time. <b>single</b> means only one row can
               be selected, <b>browse</b> means exactly one row can
               be selected, <b>multiple</b> <b>extended</b> ???

            -shadow; none, in, out, etchedIn, etchedOut; none
                  Type of shadow of the list.

            -children; list; ""
               A list of rows each member containing a list
               of column entries.
               
            -titles; list; ""
               List of strings which are used as titles for the columns.

            -justifications; list of left, right, center, fill; center
               Justification for each column.

            -titlesShow; boolean; true
               Determines whether the titles are shown.

            -columnClicked; string; ""
               Command to be executed, whenever a title of a column is clicked.
               The column titles are only active if <b>columnClicked</b> is
               not "".
               <br><br>Before evaluating every percent (%) and its following
               character is substituted in <b>selectionChanged</b>: 
               <table>
               <tr><th>%%</th><td>by %</td></tr>,
               <tr><th>%c</th><td>by the number of the column 
                     selected</td></tr>
               <tr><th>%w</th></td>by the widget-ID</td></tr>
               </table>

            -selectionChanged; string; ""
               Command to be executed, whenever the selection changes.
               <br><br>Before evaluating every percent (%) and its following
               character is substituted in <b>selectionChanged</b>: 
               <table>
               <tr><th>%%</th><td> by %,</td></tr>
               <tr><th>%b</th><td> by the number of the button that 
                     was pressed or released</td></tr>
               <tr><th>%c</th><td> by the number of the column 
                     selected</td></tr>
               <tr><th>%r</th><td> by the number of the row selected</td></tr>
               <tr><th>%s</th><td> by 1 if the row is selected and 
                     by 0 if the row is not selected</td></tr>
               <tr><th>%t</th><td> by the event type</td></tr>
               <tr><th>%w</th><td> by the widget-ID</td></tr>
               </table>

            -scrollbar; always, never, automatic; automatic
               What type of scrollbar the list should have. This can
               also be a list of two values where the first value
               is the type of the horizontal scrollbar and the
               second value is the type of the vertical scrollbar.
               Also possible is a boolean value understood by tcl
               where <b>true</b> is a synonym for <b>always</b> and
               <b>false</b> is a synonym for <b>never</b>.

.COMMANDS:
            getSelection
               Returns list of selected rows.

            getCellText row column
               Returns text of one cell.

            select list-of-rows VAROPTS
               Select rows.

            sort column VAROPTS
               Sort all rows based on text in column <b>column</b>.
               Valid options are
               <br>-reverse boolean
               <br>-command func

            columnConfigure column VAROPTS
               Valid options are: 
               <br>-titleActive boolean
               <br>-title string
               <br>-justification string
               <br>-visible boolean
               <br>-resizeable boolean
               <br>-autoResize boolean
               <br>-width integer
               <br>-minWidth integer
               <br>-maxWidth integer

            add list-of-rows 
            Add new rows after all existing rows. 

            addEnd widgetList 
            Synonym for <b>add</b>.

            addBegin widgetList 
            Same as <b>add</b> but adds rows before all existing rows.


.NAME:      colorPicker
.SHORTDESCR: Create and manipulate a widget for selecting colors.
.SYNOPSIS:  colorPicker VAROPTS
.OPTIONS:   
            -title; string; ""
               Title of the color selection dialog.

            -variable; string; ""
               Name of a (global) variable which is changed if the
               color is changed.

            -command; string; ""
               Tcl command which is executed if the color is changed.
               <br><br>Before evaluating every percent (%) and its following
               character is substituted in <b>command</b>: 
               <table>
               <tr><th>%%</th><td> by %,</td></tr>
               <tr><th>%a</th><td> by the alpha value of the 
                     selected color</td></tr>
               <tr><th>%b</th><td> by the blue value of the 
                     selected color</td></tr>
               <tr><th>%g</th><td> by the green value of the 
                     selected color</td></tr>
               <tr><th>%r</th><td> by the red value of the 
                     selected color</td></tr>
               <tr><th>%w</th><td> by the widget-ID</td></tr>
               </table>

            -sensitive; boolean; 1
                  Wheather or not the item is sensitve to user input.

.COMMANDS:
            getColor
               Returns a list of red green blue and alpha value of 
               the current color.

            setColor col
               Sets the color. <b>col</b> can be a textual description
               like "lightblue", a list of a textual description and
               a alpha value, a list of rgb values or a list of rgba
               values. If alpha is not set, it defaults to 65535.

.NAME:      checkButton
.SHORTDESCR: Create and manipulate a checkbutton
.SYNOPSIS:  checkButton VAROPTS
.OPTIONS:   
            -text; string; ""
                  text or icon of the button
            
            -command; string; ""
               Tcl command which is executed if the button is pressed 
               <br><br>Before evaluating every percent (%) and its following
               character is substituted in <b>command</b>: 
               <table>
               <tr><th>%%</th><td> by %,</th></tr>
               <tr><th>%v</th><td> by value <b>onValue</b> or 
                     <b>offValue</b> dependent on the state of the 
                     button,</th></tr>
               <tr><th>%w</th><td> by the widget-ID</th></tr>
               </table>
            
            -variable; string; ""
                  Name of a (global) variable which is changed if the state 
                  of the button changes. If the variable does not exist, it
                  is created with a value of <b>offValue</b>. If it does
                  exist and has the same value than <b>onValue</b>, the
                  checkbutton is selected. If the variable is set 
                  externaly (e.g. via the set command) 
                  to <b>onValue</b> or <b>offValue</b>, <b>command</b>
                  is called and the state of the widget changed.
            
            -onValue; string; 1
                  value to store in the button's associated variable 
                  whenever this button is selected
            
            -offValue; string; 0
                  value to store in the button's associated variable 
                  whenever this button is not selected
            
            -indicatorOn; boolean; true
                  Determines whether or not the toggle button is drawn 
                  on screen
            
            -tooltip; string; ""
                  Message that appear next to this widget when the mouse 
                  pointer is held over it for a short amount of time.
            
            -sensitive; boolean; 1
                  Wheather or not the item is sensitve to user input.

.DESCRIPTION:  A checkbutton is like a <a href="button.html">button</a>, 
               but it has two states: on and off.

.COMMANDS:
            getValue
                  Returns value of <b>onValue</b> or <b>offValue</b> 
                  depending on the state of the widget.
            
            setValue value
                  Sets the state of the widget, changes <b>variable</b>
                  and calls <b>command</b>. <b>value</b> must be either
                  value of <b>onValue</b> or <b>offValue</b>.

            invoke
            Does just what would have happened if the user invoked the 
            checkbutton with the mouse:  toggle the  selection state of 
            the button and invoke the Tcl command associated with the 
            checkbutton, if there is one. This command is ignored if the
            checkbutton's state is not sensitve.



.NAME:      combo
.SHORTDESCR: Create and manipulate an entry widget with a drop down list
.SYNOPSIS:  combo VAROPTS
.OPTIONS:   
            -variable; string; ""
                  name of a (global) variable which is changed whenever 
                  the entry is changed 

            -strings; list of strings; ""
                  Members of the drop down list
            
            -mustMatch; boolean; false
                  Whether or not the value must match a member of the 
                  drop down list
            
            -okIfEmpty; boolean; false
                  Whether or not the value can be the empty string
            
            -caseSensitive; boolean; false
                  Whether or not the matching is case sensitive
            
            -editable; boolean; true
                  Whether  or not the the entry is editable
            
            -maxLength; integer; -1
                  maximum length of entry value (<b>-1</b> means not limited)
            
            -tooltip; string; ""
                  Message that appear next to this widget when the mouse 
                  pointer is held over it for a short amount of time.
            
.COMMANDS:
            getValue
                  Returns the contents of the entry.
            
            setValue text
                  Sets the contents of the entry.
            

.NAME:      dialog
.SHORTDESCR: Create and manipulate a gnome dialog, message box respectively
.SYNOPSIS:  dialog title button-list VAROPTS
.OPTIONS:
            -child; string; ""
                  Widget ID of the child widget

            -text; string; ""
                  Text which should appear in the dialog

            -parent; string; ""
                  Widget ID of the parent widget

            -default; integer; 0
                  Number of the default button

            -type; none, info, warning, error, question, or generic; ?
                  Type of dialog

            -modal; boolean; false
                  Determines whether the dialog should be modal.

.DESCRIPTION:
            <b>button-list</b> must be a list of widget IDs of buttons.
            Either <b>text</b> or <b>child</b> must be specified.

.NAME:      entry
.SHORTDESCR: Create and manipulate a widget which is a combination of the gtk entry and the gnome file, number, pixmap, and icon entries
.SYNOPSIS:  entry VAROPTS
.OPTIONS:   
            -variable; string; ""
                  name of a (global) variable which is changed whenever 
                  the entry is changed 

            -editable; boolean; true
                  Whether  or not the the entry is editable
            
            -maxLength; integer; -1
                  maximum length of entry value (<b>-1</b> means not limited)
            
            -tooltip; string; ""
                  Message that appear next to this widget when the mouse 
                  pointer is held over it for a short amount of time.
            
            -type; default, gnome, pixmap, icon, file, or number; default
                  Type of entry widget
            
            -history; list of strings; ""
                  Members of the history 
                  (not for type <b>default</b>)
            
            -historyId; string; ""

.COMMANDS:
            getValue
                  Returns the contents of the entry.
            
            setValue text
                  Sets the contents of the entry.
            
            appendHistory text
                  Appends <b>text</b> to the history
                  (not for type <b>default</b>).
            
            prependHistory text
                  Prepends <b>text</b> to the history
                  (not for type <b>default</b>).

            saveHistory
                  If <b>historyId</b> is not equal "", saves the history
                  else does nothing
                  (not for type <b>default</b>).

            loadHistory
                  If <b>historyId</b> is not equal "", loads the history
                  else does nothing
                  (not for type <b>default</b>).
            
.NAME:      eventBox
.SHORTDESCR: Create and manipulate a helper widget for widgets which have no own window
.SYNOPSIS:  eventBox VAROPTS
.OPTIONS:   
            -child; widget-id; ""
                  ID of the child widget.

.DESCRIPTION: Some widget (for example lables) do not have an own
              window. If they should be the target or the source of
              <a href="dnd.html">drag and drop</a> actions, they have 
              to be packed in an eventBox
              and this box made target or sorce of the drag or drop.

.NAME:      fileSelection
.SHORTDESCR:   Create a file selection dialog

.NAME:      fontPicker
.SHORTDESCR: Create and manipulate a widget for selecting fonts.
.SYNOPSIS:  fontPicker VAROPTS
.OPTIONS:   
            -title; string; ""
               Title of the font selection dialog.

            -variable; string; ""
               Name of a (global) variable which is changed if the
               font is changed.

            -command; string; ""
               Tcl command which is executed if the font is changed.
               <br><br>Before evaluating every percent (%) and its following
               character is substituted in <b>command</b>: 
               <table>
               <tr><th>%%</th><td> by %,</td></tr>
               <tr><th>%f</th><td> by the name of the selected font</td></tr>
               <tr><th>%w</th><td> by the widget-ID</td></tr>
               </table>

            -sensitive; boolean; 1
                  Wheather or not the item is sensitve to user input.

.COMMANDS:
            getFont
               Returns the selected font.

            setFont font
               Sets the font. 

.NAME:      frame
.SHORTDESCR: alias for box

.NAME:         label
.SHORTDESCR:   Create and manipulate a label widget
.SYNOPSIS:     label VAROPTS
.OPTIONS:      
            -text; string; ""
                  Text of label
            
            -justify; left, right, center, fill; center
                  Justification of multiple lines in the label to each other.
            
            -lineWrap; boolean; true
                  whether or not the text in the label shall wrap.

            -xAlign; double (0 &lt;= xAlign &lt;= 1); 0.5
                  Alignement of label in x direction.

            -yAlign; double (0 &lt;= xAlign &lt;= 1); 0.5
                  Alignement of label in y direction.

            -xPad; int; 0
                  Padding in x direction.

            -yPad; int; 0
                  Padding in y direction.

.NAME:      menu
.SHORTDESCR: Create and manipulate a menu
.SYNOPSIS:  menu VAROPTS
.OPTIONS:
            -title; string; ""
                  Title of menu.
            
            -children; list, ""
                  list of widget ids
            
            -tearoff; boolean; true
                  whether the menu can be torn off

.COMMANDS:
            add widgetList 
            add widgets to the menu. 

            addEnd widgetList 
            synonym for <b>add</b>

            addBegin widgetList 
            same as <b>add</b> but adds widgets before existing childs

            popup

            popdown

.NAME:      menubar
.SHORTDESCR: Create and manipulate a menubar
.SYNOPSIS:  menubar VAROPTS
.OPTIONS:
            -shadow; none, in, out, etchedIn, etchedOut; none
                  type of shadow of the menubar
            
            -children; list, ""
                  list of widget ids
            
.COMMANDS:
            add widgetList VAROPTS
            add widgets to the box. Valid options are <b>-homogeneous</b>, 
            <b>-spacing</b>, <b>-expand</b>, and <b>-fill</b>

            addBegin widgetList VAROPTS
            synonym for <b>add</b>

            addEnd widgetList VAROPTS
            same as <b>add</b> but adds widgets before existing childs

.NAME:      menuItem
.SHORTDESCR: Create and manipulate a menu item
.SYNOPSIS:  menuItem type VAROPTS
.DESCRIPTION: Depending on <b>type</b> a menu item is created. Type
            must be one of <b>label</b>, <b>checkButton</b>, or
            <b>separator</b>.

.OPTIONS:
            -text; <a href="percentstring.html">percent string</a>; ""
                  (For label and checkButton)

            -submenu; string; ""
                  Widget ID of a <a href="menu.html">menu</a>. 
                  <br>(For label)

            -command; string; ""
                  Tcl command which is executed if the item is selected 
                  <br><br>Before evaluating every percent (%) and its 
                  following character is substituted in <b>command</b>: 
                  <table>
                  <tr><th>%%</th><td> by %,</th></tr>
                  <tr><th>%v</th><td> by value <b>onValue</b> or 
                        <b>offValue</b> dependent on the state of the 
                        button,</th></tr>
                  <tr><th>%w</th><td> by the widget-ID</th></tr>
                  </table>
                  <br>(For label and checkButton)

            -accelerator; string; ""
                  (For label and checkButton)

            <br>-icon; <a href="percentstring.html">percent string</a>; ""
                  Icon of the button. If this parameter is given, even
                  if it is the empty string, gtk_pixmap_menu_item is used,
                  otherwise the normal gtk_menu_item.
                  <br>(For label)

            -variable; string; ""
                  Name of a (global) variable which is changed if the state 
                  of the button changes. If the variable does not exist, it
                  is created with a value of <b>offValue</b>. If it does
                  exist and has the same value than <b>onValue</b>, the
                  checkbutton is selected. If the variable is set 
                  externaly (e.g. via the set command) 
                  to <b>onValue</b> or <b>offValue</b>, <b>command</b>
                  is called and the state of the widget changed.
                  <br>(For checkButton)
            
            -onValue; string; 1
                  value to store in the item's associated variable 
                  whenever this item is selected
                  <br>(For checkButton)
            
            -offValue; string; 0
                  value to store in the item's associated variable 
                  whenever this item is not selected
                  <br>(For checkButton)

            -tooltip; string; ""
                  Text which is displayed in the 
                  <a href="appbar.html">appBar</a> of application if the
                  item is activated.
            
.COMMANDS:
            getValue
                  Returns value of <b>onValue</b> or <b>offValue</b> 
                  depending on the state of the widget.
                  <br>(For checkButton)
            
            setValue value
                  Sets the state of the widget, changes <b>variable</b>
                  and executes <b>command</b>. <b>value</b> must be either
                  value of <b>onValue</b> or <b>offValue</b>.
                  <br>(For checkButton)

            invoke
            Does just what would have happened if the user invoked the 
            menuItem with the mouse: for checkButton: toggle the selection 
            state of the button and invoke the Tcl command associated with the 
            checkbutton, if there is one; for label: invoke the Tcl
            command associated with the label. This command is ignored if the
            checkbutton's state is not sensitve.
            <br>(For checkButton and label)


.NAME:      notebook
.SHORTDESCR: Create and manipulate a notebook widget
.SYNOPSIS:  notebook VAROPTS
.OPTIONS:
            -children; list of strings; ""
                  List of widget IDs.

            -popup; boolean; false

            -tabPosition; left, right, top, or bottom; 
                  
            -switchPageCmd; string; ""
                  Tcl string to be executed, when a page change occurs.

.COMMANDS:
            add widget-list VAROPTS
            Synonym for <b>addBegin</b>
            
            addBegin widget-list VAROPTS
            
            addEnd widget-list VAROPTS
         
            currentPage
            
            nextPage

.NAME:       optionMenu
.SHORTDESCR: Create and manipulate a optionMenu widget
.SYNOPSIS:   optionMenu VAROPTS
.OPTIONS:
            -command; string; ""
                  Tcl command which is executed if the selected item
                  changes. That means that it is also executed if
                  the widget changes because of a change of a via the
                  <b>-variable</b> option associated variable.
                  <br><br>Before evaluating every percent (%) and its 
                  following character is substituted in <b>command</b>: 
                  <table>
                  <tr><th>%%</th><td> by %,</th></tr>
                  <tr><th>%v</th><td> by value of the selected option</th></tr>
                  <tr><th>%w</th><td> by the widget-ID</th></tr>
                  </table>
            
            -variable; string; ""
                  Name of a (global) variable which is changed if the state 
                  of the item changes. If the variable does not exist, it
                  is created and, if options are added via the <b>add</b>
                  command, set to the value of the first option. It the
                  variable does exist, the option with the same value as
                  the variable is selected. If the variable is set
                  externaly (e.g. via the set command),
                  the state of the item is changed and command called, if
                  it exists.

            -menu; widget-id; ""
                  Widget Id of a <a href="menu.html">menu</a> widget

            -tooltip; string; ""
                  Message that appear next to this widget when the mouse 
                  pointer is held over it for a short amount of time.

            -sensitive; boolean; 1
                  Wheather or not the item is sensitve to user input.

.DESCRIPTION: An optionMenu is used to select an option among different
               alternatives similar to 
               <a href="radiobutton.html">radioButtons</a>. The different
               alternatives are presented via a 
               <a href="menu.html">menu</a> widget. This can either
               be constructed and added via the <b>-menu</b> option,
               or (prefered method) added via the <b>add</b> command.

.COMMANDS:
            add txt ?-value val?
            Add an option with text <b>txt</b>. If option <b>-value</b>
            is given, the status of variable is changed.

            getValue
            Get value of selected item.

            setValue val
            Sets the option with the value <b>val</b>, changes <b>variable</b>
            and executes <b>command</b>.

.NAME:      paned
.SHORTDESCR: Create and manipulate a paned widget
.SYNOPSIS:  paned VAROPTS

.NAME:      plug
.SHORTDESCR: Create and manipulate a plug widget
.SYNOPSIS:  plug XID VAROPTS
.DESCRIPTION: A plug widget can be used to embed the window with the
            XID <b>XID</b> of another
            process. It works best with a <a href="socket.html">socket</a>
            widget on the other side.

.OPTIONS:   
            -child; widget-id; ""
                  ID of the child widget.

.NAME:      radioButton
.SHORTDESCR: Create and manipulate a radio button
.SYNOPSIS:  radioButton VAROPTS
.OPTIONS:   
            -variable; string; ""
                  (Required option)
                  Name of a (global) variable which is changed when the state 
                  of the button changes. All radio buttons with the
                  same variable are in one group. If the variable does
                  not exist, it is created and set to the value of the
                  first button in the group. If the variable does exist
                  and it's value corresponse to the value of a button in
                  this group, this button is selected. If the value of
                  variable is set externaly (e.g. via the set),
                  the corresponding button in the group is selected and
                  its command executed.

            -value; string; ""
                  (Required option)
                  Value to store in the button's associated variable 
                  whenever this button is selected.
            
            -text; string; ""
                  text or icon of the button
            
            -command; string; ""
                  Tcl command which is executed when the button is pressed.
            
            -indicatorOn; boolean; true
                  Determines whether or not the toggle button is drawn on 
                  screen.
            
            -tooltip; string; ""
                  Message that appear next to this widget when the mouse 
                  pointer is held over it for a short amount of time.

            -sensitive; boolean; 1
                  Wheather or not the item is sensitve to user input.

.COMMANDS:
               invoke
               Does just what would have happened if the user invoked 
               the radiobutton with the mouse: selects the  button  and 
               invokes its associated Tcl command, if there is one.  
               This command is ignored if the radiobutton is already selected
               or it's state is not sensitve.


.DESCRIPTION:  A radio button is like a 
               <a href="checkbutton.html">checkbutton</a>, but in a group of 
               radio buttons only one can be selected. All radio buttons of 
               one group share one variable. This variable contains always 
               the value of the active radio button.

.NAME:      scale
.SHORTDESCR: Create and manipulate a scale widget
.SYNOPSIS:  scale VAROPTS
.OPTIONS:
            -variable; string; ""
                  Name of a (global) variable which is changed if the state 
                  of the button changes. If the variable does not exist,
                  it is created and set to the lower limit. If it does
                  exist, the widget is set accordingly.
                  If the value of variable is set externaly 
                  (e.g. via the set command), the value of the widget is 
                  adapted accordingly and <b>command</b> executed.


            -command; string; ""
                  Tcl command which is executed if the item is selected,
                  <b>variable</b> set externaly or <b>setValue</b> called.
                  <br><br>Before evaluating every percent (%) and its 
                  following character is substituted in <b>command</b>: 
                  <table>
                  <tr><th>%%</th><td> by %,</th></tr>
                  <tr><th>%v</th><td> by value of the scale widget</th></tr>
                  <tr><th>%w</th><td> by the widget-ID</th></tr>
                  </table>

            -lower; double; 0
                  lower limit

            -upper; double; 0
                  upper limit

            -value; double; 0
                  acual value

            -stepInc; double; 1
                  step increment

            -pageInc; double; 10
                  page increment

            -digits; integer; 1
                  Number of decimal places which are displayed.

            -drawValue; boolean; true
                  Whether only the value of the scale should be drawn.

            -valuePos; left, right, top, bottom; ???
                  Position where the value of the scale is drawn.

            -updatePolicy; continuous, discontinuous, delayed; continuous
                  How often a change of the value is reported (via
                  change of variable or execution of command.
            
            -orientation; horizontal, vertical; vertical
                  Orientation of the scale widgets.

.COMMANDS:  
            getValue
            Returns current value.

            setValue value
            Sets the state of the widget according to <b>value</b>,
            changes <b>variable</b> and executes <b>command</b>.

.NAME:      scrolledWindow
.SHORTDESCR: A widget which add scrolling capabilities to its child.
.SYNOPSIS:  scrolledWindow VAROPTS
.OPTIONS:
            STD_OPTIONS

            -child; widget-id; ""
               Widget ID of the child

            -scrollbar; always, never, automatic; automatic
               What type of scrollbar the widget should have. This can
               also be a list of two values where the first value
               is the type of the horizontal scrollbar and the
               second value is the type of the vertical scrollbar.
               Also possible is a boolean value understood by tcl
               where <b>true</b> is a synonym for <b>always</b> and
               <b>false</b> is a synonym for <b>never</b>.


.NAME:      socket
.SHORTDESCR: Create and manipulate a socket widget
.SYNOPSIS:  socket VAROPTS
.DESCRIPTION: A socket widget can be used to embed a window of another
            process. It works best with a <a href="plug.html">plug</a>
            widget on the other side.

.COMMANDS:  
            getXID
            Returns the XID of the socket. This value is required
            for the <a href="plug.html">plug</a> widget.

.NAME:      spinButton
.SHORTDESCR: Create and manipulate a spin button
.SYNOPSIS:  spinButton VAROPTS
.OPTIONS:
            -variable; string; ""
                  Name of a (global) variable which is changed if the state 
                  of the button changes. If the variable does not exist, it
                  is created with a value of <b>lower</b>. If it does
                  exist the widget is set accordingly.
                  If the variable is set externaly 
                  (e.g. via the set command) <b>command</b>
                  is called and the state of the widget changed.

            -maxLength; integer; -1
                  maximum length of entry value (<b>-1</b> means not limited)

            -editable; boolean; true
                  Whether  or not the the entry is editable

            -lower; double; 0
                  lower limit

            -upper; double; 0
                  upper limit

            -value; double; 0
                  acual value

            -stepInc; double; 1
                  step increment

            -pageInc; double; 10
                  page increment

            -numeric; boolean; true
                  Whether only numeric values are accepted.

            -digits; integer; 1
                  Number of decimal places which are displayed.

            -command; string; ""
                  Tcl command which is executed if the item is selected 
                  <br><br>Before evaluating every percent (%) and its 
                  following character is substituted in <b>command</b>: 
                  <table>
                  <tr><th>%%</th><td> by %,</th></tr>
                  <tr><th>%v</th><td> by value of the spinButton</th></tr>
                  <tr><th>%w</th><td> by the widget-ID</th></tr>
                  </table>

.COMMANDS:  
            getValue
            Returns the current value.

            setValue value
            Sets the state of the widget according to <b>value</b>,
            changes <b>variable</b> and executes <b>command</b>.

.NAME:         statusbar
.SHORTDESCR:   Create and manipulate a statusbar
.SYNOPSIS:     statusbar
.OPTIONS:      

.COMMANDS:  
               push context text
               Push text

               pop context
               Remove last in <b>context</b> pushed text 

               remove context id
               Remove in <b>context</b> text with the ID <b>id</b>

.COMMANDS:     
            add type VAROPTS
            add widgets to the toolbar. Valid types are <b>widget</b>,
            <b>space</b> or <b>item</b>. For <b>item</b> valid options
            are <b>-text</b>, <b>-tooltip</b>, <b>-icon</b>, 
            and <b>-command</b>.

            addEnd type VAROPTS
            synonym for <b>add</b>

            addBegin type VAROPTS
            same as <b>add</b> but adds widgets before existing childs
            
.NAME:      table
.SHORTDESCR: Create and manipulate a table widget
.SYNOPSIS:  table VAROPTS
.OPTIONS:
            -homogeneous; boolean; true
               Determines, if all rows and columns should have the same
               height, width respectively.

            -rows; integer; 3
               Numbers of rows on creation.

            -columns; integer; 3
               Numbers of columns on creation.

            -label; string; ""
                  label of the frame
            
            -shadow; none, in, out, etchedIn, etchedOut; none
                  type of shadow of the frame
            
            -xAlign; double (0 &lt;= xAlign &lt;= 1); 0
                  alignement of label

.DESCRIPTION: A table widget is a container widget, which packs its
            children in rows and columns.  If necessary gtk
               alignment widgets are used when adding children.

.COMMANDS:
            add widget-id column row VAROPTS
            Adds <b>widget-id</b> at <b>row</b> and <b>column</b> to
            the table. Valid options are <b>-rowSpan</b>, <b>-columnSpan</b>, 
            <b>-expand</b>, <b>-shrink</b>, <b>-fill</b>, 
            <b>-padding</b>, <b>-align</b>, and <b>-scale</b>. All but 
            the first to options can consist either of a list of two
            values for the horizontal and vertical value or of one
            value in which case horizontal and vertical is set to the
            same value.

            addRow widget-list VAROPTS
            Same options as <b>add</b> plus <b>-start</b>

            addColumn widget-list VAROPTS
            Same options as <b>addRow</b>

.NAME:      text
.SHORTDESCR: Create and manipulate a text widget.
.SYNOPSIS:  text VAROPTS
.OPTIONS:
            -editable; boolean; true
               Determines whether the text is editable.

            -wordWrap; boolean; true

            -lineWrap; boolean; true

            -scrollbar; always, never, automatic; automatic
               What type of scrollbar the list should have. This can
               also be a list of two values where the first value
               is the type of the horizontal scrollbar and the
               second value is the type of the vertical scrollbar.
               Also possible is a boolean value understood by tcl
               where <b>true</b> is a synonym for <b>always</b> and
               <b>false</b> is a synonym for <b>never</b>.
               <br>Because of the shortcomings of the gtk text 
               widget the horizontal will never show up.

.DESCRIPTION:
            A position has the form <tt>anchor</tt>, 
            <tt>anchor+Offset</tt> or <tt>anchor-Offset</tt>. 
            <tt>anchor</tt> can be <b>end</b>, <b>cursor</b>,
            <b>selectionStart</b> or <b>selectionEnd</b>. 
            <tt>Offset</tt> must be an integer value. Example:
            <tt>cursor+1</tt> or <tt>selectionEnd-1</tt>.

.COMMANDS:
            remove ?startPos endPos?
            Delete characters from <b>startPos</b> to <b>endPos</b>.
            If both position parameters are missing they default to
            <b>0</b> and <b>end</b>, respectively. If only
            <b>endPos</b> is missing, it defaults to <b>end</b>.

            select ?startPos endPos?
            Select characters from <b>startPos</b> to <b>endPos</b>.
            If both position parameters are missing they default to
            <b>0</b> and <b>end</b>, respectively. If only
            <b>endPos</b> is missing, it defaults to <b>end</b>.

            cut
            Cut selected characters to clipboard.

            copy
            Copy selected characters to clipboard.

            paste
            Paste content of clipboard.

            getChars ?startPos endPos?
            Get characters from <b>startPos</b> to <b>endPos</b>.
            If both position parameters are missing they default to
            <b>0</b> and <b>end</b>, respectively. If only
            <b>endPos</b> is missing, it defaults to <b>end</b>.

            getLength
            Get length of widget content.

            setPoint pos
            Sets the insertion cursor to position <b>pos</b>

            getPoint
            Returns the position of the insertion cursor.

            getPosition pos
            Returns the index of position <b>pos</b>

            insert pos text VARARGS
            Inserts <b>text</b> at position <b>pos</b>. Valid
            options are <b>-font</b>, <b>-foreground</b>, 
            <b>-background<b>.


.NAME:         toolbar
.SHORTDESCR: Create and manipulate a toolbar widget.
.SYNOPSIS:     toolbar VAROPTS
.OPTIONS:
               -orientation; horizontal, vertical; horizontal
                  Orientation of the toolbar

               -style; icons, text, both; both
                  whether icons and/or text shall be shown.

.COMMANDS:
            configure VAROPTS

            add type VAROPTS

            addBegin type VAROPTS

            addEnd type VAROPTS
            <b>type</b> must be one of space, widget or item.
            <br>valid options are:
            <br>-text
            <br>-tooltip
            <br>-command
            <br>-icon; <a href="percentstring.html">percent string</a>; ""
                  Icon of the button

.NAME:      window
.SHORTDESCR: Create and manipulate a top level widget.
.SYNOPSIS:  window VAROPTS
.OPTIONS:
            -title; string; ""

            -resizable; boolean; true

            -modal; boolean; false

            -type;;

            -child; widget-id; ""

            -width; integer; -1
               Default width of window.

            -height; integer; -1
               Default height of window.

