
General documentation.

$Ident: This file is part of the 'Gt-library' 1.0.0 $
$Copyright: (C) 1997 by Gran Gustafsson $

-------------------------------------------------------------------------

 Introduction
--------------
The Gt library is a collection of C++ classes for creating Graphical User
Interfaces (GUI) under X Windows. It is based directly on Xlib and provide
low-level encapsulation of X resources and high-level GUI components.

The library is created to allow more widgets (a widget is a X window with
functionality) to be developed with as little extra work as possible. The
construction of the library is not as flexible and standardized as for
example the Xt library but it is good enough for most programs and widgets.

Since Gt uses C++ for implementation it is of course object oriented which
is a very natural way of looking at a GUI. The classes of the library is
divided in two separate parts: the low-level classes and the high-level
classes. The low-level classes provide a object oriented interface to most
of the X resources like windows, fonts and cursors. These classes are then
used in the high-level classes to create common components in a GUI like
buttons, frames and lists.


 Terminology
-------------
There is a number of word used in the documentation of the Gt library that
may need some mentioning.

* Callback
  A callback is a function invoked through a callback list in one of classes
  of the Gt library. All callback functions have the same prototype to allow
  a simple calling system.

* Callback list
  A callback list is simply a list of callback functions that can be
  activated and then activates all of the callback functions on the list. 
  Widgets that lets the user interact with them in some way usually have a
  callback list to inform the program when some changes occur.

* Manager
  A manager is a widget that can contain other widgets to form a hierarchic
  structure of widgets. Managers can also control the placement and size of
  it's children (widgets that it contain) to handle automatic layout.

* Resource
  A resource is some named information (normally stored in a resource file)
  that a widget or program can read through a standard interface. Resources
  are used in widgets to allow a user of a program to modify the appearance
  and function of a widget without recompiling the GUI.

* Tag
  A tag is a tag identifier and a value for the data that the tag identifier
  is referring to. Tags are used to create and change widget attributes.

* Tag identifier
  A tag identifier is a constant number used in the Gt library to refer to
  data in a widget. The most common use for tag identifiers are to refer to
  values, callback lists or events occurring.

* Widget
  A widget is a X window and a some functionality connected to that window. 
  An example would be a button. The button uses a X window to allow it to
  display a border to the user. The user may then press the button with the
  mouse pointer and the border will then invert. The mouse button press will
  be sent to the button through it's X window and that activates the
  functionality to invert the border.

* X resource
  A X resource is a window, font, pixmap or other entity created and
  maintained by the X server. Do not confuse with a "resource" that is some
  named information.


 Naming convention
-------------------
Most named objects introduced by the Gt library will have the "Gt" or "GT"
prefix in some way.

* All class names have a "Gt" prefix and are in mixed case.

* All methods and functions have mixed case.

* All structures have a typedef of the same name as the structure and the
  name is in mixed case with a "Gt" prefix.

* All constants are defines with names in upper case and a "GT" prefix.


 Tags
------
To be able to use the classes of the Gt library one must know how to handle
tags. A tag is a structure with the following construction:

 GtTag
 {
   ulong tag;
   union
   {
     ulong val;
     void *ptr;
   } d;
 }
 
 - tag : a tag identifier to indicate what kind of information this is.
 - val : a integer value as information.
 - ptr : a pointer as information.
 
An array of GtTag structures is called a tag list. Tag lists are used when
creating widget, setting or getting widget attributes and in some other
operations to supply values in a dynamic way. Only the attributes that have
a corresponding tag in a tag list passed to a operation will be considered
in the operation and if there is unidentified tags in the tag list they will
be ignored. This allow for extensible operations that understand more and
more tags as new code is added. The programmer will also only have to provide
tags for the values that need to be modified. A tag list is terminated by
the tag list terminator tag identifier as described below.

To simplify the use of tag lists most operations that use them will be
available in two versions: one that take an array pointer and one that uses
varargs to build the tag list from "ulong" arguments. The first version is
straight forward and force the programmer to fill in an array. The second
method allow the programmer to make a call to a operation with an argument
list that consist of a tag identifier, the value for the tag identifier, a
new tag identifier, the value for the new tag identifier and so on until the
tag list terminator.

