21.4 ColorTable Interface

ORIGIN '../guienv';
BODY 'private/colorTableBody'

(* This fragment adds color-table facilities to guienv.  
 * A 'colorTable' pattern have been added. 
 *
 * colorTable
 * ----------
 *
 * This pattern defines facilities for maintaining mappings between
 * textual names of colors, and their numerical representations (in terms 
 * of 'color' values). 'colorTable' defines four functions:
 *
 * define: defines the text in 'colorName' to refer to the current
 *   color of 'colorValue'.  If 'colorName' is already defined, it
 *   will be redefined to refer to the color of 'colorValue'.
 *
 * lookup: sets the color values of 'colorValue' to the color values
 *   referred to by 'colorName'.  If 'colorName' is not defined in the
 *   colortable, 'colorValue' will be set to 'black'
 *
 * loadFile: load the color definitions found in the file 'filename' into
 *   the color table.
 *
 *   If 'overwrite' is bound to 'trueObject'
 *   (i.e. 'overwrite::trueObject'), then the new color definitions
 *   will replace any previously existing color definition with the
 *   same color name.
 *
 *   If 'merge' is not bound to 'trueObject' - i.e. not
 *   'merge::trueObject', then clear the color table.
 *
 *   If 'filename' is empty, or cannot be read, the result will be
 *   that all color definitions will be erased, i.e. a way to clear
 *   all existing color definitions is merely by executing:
 *
 *      ct.loadFile; ('ct' assumed to be an instance of 'colorTable')
 *
 * scan: scans the defined colornames in the color table and their
 *   color values.
 *
 * In multi-fragment guienv programs it can be a problem to
 * reach the single colortable instans. This problem can be 
 * solved using the object-pool. 
 * 
 * Main fragment:
 * ct:@colortable;
 * ...
 * ct[]->objectPool.put;
 * 
 * Other fragment:
 * ct:^colortable;
 * ...
 * objectPool.get(# type::<colortable; #)->ct[];
 * 
 * see basiclib reference manual p 12&23
 *)

--- guienvlib: attributes ---
colorTable:
  (# <<SLOT colortablelib: attributes>>;
     define:
       (* defines the text in 'colorName' to refer to the current
        * color of 'colorValue'.  If 'colorName' is already defined,
        * it will be redefined to refer to the color of 'colorValue'.
        *)
       (# colorName: ^text; colorValue: @color
       enter (colorName[], colorValue)
       ...
       #);
     lookup:
       (* sets the color values of 'colorValue' to the color values
        * referred to by 'colorName'.  If 'colorName' is not defined
        * in the colortable, 'colorValue' will be set to 'black'
        *)
       (# colorName: ^text; colorValue: @color
       enter colorName[]
       ...
       exit colorValue
       #);
     load:
       (* reads color definitions from a stream
        * into the color table.
        *
        * If 'overwrite' is bound to 'trueObject'
        * (i.e. 'overwrite::trueObject'), then the new color
        * definitions will replace any previously existing color
        * definition with the same color name.
        *
        * If 'merge' is not bound to 'trueObject' - i.e. not
        * 'merge::trueObject', then clear the color table.
        *)
       (# colorstream: ^stream;
          overwrite:< booleanValue;
          merge:< booleanValue;
       enter colorstream[]
       ...
       #);
     loadFile:
       (* load the color definitions found in the file 'filename'
        * into the color table.
        *
        * If 'overwrite' is bound to 'trueObject'
        * (i.e. 'overwrite::trueObject'), then the new color
        * definitions will replace any previously existing color
        * definition with the same color name.
        *
        * If 'merge' is not bound to 'trueObject' - i.e. not
        * 'merge::trueObject', then clear the color table.
        *
        * If 'filename' is empty, or cannot be read, the result will
        * be that all color definitions will be erased, i.e. a way to
        * clear all existing color definitions is merely by executing:
        *
        *      ct.load; ('ct' assumed to be an instance of 'colorTable')
        *)
       (# filename: ^text;
          overwrite:< booleanValue;
          merge:< booleanValue;
       enter filename[]
       ...
       #);
     scan:
       (* scans the defined colornames in the color table and their color
        * values.
        *)
       (# currentName: ^text; currentColor: @color;
       ...
       #);
     private: @...
  #)