
Class documentation.

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

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

** GtWidget **
--------------

Name:       GtWidget
Superclass: GtBase
Include:    gtwidget.h


  This class is the base class of all widget classes. Instances of this
class will normally be associated with a X window to allow it to display
graphics and handle input from the user. Instances can be created without a
X window to save system resources if no input is to be processed and output
can be limited to the parent window with default colors.

  A normal widget will be provided with a GtWindow, a GtFont, a GtColormap,
a GtCursor and a number of GtGC's for default colors. The default colors are
currently six:

  * Background
    The color used to fill all normal windows with a solid pattern.
  
  * Foreground
    The color used to display text and other non-3D object.
  
  * Light
    The color used to display light parts of 3D effects and to high-light
    selections.
  
  * Dark
    The color used to display dark parts of 3D effects.
    
  * Fill
    The color used to display filled parts (like progress bars) and some
    selected entries.
    
  * Disable
    The color used to display a dithered pattern over disabled widgets
    (normally the same as foreground to save colors).
  
  All objects that can be created in a shared fashion will be shared as
default. This saves system resources but also limit the used of the objects
to read-only (no values may be changed). Any of the GtGC objects can be made
private by the widget later. 

  A widget that do not set a input events mask other than expose events can
be made windowless. If a widget is created to have no window it will have
access to it's parent's objects.

  If a widget is to be displayed and properly handled in a manager widget it
must inform it's parent that it is to be managed (by a virtual method).
Unmanaged widgets will not be handled in a layout and is normally invisible.
Any widget that is unmanaged and that have a empty event mask will be
automatically windowless and never receive events.

  Widgets are invisible until the "Build()" method is called on them. The
method is recursive over the widget tree so only one call to the "Build()"
method of the root widget of a created widget tree need to be made. If new
subtrees are created later the "Build()" method must be called on the root
of the subtree.


