
Class documentation.

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

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

** GtApp **
-----------

* Name:       GtApp
* Superclass: GtBase
* Include:    gtapp.h


  This class is common anchor for all displays and widgets created by a
program. Any program that want to use the Gt widgets must have one instance
of this class to handle events, resources, timeouts and other global
administration.

  To ease the handling of resources a number of type converters are
registered by the GtApp class. These converters allow the program to read
resources whose value is to be treated as something other than a string. The
available converters are:

  Type define    Type        Description
  --------------------------------------
  GTRT_STRING    (char *)    No conversion performed
  GTRT_BYTE      (byte)      Convert from string to number
  GTRT_WORD      (word)      Convert from string to number
  GTRT_LONG      (long)      Convert from string to number
  GTRT_BOOL      (sbool)     Convert from string to boolean (stored in char)
  GTRT_ALIGN     (ubyte)     Convert from string to alignment constant
  GTRT_PLACE     (ubyte)     Convert from string to placement constant
  GTRT_ORIENT    (ubyte)     Convert from string to orientation constant
  GTRT_DIR       (ubyte)     Convert from string to direction constant
  GTRT_FRAME     (ubyte)     Convert from string to frame type constant
  GTRT_APLACE    (ubyte)     Convert from string to arrow placement constant

  The number converters uses a normal string to number conversion which
allow numbers to be specified in decimal, hex (with '0x' prefix) or octal
(with '0' prefix).

  The constant converters compares the resource string value to a predefined
set of strings and sets a constant value connected to a matching string from
the set. The possible strings are described below:

  Type define    Strings
  ----------------------
  GTRT_BOOL      "true", "false"
  GTRT_ALIGN     "left", "right", "center"
  GTRT_PLACE     "top", "left", "topleft", "bottom", "right",
                 "botright", "center", "expand"
  GTRT_ORIENT    "vert", "vertical", "horiz", "horizontal"
  GTRT_DIR       "left", "right", "up", "down"
  GTRT_FRAME     "none", "simple", "in", "out", "dbl_in", "dbl_out"
  GTRT_APLACE    "apart", "together"
  
  The constants generated from these strings are listed in the header
"gtcommon.h" in the include directory.


Tags for GtApp:
---------------

  Name           ISGR  Type            Defaults
  ---------------------------------------------
  GT_AppName    (I.G.) (char *)        "gtapp"
  GT_AppClass   (I.G.) (char *)        "GtApp"
  
  
  * GT_AppName
    The name used by the program to find it's resources are set by this tag.


  * GT_AppClass
    The class of the program used to find it's resources are set by this
    tag.


Callbacks for GtApp:
--------------------

  ** NONE DEFINED **


