# The module

    <*PRAGMA LL*>

A `ScrnCursor.T` is a handle on a cursor shape that is valid for some particular screentype, called the 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.

### 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`.

### 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.