Tags for GtWidget:
------------------

  Name                   ISGR  Type            Defaults
  -----------------------------------------------------  
  GT_Display            (I.G.) (GtDisplay *)   NULL
  GT_Parent             (I.G.) (GtManager *)   NULL
  GT_Name               (I.G.) (char *)        "<unnamed>"
  GT_Disabled           (ISG.) (sbool)         FALSE
  GT_Position           (I...) (int)           GTP_LAST
  GT_Colormap           (I.G.) (GtColormap *)  DefaultColormap()
  GT_Visual             (I...) (Visual *)      DefaultVisual()
  GT_Depth              (I...) (ulong)         DefaultDepth()
  GT_XPos               (ISGR) (word)          0
  GT_YPos               (ISGR) (word)          0
  GT_XSize              (ISGR) (word)          1
  GT_YSize              (ISGR) (word)          1
  GT_Mapped             (I.G.) (sbool)         TRUE
  GT_Background         (ISGR) (ulong)         GTDEF_BACK
  GT_Foreground         (ISGR) (ulong)         GTDEF_FORE
  GT_Light              (ISGR) (ulong)         GTDEF_LIGHT
  GT_Dark               (ISGR) (ulong)         GTDEF_DARK
  GT_Fill               (ISGR) (ulong)         GTDEF_FILL
  GT_Disable            (ISGR) (ulong)         GTDEF_DIS
  GT_Font               (ISG.) (GtFont *)      NULL
  GT_FontList           (IS.R) (char *)        GTDEF_FONT
  GT_BackPixmap         (ISG.) (GtPixmap *)    NULL
  GT_BackXPM            (IS.R) (char *)        NULL
  GT_BackBitmap         (IS.R) (char *)        NULL
  GT_BackColor          (ISGR) (ulong)         GTDEF_BACK
  GT_Cursor             (ISG.) (GtCursor *)    NULL
  GT_EnterLeave         (ISG.) (sbool)         FALSE
  GT_WindowLess         (I.GR) (sbool)         FALSE
  GT_Window             (..G.) (GtWindow *)    NULL

  
  * GT_Display
    This tag provide the GtAppDisp to use for a widget. It is not normally
    used since the creation function provide it as an argument.

  
  * GT_Parent
    This tag provide the manager to use for the parent of a widget. It is
    not normally used since the creation function provide it as an argument.

  
  * GT_Name
    This tag provide the name of a widget. It is not normally used since
    the creation function provide it as an argument.

  
  * GT_Disabled
    If the value of this tag is true a widget is supposed to ignore user
    input. A dithered pattern will be displayed in it's window.
    NOTE: Don't confuse this with the "GT_Disable" tag that give the color
          for the pattern.

  
  * GT_Position
    The position of a widget in the parent's list of children will be
    provided by this tag. The first position (before any other widget) is 0
    (zero) and the position between the first and second widget is 1 and so
    on. The special position "GTP_LAST" will be the last position in the
    list. 


  * GT_Colormap
    This tag provide a GtColormap object to allocate the default colors
    from. If default colors is to be used it must be possible to allocate
    all of the colors from the GtColormap. If pixel values for all of the
    colors is provided no colors will be allocated from the GtColormap. By
    default the GtColormap object of the parent (or the default colormap) is
    used.


  * GT_Visual
    This tag provide a visual to use when creating the window of a widget.
    
    
  * GT_Depth
    This tag provide the depth to use when creating the window of a widget.
    
    
  * GT_XPos, GT_YPos, GT_XSize, GT_YSize
    These tags provide a position and size of a widget. If the widget is
    managed and child of a manager with a layout the values of these tags
    may be ignored.


  * GT_Mapped
    If the value of this tag is true a widget will be visible when the
    "Build()" method has been called for it.
  
  
  * GT_Background, GT_Foreground, GT_Light, GT_Dark, GT_Fill, GT_Disable
    These tags provide user allocated pixel values to use for the different
    standard colors of a widget. No color will be allocated if a pixel value
    is provided.
    NOTE: The type of the resource is a color name and not a pixel number.
    NOTE: Don't confuse this tag with "GT_Disabled" that disable a widget's
          response to user input.


  * GT_Font
    This tag provide a GtFont to be used for text in a widget.
  

  * GT_FontList
    This tag provide a string with font names separated with colon (:) or
    comma (,). A GtFont object is created from the first existing font named
    in the string.
    

  * GT_BackPixmap
    This tag provide a GtPixmap to be used as the background of the window
    of a widget. By setting this tag to "NULL" a solid background color
    will be restored to the window.
    
  
  * GT_BackXPM
    This tag provide the name of a XPM pixmap to load and use as background
    pixmap. A symbolic color name of "background" is set to allow
    "transparent" looking XPM pixmaps.
    

  * GT_BackBitmap
    This tag provide the name of a bitmap to load and use as background
    pixmap. The foreground color used to draw the bitmap will be
    "GT_BackColor" and the background color will be "GT_Background".

  
  * GT_BackColor
    This tag provide a pixel value to use as the foreground of a background
    bitmap created by "GT_BackBitmap". The color of the background bitmap
    can not be changed after the creation of the bitmap with
    "GT_BackBitmap".
    NOTE: The type of the resource is a color name and not a pixel number.


  * GT_Cursor
    This tag provide a GtCursor to use in the window of a widget.
    
    
  * GT_EnterLeave
    If the value of this tag is true a callback in the GtAppDisp object of
    a widget is activated when the mouse pointer enter or leave the widget.
    See the description of callbacks in GtAppDisp for details.
    

  * GT_WindowLess
    If the value of this tag is true and a widget has a event mask that is
    empty or only contain expose events then no window will be created for
    the widget.
   
   
  * GT_Window
    This tag will give the GtWindow of a widget.
  

Callbacks for GtWidget:
-----------------------

  Name          Callback data
  ---------------------------
  GT_Event	(GtEventCD *)
  
  
  * GT_Event
    This callback is activated for each event that arrive to a widget. Any
    handling of the event by the widget will done before the activation of
    this callback.
    
    To ensure that a certain type of event can be reported to the widget a
    call to the "SetEMask()" method with the appropriate event mask should
    be performed.

    When the callback is activated a pointer to the following structure will
    be sent to the callback as callback data:
    
     GtEventCD
     {
       sbool used;
       XEvent *xevent;
     }
     
     - used   : set this to true if the event was used by the callback and
                leave it unchanged otherwise.
     - xevent : pointer to the event that activated the callback.
     
     