Methods for GtApp:
------------------

   -- User methods --
   
  void SetupRes(int *ac,char **av)
  sbool LoadRes(char *name,sbool override)
  sbool GetRes(GtWidget *obj,char *name,int type,void *data)
  void AddRConverter(int t,GtCallB cb,GtUDPtr ud)
  void RemRConverter(int t,GtCallB cb)
  int AddRType(char *tname,sbool create)
  void AddTimeOut(long msec,GtCallB cb,GtUDPtr ud)
  void RemTimeOut(GtCallB cb)
  void AddFDWatch(int fd,uword mode,GtCallB cb,GtUDPtr ud)
  void RemFDWatch(int fd,GtCallB cb)
  void BreakLoop(void)
  sbool EventLoop(int mode)
  char *GtDesc(void)
  
    -- Internal methods --
    
  void AddDisp(GtAppDisp *d)
  void RemDisp(GtAppDisp *d)
  void GetArgs(int *ac,char ***av)

   -- GtBase methods --
   
  Init, Set, Get, GetClass, IsSubClassOf, InitV, SetV, GetV, GetA,
  PrtErrHeader

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

  void SetupRes(int *ac,char **av)

    - ac : pointer to argument count from the "main()" function.
    - av : pointer to argument vector from the "main()" function.

    This method checks the command line arguments for arguments that sets
    resources in the program. Any such arguments found are removed.
    
    NOTE: The call to this method must be performed before the first
    GtAppDisp object is added to the GtApp. This is to ensure correct
    handling of resources.
    
    NOTE: The program is not required to call this method but it is strongly
    recommended that it makes the call. The user will expect to be able to
    set some resources by command line arguments and this method handles
    that.
    
 ----------------------------------------------------------------------------

  sbool LoadRes(char *name,sbool override)

    - name     : name of the resource file to load.
    - override : true if the resources in the file to load is to replace the
                 previously loaded resources.

    - <result> : true if loading the file was successful.

    This method loads a resource file and combines the resources in the file
    with those already loaded by other sources. If the <override> flag is true
    any resources found in multiple sources will get the value of the latest
    loaded source.
    
    NOTE: The call to this method must be performed before the first
    GtAppDisp object is added.
    
 ----------------------------------------------------------------------------

  sbool GetRes(GtWidget *obj,char *name,int type,void *data)

    - obj  : pointer to the widget looking for resources.
    - name : name of the resource to find.
    - type : the type of the resource value.
    - data : pointer to a position to store the result.
    
    - <result> : true if the resource was found and converted correctly.
    
    This method will try to find a named resource in the resource database.
    If a resource is found the list of converters are searched for one matching
    the <type> argument. If one is found it is invoked and it will then place
    the converted value in the position supplied by <data>. If the conversion
    failed or no converter can be found the method will return false and the
    position supplied by <data> will be unmodified. A type of "GTRT_STRING"
    will always be successful since no conversion is performed.

    If the argument <obj> is "NULL" then a resource with the prefix made up
    of only the program's name or class will be used. The method can be used by
    the program to read additional resources apart from the widget resources.

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

  void AddRConverter(int t,GtCallB cb,GtUDPtr ud)

    - t  : type to install converter for.
    - cb : pointer to the converter function.
    - ud : pointer to user defined information pass on in the call.
    
    This method will install a new type converter. The installer will then
    be invoked by the "GetRes()" method when the type of the converter is
    requested. The converter will be called with a pointer to the GtApp
    object as the first argument. The second argument is a pointer to a
    structure with the following parts:

     GtResourceCD
     {
       int type
       void *data
       XrmValue res
     }

     - type : type to convert the resource to.
     - data : pointer to memory to store the converted value in.
     - res  : the resource string to convert stored in a XrmValue structure.

    The third argument to the converter will be the <ud> passed to this
    method.
    
    The converter will try to convert the resource string and store the
    result in the memory pointed to by <data> in the "GtResourceCD"
    structure.
    
    If no conversion was possible the converter must return "GTCB_BREAK" to
    allow other converters installed for the same type to be invoked. If
    conversion was successful the converter must return "GTCB_CONT".
    
    The same converter can not be install multiple times for the same type
    but it can be installed for different types. Different converters can
    also be installed for the same type to expand the possible values of a
    previous converter.

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

  void RemRConverter(int t,GtCallB cb)

    - t  : type to remove converter for.
    - cb : pointer to converter function to remove.
    
    This method will remove a type converter function for a given type.
  
 ----------------------------------------------------------------------------
  
  int AddRType(char *tname,sbool create)

    - tname  : pointer to a string with the name of a type.
    - create : true if the type may be created and false if it must already
               exist.
               
    - <result> : the type value of the named type.
    
    This method adds or finds a named type. The returned number is the type
    value to use in "GetRes()" or "AddRConverter()" when referring to the
    type.  The idea is to use this method to add types that are not builtin
    and then add a resource converter for the type to handle it in
    "GetRes()".

    All valid types have a type value greater than zero and if the <create>
    argument is "FALSE" and the named type do not exist the returned value
    will be zero to indicate a missing type.

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

  void AddTimeOut(long msec,GtCallB cb,GtUDPtr ud)

    - msec : number of milliseconds before timeout.
    - cb   : callback function called at timeout.
    - ud   : pointer to user defined information pass on in the call.
    
    This method adds a callback function to be called after a number of
    milliseconds have passed. After the call to the callback function the
    function will be removed from the timeout list. A timeout callback that
    is to be called repeatedly must add itself as the last thing before
    returning from the call.

    No callback data is passed to the callback function (argument is NULL).

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

  void RemTimeOut(GtCallB cb)

    - cb : pointer to timeout callback function to remove.
    
    This method will remove a callback function from the timeout list.
  
 ----------------------------------------------------------------------------

  void AddFDWatch(int fd,uword mode,GtCallB cb,GtUDPtr ud)
  
    - fd   : a file descriptor to be check for changes.
    - mode : what changes to check for.
    - cb   : pointer to a callback function to call upon changes.
    - ud   : pointer to user defined information pass on in the call.
    
    This method will install a callback function to be called whenever some
    changes occur in a file descriptor. Possible changes to watch for are:

     GTAWM_READ   : there is something to read from the file descriptor.
     GTAWM_WRITE  : it is possible to write to the file descriptor.
     GTAWM_EXCEPT : some exception occurred on the file descriptor.
    
    The <mode> argument can be set to any or'ed combination of the above
    constants and when some change occur the callback function will be
    called with a pointer to the following structure as callback data:
    
     GtWatchCD
     {
       int fd;
       uword mode;
     }

     - fd   : which file descriptor changed.
     - mode : what changed (a combination of GTAWM_* constants).
     
 ----------------------------------------------------------------------------
     
  void RemFDWatch(int fd,GtCallB cb)
  
    - fd : a file descriptor to stop watching.
    - cb : pointer to the callback function to remove.
   
    This method will remove the watching callback function from a
    file descriptor.
   
 ----------------------------------------------------------------------------

  void BreakLoop(void)
  
    This method will break out of the "EventLoop()" method and make it
    return "FALSE".
  
 ----------------------------------------------------------------------------

  sbool EventLoop(int mode)
  
    - mode : the way to process events.
    
    - <result> : true if more processing is to be done and false if the loop
                 was broken.
    
    This method will process X events in three different ways depending on
    it's <mode> argument:
    
     GTAM_POLL : only one pending event is processed without waiting if no
                 event is pending.
     GTAM_WAIT : only one pending event is processed and if no event is
                 pending wait for one to arrive.
     GTAM_LOOP : events are processed as they arrive and this method will
                 not return until after a call to "BreakLoop()".
                 
    All added GtAppDisp object with pending events receive a call to their
    "HandleEvent()" method. All timeouts and file descriptor watches are also
    check and called as required.
    
    NOTE: If this method is used to poll for events the method must be
    called as often as possible for the user interface to behave normally
    without delays.

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

  char *GtDesc(void)
  
    - <result> : pointer to a description string.
                   
    This method will return a string describing the library.
    
 ----------------------------------------------------------------------------

  void AddDisp(GtAppDisp *d)
    
    - d : pointer to a GtAppDisp object to add.
    
    This method adds a GtAppDisp object to the internal list.
  
 ----------------------------------------------------------------------------

  void RemDisp(GtAppDisp *d)
  
    - d : pointer to a GtAppDisp object to remove.
    
    This method removes a GtAppDisp object from the internal list.
  
 ----------------------------------------------------------------------------

  void GetArgs(int *ac,char ***av)

    - ac : pointer to an integer to store argument count in.
    - av : pointer to an char pointer pointer to store argument vector in.
    
    This method will return the argument count and vector set by a call to
    "SetupRes()".

