
Class documentation.

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

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

** GtAppDisp **
---------------

* Name:       GtAppDisp
* Superclass: GtDisplay
* Include:    gtappdisp.h

  This class extends the GtDisplay class with event distribution to a tree
of widgets. The distribution can be modified by a focus widget and a grab
widget.

  GtAppDisp objects are connected to a GtApp object when they are created
and the GtApp object controls when event are to be read.

  When a event is read from the X server the GtAppDisp object will check if
there is a focus widget. If a focus widget exists it will get to handle the
event before all other widgets. If it does not use the event the destination
widget of the event (base on a widget's window) is searched for in the
widget tree. When a widget is found to be the destination a check to see if
there is a grab widget is made. If a grab widget exists and the destination
widget is not a child of the grab widget the event is sent only to the grab
widget. If no grab widget exists or if the destination widget is a child of
the grab widget then the event is passed to the destination widget. If it
does not use the event it is passed to the parent of the destination widget.
This is repeated so that the event is passed up through the widget tree
towards the root widget. If any widget on the chain uses the event it is not
passed on. If there exists a grab widget and it has not handled the event
when the chain is broken it is passed the event last of all.

  Callback functions can be installed to handle events before they are
distributed to the widget tree.

  To handle any resource values attached as properties on the root window of
a X display all GtAppDisp objects create a resource database that is used
when the method "GetRes()" in the connected GtApp object is called.

  The GtAppDisp class provide a number of methods to simplify the use of the
"selection" system of the X server.


Tags for GtAppDisp:
-------------------

   -- GtDisplay tags --

  Name                   ISGR  Type            Defaults
  -----------------------------------------------------
  GT_DispString         (I.GR) (char *)        NULL
  GT_DontFreeX          (I.G.) (sbool)         FALSE
  GT_XDisplay           (I.G.) (Display *)     NULL
  
   -- GtAppDisp tags --
   
  Name                   ISGR  Type            Defaults
  -----------------------------------------------------
  GT_MultiClickTime     (ISGR) (long)          GTDEF_MULTICLICK
  GT_App                (I.G.) (GtApp *)       NULL
  

  * GT_MultiClickTime
    The value of this tag is the number of milliseconds that may between
    mouse clicks for them to be considered a multiple click.


  * GT_App
    This tag provide the GtApp object to connect to.


Callbacks for GtAppDisp:
------------------------

  Name                  Callback data
  -----------------------------------
  GT_Before             (XEvent *)
  GT_EnterLeave         (GtEnterLeaveCD *)
  
  
  * GT_Before
    This callback is activated before each event is distributed to the
    widget tree. If the return value is "GTCB_BREAK" then the event will
    not be distributed.
    
    The callback data is a pointer to a normal XEvent structure.
    

  * GT_EnterLeave
    Any widget that have the value of the tag "GT_EnterLeave" set to "TRUE"
    will call activate this callback when the mouse pointer enter or leave
    the widget window.

    The callback data is a pointer to the following structure:
    
     GtEnterLeaveCD
     {
       GtWidget *wid;
       ulong state;
       sbool enter;
     }
     
     - wid   : pointer to the widget that activated the callback.
     - state : the state mask from a XCrossingEvent.
     - enter : true if the mouse pointer entered the widget.


Methods for GtAppDisp:
----------------------

   -- User methods --
   
  void AddCB(ulong tag,GtCallB cb,GtUserD ud)
  void RemCB(ulong tag,GtCallB cb)
  
   -- Internal methods --
   
  void HandleEvent(XEvent *xe)
  void SetRoot(GtWidget *o)
  GtWidget *GetRoot(void)
  void SetFocus(GtWidget *o)
  void ClrFocus(GtWidget *o)
  void ChkFocus(GtWidget *o)
  void SetGrab(GtWidget *o)
  void ClrGrab(GtWidget *o)
  sbool HasFocus(GtWidget *o)
  sbool HasGrab(GtWidget *o)
  sbool OwnSelection(GtWidget *w,Atom sel,Time t,GtCallB conv,GtCallB lose,
                     GtCallB done,GtUDPtr ud)
  void DisOwnSelection(GtWidget *w,Atom sel)
  void GetSelection(GtWidget *w,Atom sel,Atom target,Atom dest,Time tm,
                    GtCallB cb,GtUDPtr ud)
  Atom *GetStdAtoms(void)
  void EnterLeave(GtWidget *w,sbool enter,ulong state)
  long GetMCTime(void)
  XrmDatabase GetDB(void)

   -- GtDisplay methods --
   
  HandleEvent, Dsp, Pending, XBlackPixel, XWhitePixel, XDefaultColormap,
  XDefaultDepth, XDefaultRootWindow, XDefaultScreen, XDefaultVisual,
  XDisplayCells, XDisplayPlanes, GetFD
  
   -- GtBase methods --

  Init, Set, Get, GetClass, IsSubClassOf, InitV, SetV, GetV, GetA,
  PrtErrHeader

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

  void AddCB(ulong tag,GtCallB cb,GtUserD ud)
  
    - tag : tag identifier to select which callback list to add to.
    - cb  : pointer to callback function to add.
    - ud  : pointer to user defined information to pass on in the call.
    
    This method will add a callback function to one the callback lists
    provided by the class.

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

  void RemCB(ulong tag,GtCallB cb)
  
    - tag : tag identifier to select which callback list to remove from.
    - cb  : pointer to callback function to remove.
    
    This method will remove a callback function from one of the callback
    lists provided by the class.

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

  void HandleEvent(XEvent *xe)

    - xe : pointer to space to store event in.
    
    This method reads the next event from the X server and distributes it to
    connected widgets.
    
    The distribution consist of the following steps:
    
     1) The callbacks on the "GT_Before" callback list is activated.
     
     2) If there is a focus widget it's "Handle()" method is called.
     
     3) The event is sent to the destination widget based on the window in
        the event. If there is a grab widget and the destination widget is
        not a child of the grab widget then skip to 5).
     
     4) Pass the event up the chain of parent widgets all the way to the
        root widget.
     
     5) If there is a grab widget and it has not received the event pass it
        to the grab widget last of all.
        
    After any step the distribution may be aborted if the event is used.
    
 ----------------------------------------------------------------------------

  void SetRoot(GtWidget *o)
  
    - o : pointer to a widget object.
    
    This method will set the root widget of the widget tree. There is only
    one root object so all other widgets will be children of this root
    widget.
    
 ----------------------------------------------------------------------------

  GtWidget *GetRoot(void)
  
    - <result> : pointer to the root widget.
    
    This method returns the root widget.

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

  void AddWidget(GtWidget *w)
  
    - w : pointer to a widget object.
    
    This method will connect the widget object with it's X window for event
    distribution.

 ----------------------------------------------------------------------------
    
  void RemWidget(GtWidget *w)
  
    - w : pointer to a widget object.
    
    This method will disconnect a widget object from it's X window and stop
    it from event distribution.

 ----------------------------------------------------------------------------
    
  GtWidget *GetCurrentWidget(void)
  
    - <result> : pointer to a widget object.
    
    This method returns the widget that is currently handling a event. It
    is used to handle destructions of widgets at any time.

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

  void SetFocus(GtWidget *o)

    - o : pointer to a widget object.
    
    This method will try to set the widget object as the focus widget. It
    will only succeed if there is no current focus widget and the focus
    object is a child to any grab widget.
    
    If the widget is made the focus widget it will receive a
    "Notify(GT_FocusIn)" method call.
    
 ----------------------------------------------------------------------------

  void ClrFocus(GtWidget *o)
  
    - o : pointer to a widget object.
    
    This method will try to unset the widget as the focus widget. It will
    succeed if the current focus widget is this widget.
    
    If this widget was the focus widget it will receive a
    "Notify(GT_FocusOut)" method call.

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

  void ChkFocus(GtWidget *o)
  
    - o : pointer to a widget object.
    
    This method checks to see if the focus widget is a child of the <o>
    widget. If it is true the focus widget is cleared by "ClrFocus(..)".

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

  void SetGrab(GtWidget *o)
  
    - o : pointer to a widget object.
    
    This method will try to set the grab widget. It will succeed if there is
    no current grab widget.
    
    If the grab widget was set then any focus widget is check to see if it
    is a child of the grab widget and if it is not it is cleared with
    "ClrFocus(..)".
    
    The grab widget will normally limit the distribution of events to a
    widget subtree be using any events it is passed except for expose events.

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

  void ClrGrab(GtWidget *o)
  
    - o : pointer to a widget object.
    
    This method will try to unset the grab widget. It succeed if the current
    grab widget is the same as <o>.

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

  sbool HasFocus(GtWidget *o)
  
    - o : pointer to a widget object.
    
    - <result> : true if the widget object is the focus widget.
    
    This method will check if a widget is the focus widget.

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

  sbool HasGrab(GtWidget *o)
  
    - o : pointer to a widget object.
    
    - <result> : true if the widget object is the grab widget.
    
    This method will check if a widget is the grab widget.

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

  sbool OwnSelection(GtWidget *w,Atom sel,Time t,GtCallB conv,GtCallB lose,
                     GtCallB done,GtUDPtr ud)
  
    - w    : pointer to widget get ownership of selection.
    - sel  : selection to own.
    - t    : timestamp of ownership.
    - conv : callback function called when selection requested.
    - lose : callback function called when selection lost.
    - done : callback function called when selection not needed any more.
    - ud   : pointer to user data passed to all three callback functions.
    
    - <result> : true if the widget got the ownership.
    
    This method will try to make the widget the owner of a selection. When
    someone requests the selection in some format the <conv> callback will
    be activated and the callback data is a structure as follows:
    
     GtSelReqCD
     {
       XEvent *xevent;
       GtWidget *w;
       Window req;
       Atom sel;
       Atom target;
       Atom prop;
       int fmt;
       ubyte *data;
       int len;
       sbool ok;
     }
     
     - xevent : pointer to the event that triggered the selection request.
     - w      : pointer to the widget owning the selection.
     - req    : X window of the requester.
     - sel    : atom identifying the selection that was requested
                (ie XA_PRIMARY).
     - target : atom identifying the desired destination format. Change this
                atom to reflect the true destination format.
     - prop   : destination property of the requester.
     - fmt    : change this value to the format of the selection data.
     - data   : change this to a pointer to the selection data.
     - len    : change this to the size of the selection data in <fmt>
                units.
     - ok     : change this value to false if error occurred.
    
    When the ownership is lost to someone else the <lose> callback is
    activated with the following structure as callback data:
    
     GtSelClrCD
     {
       XEvent *xevent;
       GtWidget *w;
       Atom sel;
     }
     
     - xevent : pointer to the event that caused the widget to lose
                ownership.
     - w      : pointer to the widget that had the ownership.
     - sel    : atom identifying the selection.
    
    When the selection is not needed any more (the ownership is lost and no
    outstanding requests remain) the <done> callback is activated to allow
    cleanup of the selection. A pointer to a structure as for the <lose>
    callback is passed as callback data.

    A selection owner must always be ready to respond to the target
    "TARGETS" that is to return the contents of the standard atoms as
    returned by the "GetStdAtoms()" method and extended by all targets that
    the owner can convert the selection to.

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

  void DisOwnSelection(GtWidget *w,Atom sel)
  
    - w   : pointer to owner widget.
    - sel : selection to disown.
    
    This method will disown a selection. No callback for losing the
    selection will be activated.

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

  void GetSelection(GtWidget *w,Atom sel,Atom target,Atom dest,Time tm,
                    GtCallB cb,GtUDPtr ud)
    
    - w      : pointer to widget requesting a selection.
    - sel    : selection to get.
    - target : desired format of selection.
    - dest   : atom identifying the destination property.
    - tm     : timestamp of get request.
    - cb     : callback function to call when selection is received.
    - ud     : pointer to user data to be passed on to callback function.
    
    This method will request the contents of a selection. The callback
    function will be called when the request is performed. As callback data
    a pointer to a structure of the following form will be passed:
    
     GtSelGetCD
     {
       GtWidget *w;
       Atom sel;
       Atom type;
       int fmt;
       void *data;
       ulong len;
     }
     
     - w    : pointer to widget making the request.
     - sel  : atom identifying the selection.
     - type : atom identifying the type of the selection data. If an error
              occurred it will be "None".
     - fmt  : format of the selection data.
     - data : pointer to the selection data. The data must be copied since
              the memory containing the data will be freed after the return
              of the callback function.
     - len  : size of the selection data in <fmt> units.

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

  Atom *GetStdAtoms(void)
  
    - <result> : pointer to array of standard atoms.
    
    This method returns a pointer to an array of atoms that describe the
    standard targets for selection owners.

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

  void EnterLeave(GtWidget *w,sbool enter,ulong state)
  
    - w     : pointer to the calling widget.
    - enter : true if the mouse pointer entered the window.
    - state : state mask from a XCrossingEvent.
    
    This method is called from widgets that have the value for
    "GT_EnterLeave" set to "TRUE". The call will activate the
    "GT_EnterLeave" callback functions.
    
 ----------------------------------------------------------------------------

  long GetMCTime(void)
  
    - <result> : maximum number of millisecond between multiple clicks.
    
    This method returns the number of millisecond that may pass between
    mouse click for them to be a multiple click.

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

  XrmDatabase GetDB(void)
  
    - <result> : a resource database.
    
    This method return a resource database created from any resources
    attached as properties on the root window of a display.
