
Class documentation.

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

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

  ** GtColormap **
  ----------------
  
Name:       GtColormap
Superclass: GtBase
Include:    gtcolormap.h


  This class encapsulates the X colormap in a C++ object. It has methods for
all the mostly used operations on colormaps.

  Different types of GtColormaps may be created by this class. One type is
to encapsulate the default colormap of the root window. By doing this one
can easily allocate and free colors for the program. The other types of
GtColormaps create private colormaps with none or all colors allocated.

  Note that a GtDisplay object must be provided for the GtColormap to use at
creation time.


Tags for GtColormap:
--------------------

  Name           ISGR  Type            Defaults
  ---------------------------------------------
  GT_Display    (I.G.) (GtDisplay *)   -
  GT_Mode       (I.G.) (long)          GTCM_DEFAULT
  GT_Visual     (I...) (Visual *)      DefaultVisual()
  GT_DontFreeX  (I.G.) (sbool)         FALSE
  GT_XColormap  (I.G.) (Colormap)      0
  
  
  * GT_Display
    This tag provide the GtDisplay object to be used by the GtColormap. It
    is not normally used since the GtDisplay object is provided as an
    argument to the special "Init()" method of this class.


  * GT_Mode
    This tag determine what kind of GtColormap to create. Possible values are:
    
     GTCM_DEFAULT   : create a colormap from "DefaultColormap()".
     GTCM_ALLOCALL  : create new private colormap with all colors allocated.
     GTCM_ALLOCNONE : create new private colormap with no colors allocated.
  
    In GtColormaps created with "GTCM_ALLOCALL" all colors are read/write.
    
  
  * GT_DontFreeX
    If this tag is true the encapsulated colormap is not destroy when the
    GtColormap object is destroyed. For GtColormaps created with
    "GTCM_DEFAULT" this tag is always true.
    

  * GT_XColormap
    This tag provide a X colormap to encapsulate. The "GT_DontFreeX" tag is
    by default true if this tag is used in initializing the GtColormap.

    NOTE: All features of the encapsulation may not work correctly for
    objects using the "GT_XColormap" tag in initialization.
    
    
Callbacks for GtColormap:
-------------------------

  ** NONE DEFINED **
  

Methods for GtColormap:
-----------------------

   -- User methods --

  sbool AllocC(XColor *rgb)
  sbool AllocC(ulong *pix,uword r,uword g,uword b)
  sbool AllocNamedC(char *name,XColor *rgb)
  sbool AllocCells(ulong *cells,int nr,sbool cont)
  void FreeC(ulong pix)
  void StoreC(XColor *rgb)
  void StoreC(ulong pix,uword r,uword g,uword b)
  void StoreNamedC(char *name,ulong pix)
  void QueryC(XColor *rgb)
  sbool FindNamedC(char *name,XColor *rgb,XColor *trgb)
  Colormap XCm(void)

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

  sbool AllocC(XColor *rgb)

    - rgb : pointer to a XColor structure with RGB values.
    
    - <result> : true if the color was successfully allocated else false.

    This method tries to allocate a color according to the XColor structure.
    If a color was allocated it's pixel value is stored in the XColor
    structure.
  
 ----------------------------------------------------------------------------

  sbool AllocC(ulong *pix,uword r,uword g,uword b)
  
    - pix : pointer to space for the pixel value.
    - r   : red component of the color to allocate.
    - g   : green component of the color to allocate.
    - b   : blue component of the color to allocate.

    - <result> : as for "AllocC" above.
    
    This method performs the same operation as the "AllocC()" method above
    but it uses normal arguments instead of a XColor structure.
  
 ----------------------------------------------------------------------------

  sbool AllocNamedC(char *name,XColor *rgb)

    - name : pointer to a string with a color name.
    - rgb  : pointer to a XColor structure to store the allocated color
             values.
    
    - <result> : true id the color was successfully allocated else false.
    
    This method allocates a named color from the colormap and stores the
    allocated color's values in the XColor structure.
  
 ----------------------------------------------------------------------------

  sbool AllocCells(ulong *cells,int nr,sbool cont)
  
    - cells : pointer to an array of <nr> elements to store allocated pixel
              values in.
    - nr    : number of colors to allocate.
    - cont  : true if all allocated colors must be a contiguous range.
    
    - <result> : true if the colors was successfully allocated else false.

    This method allocates a number of colors for private use. The pixel
    values for the allocated colors are returned in the array provided for
    that. All allocated colors has a read/write access mode.

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

  void FreeC(ulong pix)
  
    - pix : pixel value of color to free.

    This method frees an allocated color.
  
 ----------------------------------------------------------------------------

  void StoreC(XColor *rgb)
  
    - rgb : pointer to XColor structure with RGB values.

    This method stores a new RGB value in a color cell if the cell has been
    allocated in read/write mode.
  
 ----------------------------------------------------------------------------

  void StoreC(ulong pix,uword r,uword g,uword b)
  
    - pix : pixel value of the color to set.
    - r   : red component of the color to set.
    - g   : green component of the color to set.
    - b   : blue component of the color to set.

    This method works like the "StoreC" method above but uses normal argument
    instead of a XColor structure.
  
 ----------------------------------------------------------------------------

  void StoreNamedC(char *name,ulong pix)
  
    - name : pointer to a string with a color name.
    - pix  : pixel value of the color to set.

    This method stores a new RGB value from a named color in a color cell if
    the cell has been allocated in read/write mode.
  
 ----------------------------------------------------------------------------

  void QueryC(XColor *rgb)
  
    - rgb : pointer to a XColor structure to be filled in.

    This method reads the RGB value of a color and fills in the XColor
    structure. Which color to read is set in the XColor structure before
    calling this method.

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

  sbool FindNamedC(char *name,XColor *rgb,XColor *trgb)
  
    - name : pointer to a string with a color name.
    - rgb  : pointer to a XColor structure that is fill with the RGB values
             for the color on the screen.
    - trgb : same as for <rgb> above but the RGB values are the real values
             for the color.

    - <result> : true if the color could be found else false.
    
    This method looks up the named color and fills in the two XColor
    structures. No colors are allocated.

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

  Colormap XCm(void)
  
    - <result> : X colormap that the GtColormap encapsulates.

    This method returns the encapsulated X colormap.
