ui/src/vbt/ScrnCursor.i3


 Copyright (C) 1992, Digital Equipment Corporation                         
 All rights reserved.                                                      
 See the file COPYRIGHT for a full description.                            
                                                                           
 by Steve Glassman, Mark Manasse and Greg Nelson           
 Last modified on Tue Mar 10 18:59:06 1992 by steveg   
      modified on Mon Feb 24 13:58:00 PST 1992 by muller   
      modified on Sat Dec 21 17:45:24 PST 1991 by gnelson  
      modified on Fri Sep 13  1:42:24 PDT 1991 by msm      

<*PRAGMA LL*>
A ScrnCursor.T is a handle on a cursor shape that is valid for some particular screentype, called the {\it owner} of the handle. Some handles have names; others are anonymous. A named handle is valid forever. The cursor referenced by an anonymous handle will be garbage-collected when all handles to it have been dropped.

INTERFACE ScrnCursor;

IMPORT TrestleComm, Cursor;

EXCEPTION Failure;

VAR DontCare: T;

TYPE Raw = Cursor.Raw;
See the Cursor interface for the raw representation of a cursor shape as a pair of bitmaps, color information, and hotspot offset.

\subsubsection{Obtaining handles from the oracle}

TYPE
  Oracle = Private OBJECT (*CONST*)
    width, height: INTEGER;
  METHODS
    <* LL.sup <= VBT.mu *>
    load(READONLY r: Raw; nm: TEXT := NIL): T
      RAISES {TrestleComm.Failure};
    list(pat: TEXT; maxResults: CARDINAL := 1)
      : REF ARRAY OF TEXT
      RAISES {TrestleComm.Failure};
    lookup(name: TEXT): T RAISES {TrestleComm.Failure};
    builtIn(cs: Cursor.Predefined): T;
  END;
  Private <: ROOT;
For a screentype st, the field st.cursor is an Oracle that produces cursors owned by st:

The integers st.cursor.width and st.cursor.height are the dimensions in pixels of the largest cursor image that the screentype st supports. Larger images will be cropped; smaller images will be padded.

The method call

      st.cursor.load(r, nm)
allocates and returns a cursor handle c owned by st whose contents are equal to r. If nm # NIL, c receives the name nm, and any cursor handle owned by st that previously had the name nm becomes anonymous.

The method call

      st.cursor.list(pat, maxResults)
returns the names of all cursors owned by st that match the pattern pat. The list of results may be truncated to length maxResults. A * matches any number of characters and a ? matches a single character.

The method call

      st.cursor.lookup(name)
return the cursor handle owned by st with the given name, or NIL if no cursor has this name.

The method call

      st.cursor.builtIn(cs)
returns the screen-dependent cursor valid for st that corresponds to the predefined screen-independent cursor Cursor.T{cs} .

The locking level for all methods is LL.sup <= VBT.mu.

\subsubsection{The handle object}

TYPE
  T <: Public;
  Public = OBJECT (*CONST*)
    id: INTEGER
  METHODS
    <* LL.sup <= VBT.mu *>
    localize(): Raw
      RAISES {TrestleComm.Failure, Failure};
    unload() RAISES {TrestleComm.Failure};
  END;
If cs is a ScrnCursor.T, then cs.id is an identifier whose interpretation depends on the screentype that owns cs. The method call cs.localize() returns a raw cursor equal to the one on which cs is a handle, and the method call cs.unload() causes cs to become anonymous.

END ScrnCursor.