All tag identifier used in the Gt library have a define with a name prefix
of "GT_" and then a name in mixed case. There is also a number of control
tag identifiers.

* GT_DONE
  This is the tag list terminator and there for the most used control tag
  identifier. No value is used for this tag identifier.

* GT_MORE
  The value of this control tag identifier is a pointer to a new tag list
  where the processing is to continue. The current tag list is terminated by
  this control tag identifier.

* GT_SKIP
  The value of this control tag identifier is a number and that many tags
  after this one will be skipped in the processing.

* GT_IGNORE
  The value of this control tag identifier is ignored during processing.

For many of the tags used to create widgets there is a resource with a name
equal to a lower case version of the tag identifiers define name.

There is a number of functions to manipulate tags and tag lists and they are
documented in the file "gttags.txt".


 Resources
-----------
The Gt library uses the standard Xlib functions to load and query a resource
database for named data provided as resources to a program. Resources can
only be used to modify widgets when they are created and only if no
corresponding tag is provided in the program when creating the widget. In a
program all attributes of a widget is controlled by tags.

The GtApp class of the Gt library is responsible for the handling of
resources and when it is created a application name and class can be
provided. Those names are used when loading and finding resources.

A program using the Gt library will try to load resources from the following
sources:

1) A file named "GtDefaults" in the resource path.

2) A file named from the value of "GT_AppClass" in the resource path.

3) A file named from the value of "GT_AppName" in the resource path.

The resource path is a string of directory names separated by colons (:) and
with a '%s' in each directory name where the file name will be inserted.
There is two path that is examined by performing the three steps above for
each directory name. The first path is the compiled in path that is normally
set to "/usr/lib/X11/app-defaults/%s:.%s-res:%s.res" and the second path is
any path set in the environment variable "GTRESOURCEPATH".

The default resource path allow a super default resource file named
"GtDefaults" to be placed in the application defaults directory together
with a file named as the application class containing settings for any
program of the same type. There can also be a local resource in the current
directory named as the application name with a "." prefix and a "-res"
suffix or only a ".res" suffix.

The possible values for a resource is decided by the type of the resource
when search for in the resource database. The type of a resource will
normally be the same as for a corresponding tag. That is if the tag is
numeric so is the resource. If the tag uses a number of defines then the
resource will most often understand a number of strings that is the same as
a lower case version of the defined constants without any prefix (anything
up to and including the first underscore). For more details of possible
value on some resources se the documentation for the GtApp class.


 Callback functions
--------------------
A callback function is a normal function with a standard prototype. It is
called by widgets and other classes in the Gt library to inform the program
that some action occurred.

All callback function have this prototype:

 int CallBack(GtBase *obj, GtCDPtr cd, GtUDPtr ud)
 
 - obj : pointer to the object that activated the callback list where the
         callback function is located. If a button is pressed and activates
         a callback function for it this will point to the button object.
 - cd  : this is a pointer to detail information of why the callback
         function was called. The information is described in the
         documentation of the callback.
 - ud  : this is a pointer to some information that the programmer passed in
         when the callback function was added to a callback list. The Gt
         library will not use this pointer in any way.

 - <result> : a callback function should return a value of "GTCB_CONT" if
              any callback functions after it on the callback list is to be
              called and "GTCB_BREAK" if not.

There is a type named "GtCallB" to represent the type of a callback
function for use as argument in operations that require a callback function.


 Using the Gt library
----------------------
To use the low-level classes in a program no special steps apart from
creating a GtDisplay object (to connect to the X server) have to be taken.
But if the high-level classes is to be used the following steps are
necessary:

1) Create a GtApp object.

2) Read any resources from the command line with the "SetupRes()" method on
   the GtApp object.

3) Create a GtAppDisp object to connect to the X server.

4) Create a GtAppShell object as the main window of the program. This step
   is not necessary but most programs will probably perform it.