Methods for GtWidget:
---------------------

   -- User methods --

  void Map(sbool map)
  sbool Build(void)
  void Move(word xp,word yp)
  void Resize(word xs,word ys)
  void MoveResize(word xp,word yp,word xs,word ys)
  void Refresh(void)
  void SetUserData(GtUDPtr ud)
  GtUDPtr GetUserData(void)
  void AddCB(ulong tag,GtCallB cb,GtUDPtr ud)
  void RemCB(ulong tag,GtCallB cb)
  void RemapColors(uword msk,ulong bg,ulong fg,
                   ulong lt,ulong dk,ulong fl,ulong ds,GtColormap *cmap)
  
    -- Internal methods --
    
  int Handle(XEvent *xe)
  sbool IsChildOf(GtWidget *o)
  sbool IsMapped(void)
  sbool IsWindowLess(void)
  sbool Manage(void)
  GtWidget *Find(char *n)
  void SetEMask(ulong em)
  sbool SetMinMaxSize(word xs,word ys,word mxs,word mys)
  void GetMinSize(int *xs,int *ys)
  void GetMaxSize(int *xs,int *ys)
  char *GetName(void)
  GtAppDisp *GetDisp(void)
  GtManager *GetParent(void)
  void SetLInfo(GtUDPtr li)
  GtUDPtr GetLInfo(void)
  GtWindow *GetWin(void)
  void Notify(ulong tag)
  void NotifyA(ulong tag,void *ptr)
  void SetPosSize(word xp,word yp,word xs,word ys)
  sbool Draw(XEvent *xe)
  sbool Key(XEvent *xe)
  sbool Mouse(XEvent *xe)
  sbool Config(XEvent *xe)
  sbool Misc(XEvent *xe)
  sbool PrivateGC(ulong tag)
  
   -- GtBase methods --

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

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

  void Map(sbool map)
  
    - map : true if a widget is to be visible.
            
    This method will show or hide the widget.

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

  sbool Build(void)
  
    - <result> : true if no errors occurred.
    
    This method will recurse through the widget tree to setup and show
    widgets.

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

  void Move(word xp,word yp)
  
    - xp : x position.
    - yp : y position.
    
    This method will try to move the widget by asking it's parent to perform
    a move.

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

  void Resize(word xs,word ys)
  
    - xs : x size.
    - ys : y size.
    
    This method will try to resize the widget by asking it's parent to
    perform a resize.

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

  void MoveResize(word xp,word yp,word xs,word ys)
  
    - xp : x position.
    - yp : y position.
    - xs : x size.
    - ys : y size.
    
    This method will try to move and resize the widget by asking it's parent
    to perform a move and resize.

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

  void Refresh(void)
  
    This method redraws the widget graphics.

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

  void SetUserData(GtUDPtr ud)
  
    - ud : pointer to user data.
    
    This method will associate a pointer with a widget. The pointer is
    unused by the widget.

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

  GtUDPtr GetUserData(void)
  
    - <result> : pointer to user data.
    
    This method returns the pointer set by "SetUserData" from a widget.

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

  void AddCB(ulong tag,GtCallB cb,GtUDPtr ud)
  
    - tag : tag identifier to select which callback list to add to.
    - cb  : pointer to a callback function.
    - ud  : pointer to user data passed to the callback function.
            
    This method will add a callback function to one of the callback lists
    provided by a widget.

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

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

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

  void RemapColors(uword msk,ulong bg,ulong fg,
                   ulong lt,ulong dk,ulong fl,ulong ds,GtColormap *cmap)
                           
    - msk  : mask of which arguments to use.
    - bg   : pixel value for background.
    - fg   : pixel value for foreground.
    - lt   : pixel value for light.
    - dk   : pixel value for dark.
    - fl   : pixel value for fill.
    - ds   : pixel value for disable.
    - cmap : pointer to GtColormap.
    
    This method will make a recursive set of all valid arguments.

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

  int Handle(XEvent *xe)

    - xe : pointer to event.
    
    - <result> : value to indicate status of event after handle (GTHR_USED,
                 GTHR_UNUSED, GTHR_SEARCH).
  
    This method will check if a event is for a widget and if it is a method
    on the widget will be called depending on the type of event. The methods
    that can be called from this method is: "Draw()", "Key()", "Mouse()",
    "Config()" or "Misc()". The selection of method to call is made from the
    following table:

     Type of Event      Method
     -------------------------
     Expose		Draw()
     GraphicsExpose	Draw()
     NoExpose		Draw()
     ConfigureNotify	Config()
     CirculateNotify	Config()
     CreateNotify	Config()
     DestroyNotify	Config()
     UnmapNotify	Config()
     MapNotify		Config()
     MapRequest		Config()
     ReparentNotify	Config()
     ConfigureRequest	Config()
     GravityNotify	Config()
     ResizeRequest	Config()
     CirculateRequest	Config()
     KeyPress		Key()
     KeyRelease		Key()
     ButtonPress	Mouse()
     ButtonRelease	Mouse()
     MotionNotify	Mouse()
     EnterNotify	Mouse()
     LeaveNotify	Mouse()
     ** OTHERS		Misc()

    After a call to one of the method the event will be passed on to any
    callback functions on the "GT_Event" callback list.
    
    From the boolean values returned from the method and the callback a
    return value is selected. If the event was not for this widget
    "GTHR_SEARCH" is returned. If the event was for this widget but booleans
    returned were false then "GTHR_UNUSED" is returned and otherwise
    "GTHR_USED" is returned. A return value of "GTHR_USED" will stop
    distribution of the the event.

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

  sbool IsChildOf(GtWidget *o)
  
   - o : pointer to a widget.
   
   - <result> : true if a widget is a child of the <o> widget.
                  
   This method will determine if a widget is a direct or indirect child of
   an other widget.

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

  sbool IsMapped(void)
  
    - <result> : true if widget is visible.
                   
    This method returns true if it is visible (or rather is supposed to be
    visible since it may be clipped or obscured by another widget).

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

  sbool IsWindowLess(void)
  
    - <result> : true if a widget has no private window.
                   
    This method returns true if a widget is windowless.
    
 ----------------------------------------------------------------------------

  sbool Manage(void)
  
    - <result> : true if a widget is to be managed by it's parent.
                   
    This method returns true if a widget is to be managed by it's parent an
    thus part of any layout. The default is managed.

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

  GtWidget *Find(char *n)
  
    - n : pointer to a name of a widget to find.
    
    - <result> : pointer to widget found or "NULL".
                   
    This method will search for a named widget and return the first found.
    There is no way to find multiple widgets with the same name.
    
 ----------------------------------------------------------------------------

  void SetEMask(ulong em)
  
    - em : event mask for a widget.
    
    This method will set the event mask of the widget.

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

  sbool SetMinMaxSize(word xs,word ys,word mxs,word mys)
  
    - xs  : minimum x size.
    - ys  : minimum y size.
    - mxs : maximum x size.
    - mys : maximum y size.
  
    - <result> : true if any change occurred.
    
    This method sets the minimum and maximum size of a widget and try to
    change it's current size to stay within the boundaries.

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

  void GetMinSize(int *xs,int *ys)

    - xs  : minimum x size.
    - ys  : minimum y size.
    
    This method will return the minimum size set by "SetMinMaxSize()".

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

  void GetMaxSize(int *xs,int *ys)

    - xs  : maximum x size.
    - ys  : maximum y size.
    
    This method will return the maximum size set by "SetMinMaxSize()".

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

  char *GetName(void)
  
    - <result> : pointer to string with widget name.
    
    This method returns a pointer to a string with a widget's name.

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

  GtAppDisp *GetDisp(void)
  
    - <result> : pointer to a GtAppDisp object.
                   
    This method returns a pointer to the GtAppDisp object used by a widget.

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

  GtManager *GetParent(void)
  
    - <result> : pointer to parent of a widget.
    
    This method returns the parent of a widget which is a manager.

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

  void SetLInfo(GtUDPtr li)
  
    - li : pointer to layout information from parent.
    
    This method sets a pointer to layout information provided by the parent.

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

  GtUDPtr GetLInfo(void)
  
    - <result> : pointer to layout information.
    
    This method returns the layout information set by "SetLInfo()".

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

  GtWindow *GetWin(void)
  
    - <result> : pointer to the GtWindow object of a widget.
    
    This method returns the GtWindow object used by a widget.

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

  void Notify(ulong tag)
  
    - tag : tag identifier to signal some change.
    
    This method is used to notify a widget of changes.

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

  void NotifyA(ulong tag,void *ptr)
  
    - tag : tag identifier to signal some change.
    - ptr : pointer to details of the change.
    
    This method is used to notify a widget of changes and to provide some
    detail information of the change.

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

  void SetPosSize(word xp,word yp,word xs,word ys)
  
    - xp : x position.
    - yp : y position.
    - xs : x size.
    - ys : y size.
    
    This method move and resize a widget and it's window. The method is
    called from the parent of a widget as a result of a move or resize
    request or as result of a layout.

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

  sbool Draw(XEvent *xe)
  
    - xe : pointer to event.
    
    - <result> : true if the event was used.
    
    This method will normally redraw a widget's graphics on expose events. 
    If the <xe> argument is "NULL" it was called as a result of a call to
    the "Refresh()" method.

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

  sbool Key(XEvent *xe)
  
    - xe : pointer to event.
    
    - <result> : true if the event was used.
    
    This method will handle key events to a widget.

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

  sbool Mouse(XEvent *xe)
  
    - xe : pointer to event.
    
    - <result> : true if the event was used.
    
    This method will handle mouse events to a widget.

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

  sbool Config(XEvent *xe)
  
    - xe : pointer to event.
    
    - <result> : true if the event was used.
    
    This method will handle changes to a widget's window.

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

  sbool Misc(XEvent *xe)
  
    - xe : pointer to event.
    
    - <result> : true if the event was used.
    
    This method will handle any type of event not covered by "Draw()",
    "Key()", "Mouse()" or "Config()".

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

  sbool PrivateGC(ulong tag)
  
    - tag : tag identifier to select which GtGC object to make private.
            
    - <result> : true if a private GtGC was created successfully.
    
    This method will create a private copy of one of the shared GtGC
    objects. After a successful call to this method the GtGC object can be
    changed freely. The possible tag identifiers are: "GT_Background",
    "GT_Foreground", "GT_Light", "GT_Dark", "GT_Fill".
