21.5 CursorTable Interface

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

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

---cursorlib: attributes ---
     load:
       (# x11ID:< (# ID: @integer do INNER exit ID #);
          macID:< (# ID: @integer do INNER exit ID #);
          ntiID:< (# ID: @integer do INNER exit ID #);
          ntiNAME:< (# ID: ^text do INNER exit ID[] #);
       ...
       #);

--- guienvlib: attributes ---
cursorTable:
  (# <<SLOT cursortablelib: attributes>>;
     init:< (* is called automatically to enable automatic load of cursors *)
       (# do INNER init #);
     create:
       (# x11ID:< (# ID: @integer do INNER exit ID #);
          macID:< (# ID: @integer do INNER exit ID #);
          ntiID:< (# ID: @integer do INNER exit ID #);
          ntiNAME:< (# ID: ^text do INNER exit ID[] #);
          cursorName: ^text;
          c: ^(*private*)cursor;
       enter cursorName[]
       ...
       #);
     define:
       (* defines the text in 'cursorName' to refer to the current
        * cursor of 'cursorRef'.  If 'cursorName' is already defined,
        * it will be redefined to refer to the cursor of 'cursorRef'.
        *)
       (# cursorName: ^text; cursorRef: ^cursor
       enter (cursorName[], cursorRef[])
       ...
       #);
     lookup:
       (* sets 'cursorRef' to refer to the cursor
        * referred to by 'cursorName'.  If 'cursorName' is not defined
        * in the cursortable, 'cursorRef' will be set to 'arrow'
        *)
       (# cursorName: ^text; cursorRef: ^cursor
       enter cursorName[]
       ...
       exit cursorRef[]
       #);
     load:
       (* reads cursor definitions from a stream
        * into the cursor table.
        *
        * If 'overwrite' is bound to 'trueObject'
        * (i.e. 'overwrite::trueObject'), then the new cursor
        * definitions will replace any previously existing cursor
        * definition with the same cursor name.
        *
        * If 'merge' is not bound to 'trueObject' - i.e. not
        * 'merge::trueObject', then clear the cursor table.
        *)
       (# cursorstream: ^stream;
          overwrite:< booleanValue;
          merge:< booleanValue;
       enter cursorstream[]
       ...
       #);
     loadFile:
       (* load the cursor definitions found in the file 'filename'
        * into the cursor table.
        *
        * If 'overwrite' is bound to 'trueObject'
        * (i.e. 'overwrite::trueObject'), then the new cursor
        * definitions will replace any previously existing cursor
        * definition with the same cursor name.
        *
        * If 'merge' is not bound to 'trueObject' - i.e. not
        * 'merge::trueObject', then clear the cursor table.
        *
        * If 'filename' is empty, or cannot be read, the result will
        * be that all cursor definitions will be erased, i.e. a way to
        * clear all existing cursor definitions is merely by executing:
        *
        *      ct.load; ('ct' assumed to be an instance of 'cursorTable')
        *)
       (# filename: ^text;
          overwrite:< booleanValue;
          merge:< booleanValue;
       enter filename[]
       ...
       #);
     scan:
       (* scans the defined cursornames in the cursor table and their cursor
        * values.
        *)
       (# currentName: ^text; currentCursor: ^cursor;
       ...
       #);
     private: @...
  #)