After these steps the program is ready to create the main GUI by adding
widgets to the GtAppShell object.

All GUI's created with the Gt library will have a single root widget and all
other widgets will be located in a tree of widgets under that. All manager
widgets are nodes in the widget tree and the other widgets are leafs. Many
manager have a limit on how many managed children it can have.


 Creating objects with the Gt library
--------------------------------------
Any object in from the classes of the Gt library can of course be created
like any C++ object with "new" and a class name. But before the object can
be used the method "Init()" will have to be called on the object. The
"Init()" method have a slightly different prototype depending on the class.
Since all objects have to be created in this way each class that can be
instantiated in the Gt library has a function named "GtMk" followed by the
class name (for example the "GtMkApp()" function) that create object and
call the "Init()" method on it. The function will also check for failure in
creating the object or in the call to "Init()" and will call the error
function appropriately. The prototype for the function will vary from class
to class but many of the classes have the same prototype. Here is a
table of the different prototypes:

1) A GtDisplay object for the low-level classes is created with:

    GtDisplay *GtMkDisplay(GtTag *tgs) or
    GtDisplay *GtMkDisplay(ulong tag, ...)

2) Any object of a low-level class other then the GtDisplay class is created
   with:
    (replace <Class> with low-level class name without "Gt" prefix)
   
    Gt<Class> *GtMk<Class>(GtDisplay *dsp, GtTag *tgs) or
    Gt<Class> *GtMk<Class>(GtDisplay *dsp, ulong tag, ...)

3) A GtApp object is created with:

    GtApp *GtMkApp(GtTag *tgs) or
    GtApp *GtMkApp(ulong tag, ...)

4) A GtAppDisp object is created with:

    GtAppDisp *GtMkAppDisp(GtApp *app, GtTag *tgs) or
    GtAppDisp *GtMkAppDisp(GtApp *app, ulong tag, ...)

5) Any widget class is created with:
    (replace <Class> with widget class name without "Gt" prefix)
    
    Gt<Class> *GtMk<Class>(char *name, GtManager *parent, GtTag *tgs) or
    Gt<Class> *GtMk<Class>(char *name, GtManager *parent, ulong tag, ...)
   
   The GtAppShell class also have functions to allow the parent argument to
   be of type "GtAppDisp *" since it is the usual parent for a GtAppShell.


 Destroying classes with the Gt library
----------------------------------------
A object from one of the classes in the Gt library should be destroyed by
the "GtDestroy()" function that will perform the "DeInit()" method on the
object and then free it. It will also see to it that no problems occur when
destroying object that is being processed in some way.


 Error handling in the Gt library
----------------------------------
When a fatal error occur in the code that is part of the Gt library it will
call the "GtError()" function to by default print an error message on
"stderr" and then exit with value 1. If the default action is not desired a
program can install an error callback function. See the "gterror.txt" file
for details.


 Class documentation
---------------------
Each class of the Gt library is described in a file with the following
format:

1) Title of the class.

2) Name of the class as used in a program.

3) The super class of the class.

4) The include file to for using the class. There is a include file named
   "gtall.h" that will include all other include files for ease of use.

5) A description of the class.

6) A table of all tags that the class responds to. The table will be split
   in multiple parts describing tags introduced on each level of inheritance.
   The table will have the following entries:
   
    * Name
      Name of the tag with it's "GT_" prefix.
    
    * ISGR
      This entry indicate when a tag may be used an if it has a
      corresponding resource. The four characters are used to indicate:
      I - when creating,
      S - when setting,
      G - when getting and
      R - if a resource exist.
      When the tag can be used a character is in present and otherwise it 
      is omitted.
    
    * Type
      The type of the tag is given here. When getting a tag value it is
      always considered to be "ulong *" if not otherwise stated.
    
    * Defaults
      The default value of the tag used when a object is created and the
      widget is not supplied.

7) All callback lists that the class provide.

8) All methods of the class divided in three groups: user methods that the
   program normally use, internal methods that are normally only used by
   other classes in the Gt library and inherited methods. The inherited
   methods are not described with prototype.
