Class: Cursor

• Inheritance
• Description
• Class protocol
  • default access
  • initialization
  • instance creation
  • standard cursors
  • styles
• Instance protocol
  • ST-80 displaying
  • accessing
  • copying-private
  • creating a device cursor
  • instance release
  • printing
  • private
  • private-accessing
  • queries
• Examples

Inheritance:

   Object
   |
   +--Cursor

Package:

stx:libview

Category:

Graphics-Support

Version:

rev: 1.129 date: 2023/06/23 15:38:15

user: cg

file: Cursor.st directory: libview

module: stx stc-classLibrary: libview

Description:

I represents cursors in a device independent manner.
Normally, cursors are defined at view creation time,
via 
    'aView cursor:aCursor'.

[Instance variables:]

    shape           <Symbol>        a shape (i.e. #arrow, #hand, ...) or nil
    sourceForm      <Form>          if shape is nil, the source bits
    maskForm        <Form>          if shape is nil, the mask bits
    hotX            <SmallInteger>  if shape is nil, the hotSpot x of the cursor
    hotY            <SmallInteger>  if shape is nil, the hotSpot y of the cursor
    device          <aDevice>       the device, if associated to one
    cursorId        <anObject>      the device-specific id if device is nonNil

[class variables:]

    Lobby           <Registry>      keeps track of known device cursors
                                    (don't use it: this will be moved to the device)

    DefaultFgColor  <Color>         default foreground color for cursors (usually black)
    DefaultBgColor  <Color>         default background color for cursors (usually white)

    NormalCursor    <Cursor>        cached instance of normal (arrow) cursor
     ...

copyright
COPYRIGHT (c) 1992 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 defaultBgColor

return the default bg color used for cursors

 defaultFgColor

return the default fg color used for cursors

 defaultFgColor: fgColor defaultBgColor: bgColor

set the default colors used for new cursors

Usage example(s):

Cursor defaultFgColor:(Color red) defaultBgColor:(Color white)

 flushDeviceCursorsFor: aDevice

unassign all cursors from their device

Usage example(s):

self flushDeviceCursorsFor:Display

 initialize

Cursor initialize

 initializeNewCursors

Create additional cursors as bitmap cursors,
if not available as native cursors on the device.
This is invoked via the startup script (display.rc)
(This is rubbish - we should keep that info on a per-device basis ...)
Cursor blank
Cursor down
Cursor execute
Cursor left
Cursor marker
Cursor normal
Cursor read
Cursor right
Cursor square
Cursor up
Cursor wait
Cursor write
Cursor thumbsUp
Cursor thumbsDown
Cursor xMarker
Cursor caret
Cursor stop
Cursor eye
Cursor eyeClosed

Usage example(s):

HandCursor := nil. self initializeNewCursors. View new cursor:(Cursor eyeClosed); open View new cursor:(Cursor eye); open View new cursor:(Cursor bullet); open

 extent: extent fromArray: array offset: offset

ST-80 compatibility
create a new bitmap cursor from bits in the array argument.
Here, the offset argument defines the hotSpot, but is given
as the negative of the hotSpot coordinate within the cursor (sigh - ST80 compatibility).

 extent: extent sourceArray: sourceArray maskArray: maskArray offset: offset

create a new bitmap cursor with mask from bits in sourceArray and
maskArray.
The offset argument defines the hotSpot, but is given as the negative
of the hotSpots coordinate within the cursor (sigh - ST80 compatibility)

 fileCursorNamed: cursorName

return a cursor read from the file's 'cursorName_bits.bit' and
'cursorName_mask.bit' - return nil if either file does not exist.
This method is going to be obsoleted in the future.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 fromImage: anImage

return a new cursor.
Source- and (optional) mask-Bits are taken from anImage;
The cursors hotSpot is the center of the image.

Usage example(s):

|i c| i := Image fromFile:'bitmaps/xpmBitmaps/cursors/ul_br_arrow.xpm'. c := Cursor fromImage:i. WindowGroup activeGroup withCursor:c do:[(Delay forSeconds:5)wait]

 fromImage: anImage hotSpot: aPoint

return a new cursor.
Source- and (optional) mask-Bits are taken from anImage;
The cursors hotSpot is given as an offset from the top-left.

Usage example(s):

|i c| i := Image fromFile:'bitmaps/xpmBitmaps/cursors/ul_br_arrow.xpm'. c := Cursor fromImage:i hotSpot:(i center). WindowGroup activeGroup withCursor:c do:[(Delay forSeconds:5)wait]

 imageArray: imageBits maskArray: maskBits

ST-80 compatible cursor creation - the extent is fixed to 16@16

Usage example(s):

|cursor| cursor := Cursor imageArray: #( 2r0000000000000000 2r0000000100001110 2r0000000100001110 2r0000000100001110 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0111111111111110 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000000000000) maskArray: #( 2r0000001110011111 2r0000001110011111 2r0000001110011111 2r0000001110011111 2r0000001110011111 2r0000001110000000 2r1111111111111111 2r1111111111111111 2r1111111111111111 2r0000001110000000 2r0000001110000000 2r0000001110000000 2r0000001110000000 2r0000001110000000 2r0000001110000000 2r0000001110000000). cursor showWhile:[ (Delay forSeconds:10) wait ]

 imageArray: imageBits maskArray: maskBits hotSpot: hot

ST-80 compatible cursor creation - the extent is fixed to 16@16

Usage example(s):

|cursor| cursor := Cursor imageArray: #( 2r0000000000000000 2r0000000100001110 2r0000000100001110 2r0000000100001110 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0111111111111110 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000100000000 2r0000000000000000) maskArray: #( 2r0000001110011111 2r0000001110011111 2r0000001110011111 2r0000001110011111 2r0000001110011111 2r0000001110000000 2r1111111111111111 2r1111111111111111 2r1111111111111111 2r0000001110000000 2r0000001110000000 2r0000001110000000 2r0000001110000000 2r0000001110000000 2r0000001110000000 2r0000001110000000) hotSpot: 8@8. WindowGroup activeGroup withCursor:cursor do:[(Delay forSeconds:10)wait]

 imageArray: imageBits maskArray: maskBits hotSpot: hot name: aString

ST-80 compatible cursor creation - the extent is fixed to 16@16

 shape: aShape

return one of the standard cursors.
Each display may offer different shapes - see for example XWorkstation
for details (however a basic minimum set should be supported by all)

 shape: aShape on: aDevice

return one of the standard cursors already associated to aDevice.
This is the same as '(Cursor shape:aShape) on:aDevice' but somwehat faster.

 sourceForm: aForm

return a new cursor.
Source- and mask-Bits are taken from aForm; hotSpot is center

 sourceForm: sourceForm maskForm: maskForm

return a new cursor. hotSpot is center

 sourceForm: sourceForm maskForm: maskForm hotSpot: aPoint

return a new cursor

 sourceForm: sourceForm maskForm: maskForm hotX: hotX hotY: hotY

return a new cursor

 arrow

return an arrow (up-left-arrow) cursor

Usage example(s):

[ WindowGroup activeGroup busyHook:nil. Cursor arrow show. Delay waitForSeconds:3. ] ensure:[ Cursor normal show. WindowGroup activeGroup showWaitCursorWhenBusyForMillis:400. ].

 blank

Answer the instance of me that is an invisible cursor.

Usage example(s):

[ WindowGroup activeGroup busyHook:nil. Cursor blank show. Delay waitForSeconds:3. ] ensure:[ Cursor normal show. WindowGroup activeGroup showWaitCursorWhenBusyForMillis:400. ].

 bottomLeft

return a bottom-left corner cursor

Usage example(s):

[ WindowGroup activeGroup busyHook:nil. Cursor bottomLeft show. Delay waitForSeconds:3. ] ensure:[ Cursor normal show. WindowGroup activeGroup showWaitCursorWhenBusyForMillis:400. ].

 bottomRight

return a bottom-right corner cursor

Usage example(s):

[ WindowGroup activeGroup busyHook:nil. Cursor bottomRight show. Delay waitForSeconds:3. ] ensure:[ Cursor normal show. WindowGroup activeGroup showWaitCursorWhenBusyForMillis:400. ].

 bullet

return a bullet cursor

Usage example(s):

Cursor bullet showWhile:[ Delay waitForSeconds:3 ] View new cursor:(Cursor bullet); open

 caret

return a caret cursor

Usage example(s):

Cursor caret showWhile:[ Delay waitForSeconds:3 ]

 corner

return a corner (bottom-right) cursor

Usage example(s):

Cursor corner showWhile:[ Delay waitForSeconds:3 ]

 cross

return a cross cursor

Usage example(s):

[ WindowGroup activeGroup busyHook:nil. Cursor cross show. Delay waitForSeconds:3. ] ensure:[ Cursor normal show. WindowGroup activeGroup showWaitCursorWhenBusyForMillis:400. ].

 crossHair

return a crossHair cursor

Usage example(s):

Cursor crossHair showWhile:[ Delay waitForSeconds:3 ]

 document

return a document cursor (dragging a document)

Usage example(s):

[ WindowGroup activeGroup busyHook:nil. Cursor document show. Delay waitForSeconds:3. ] ensure:[ Cursor normal show. WindowGroup activeGroup showWaitCursorWhenBusyForMillis:400. ].

 down

Answer the instance of me that is the shape of a down-arrow.

Usage example(s):

Cursor down showWhile:[ Delay waitForSeconds:3 ]

 downLimitArrow

return a down-arrow-to-limit cursor

Usage example(s):

Cursor downLimitArrow showWhile:[ Delay waitForSeconds:3 ]

 execute

return a execute cursor - (the default here is a wait-cursor)

Usage example(s):

Cursor execute showWhile:[ Delay waitForSeconds:3 ]

 eye

return an eye cursor

Usage example(s):

Cursor eye showWhile:[ Delay waitForSeconds:3 ]

 eyeClosed

return an eye cursor

Usage example(s):

Cursor eyeClosed showWhile:[ Delay waitForSeconds:3 ]

 folder

return a folder cursor (dragging a folder)

Usage example(s):

Cursor folder showWhile:[ Delay waitForSeconds:3 ]

 fourWay

return a four-way arrow cursor

Usage example(s):

Cursor fourWay showWhile:[ Delay waitForSeconds:3 ]

 hand

return a hand cursor

Usage example(s):

[ WindowGroup activeGroup busyHook:nil. Cursor hand show. Delay waitForSeconds:3. ] ensure:[ Cursor normal show. WindowGroup activeGroup showWaitCursorWhenBusyForMillis:400. ].

 left

Answer the instance of me that is the shape of an arrow facing to the left.

Usage example(s):

Cursor left showWhile:[ Delay waitForSeconds:3 ]

 leftHand

return a left-hand cursor

Usage example(s):

Cursor leftHand showWhile:[ Delay waitForSeconds:3 ]

 leftLimitArrow

return a left-arrow-to-limit cursor

Usage example(s):

Cursor leftLimitArrow showWhile:[ Delay waitForSeconds:3 ]

 leftRightArrow

return a left-right-arrow cursor

Usage example(s):

Cursor leftRightArrow showWhile:[ Delay waitForSeconds:3 ]

 marker

Answer the instance of me that is the shape of a horizontal arrow.

Usage example(s):

Cursor marker showWhile:[ Delay waitForSeconds:3 ]

 normal

return the normal cursor; an arrow.
for ST-80 compatibility

Usage example(s):

Cursor normal showWhile:[ Delay waitForSeconds:3 ]

 origin

return an origin cursor

Usage example(s):

Cursor origin showWhile:[ Delay waitForSeconds:3 ]

 questionMark

return a question-mark cursor

Usage example(s):

Cursor questionMark showWhile:[ Delay waitForSeconds:3 ]

 read

return a reading-file cursor (the default here is a wait-cursor)

Usage example(s):

Cursor read showWhile:[ Delay waitForSeconds:3 ]

 right

Answer the instance of me that is the shape of an arrow facing to the right.

Usage example(s):

Cursor right showWhile:[ Delay waitForSeconds:3 ]

 rightLimitArrow

return a right-arrow-to-limit cursor

Usage example(s):

Cursor rightLimitArrow showWhile:[ Delay waitForSeconds:3 ]

 stop

return a stop cursor (the default here is a wait-cursor)

Usage example(s):

Cursor stop showWhile:[ Delay waitForSeconds:3 ]

 text

return a text-cursor

Usage example(s):

Cursor text showWhile:[ Delay waitForSeconds:3 ]

 thumbsDown

return a hand cursor - ST-80 compatibility

Usage example(s):

Cursor thumbsDown showWhile:[ Delay waitForSeconds:3 ]

 thumbsUp

return a hand cursor - ST-80 compatibility

Usage example(s):

Cursor thumbsUp showWhile:[ Delay waitForSeconds:3 ]

 topLeft

return a top-left corner cursor

Usage example(s):

Cursor topLeft showWhile:[ Delay waitForSeconds:3 ]

 topRight

return a top-right corner cursor

Usage example(s):

Cursor topRight showWhile:[ Delay waitForSeconds:3 ]

 up

Answer the instance of me that is the shape of an up-arrow.

Usage example(s):

Cursor up showWhile:[ Delay waitForSeconds:5 ]

 upDownArrow

return an up-down-arrow cursor

Usage example(s):

Cursor upDownArrow showWhile:[ Delay waitForSeconds:3 ]

 upLeftArrow

return an up-right-arrow cursor

Usage example(s):

Cursor upLeftArrow showWhile:[ Delay waitForSeconds:3 ]

 upLimitArrow

return an up-arrow-to-limit cursor

Usage example(s):

Cursor upLimitArrow showWhile:[ Delay waitForSeconds:3 ]

 upRightArrow

return an up-right-arrow cursor

Usage example(s):

Cursor upRightArrow showWhile:[ Delay waitForSeconds:3 ]

 upRightHand

return an up-right-hand cursor

Usage example(s):

Cursor upRightHand showWhile:[ Delay waitForSeconds:3 ]

 wait

return a wait cursor

Usage example(s):

Cursor wait showWhile:[ Delay waitForSeconds:3 ]

 write

return a writing-file cursor (the default here is a wait-cursor)

Usage example(s):

Cursor write showWhile:[ Delay waitForSeconds:3 ]

 xMarker

Answer the instance of me that is displayed when thumb-scrolling on the x-axis.

Usage example(s):

Cursor xMarker showWhile:[ Delay waitForSeconds:3 ]

 disableThumbsCursors

self initializeNewCursors.
self disableThumbsCursors.

Instance protocol:

 displayOn: aGC at: origin clippingBox: aRectangle rule: aRule mask: aMask

ST-80 compatibility;
limited functionality: can only display bitmap cursors (yet)

 show

ST-80 mimicri: change cursors in active groups views to the receiver.

 showIn: aView

ST-80 mimicri: install the receiver as aViews cursor

 showIn: aView while: aBlock

ST-80 mimicri: change aView's cursors to the receiver, while evaluationg aBlock.
Return the value as returned by aBlock.

 showWhile: aBlock

ST-80 mimicri: change all views cursors to the receiver.
Return the value as returned by aBlock.

 device

return the device I am associated with.
Please use graphicsDevice for ST80 compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 extent

the extent in pixels

 foreground: fgColor background: bgColor

set the cursor colors

 graphicsDevice

same as #device, for ST-80 compatibility naming.
Return the device I am associated with.

 hotX

return the hotspots x-coordinate of the receiver

 hotY

return the hotspots y-coordinate of the receiver

 id

return the cursors deviceId

 maskForm

return the mask-form of the receiver

 maskForm: aForm

set the mask-form of the receiver

 shape

return the shape

 sourceForm

return the source-form of the receiver

 sourceForm: aForm

set the source-form of the receiver

 postCopy

(comment from inherited method)
this is for compatibility with ST-80 code, which uses postCopy for
cleanup after copying, while ST/X passes the original in postCopyFrom:
(see there)

 postDeepCopy

 on: aDevice

create a new Cursor representing the same cursor as
myself on aDevice; if one already exists, return the one

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 onDevice: aDevice

create a new Cursor representing the same cursor as
myself on aDevice; if one already exists, return the one

 executor

redefined to return a lightweight copy
- all we need is the device handle

 finalize

some Cursor has been collected - tell it to the display

 releaseFromDevice

I am no longer available on the device

 printOn: aStream

append a printed representation to aStream

 allocateOnDevice: aDevice

allocate a device-cursor-resource for me on aDevice

 device: aDevice

set the cursors device

 id: anId

set the cursors id

 restored

private: instance has been restored (either from snapin or binary store);
flush both device and id

 setDevice: aDevice id: anId

set the device and deviceId of the receiver

 setHotX: hx hotY: hy

set the hotspot

 setShape: aShapeSymbol

set the shape

 setSourceForm: sForm maskForm: mForm hotX: hx hotY: hy

set the forms and hotspot

 isAnimatedCursor

Examples:

    Cursor wait.
    Cursor stop.
    Cursor normal.

    Cursor extent:16@16 
           fromArray:#[ 2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000]
            offset:-8 @ -8   

    |v b cursors nextCursorAction|

    cursors := OrderedCollection new.
    cursors add:#arrow.
    cursors add:#blank.
    cursors add:#bottomLeft.
    cursors add:#bottomRight.
    cursors add:#caret.
    cursors add:#corner.
    cursors add:#cross.
    cursors add:#crossHair.
    cursors add:#document.
    cursors add:#down.
    cursors add:#downLimitArrow.
    cursors add:#execute.
    cursors add:#eye.
    cursors add:#folder.
    cursors add:#fourWay.
    cursors add:#hand.
    cursors add:#left.
    cursors add:#leftHand.
    cursors add:#leftLimitArrow.
    cursors add:#leftRightArrow.
    cursors add:#marker.
    cursors add:#normal.
    cursors add:#origin.
    cursors add:#questionMark.
    cursors add:#read.
    cursors add:#right.
    cursors add:#rightLimitArrow.
    cursors add:#stop.
    cursors add:#text.
    cursors add:#thumbsDown.
    cursors add:#thumbsUp.
    cursors add:#topLeft.
    cursors add:#topRight.
    cursors add:#up.
    cursors add:#upDownArrow.
    cursors add:#upLeftArrow.
    cursors add:#upLimitArrow.
    cursors add:#upRightArrow.
    cursors add:#upRightHand.
    cursors add:#wait.
    cursors add:#write.
    cursors add:#xMarker.

    nextCursorAction := [
        |sel c|

        cursors isEmpty ifTrue:[
            v close.
        ] ifFalse:[
            sel := cursors removeFirst.
            c := Cursor perform:sel.
            b label:sel.
            b cursor:c.
        ]
    ].

    v := StandardSystemView extent:100@100.
    b := Button origin:0.0@0.0 corner:1.0@1.0 in:v.
    b label:'default'.
    b action:nextCursorAction.
    v openAndWaitUntilVisible.

    |v|

    v := StandardSystemView extent:100@100.
    v cursor:Cursor stop.
    v open.

    |v|

    v := StandardSystemView extent:100@100.
    v cursor:(
        Cursor extent:16@16 
           fromArray:#[ 2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000]
            offset:-8 @ -8).   
    v open.

    |v|

    v := StandardSystemView extent:100@100.
    v cursor:(
        Cursor 
           extent:16@16 
           sourceArray:#[ 
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000]
           maskArray:#[ 
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r00000000 2r00000000
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r11111111 2r11111111
                        2r00000000 2r00000000
                        2r00000000 2r00000000]
            offset:-8 @ -8).   
    v open.

    |v img|

    v := StandardSystemView extent:100@100.
    img := Image fromFile:'bitmaps/xpmBitmaps/cursors/mouse.xpm'.
    v cursor:(Cursor fromImage:img).
    v open.

    |v1 v2 top|

    top := StandardSystemView new.
    top extent:300@300.
    v1 := View origin:0.0@0.0 corner:1.0@0.5 in:top.
    v1 viewBackground:(Color grey:75).
    v1 cursor:Cursor thumbsUp.
    v2 := View origin:0.0@0.5 corner:1.0@1.0 in:top.
    v2 viewBackground:(Color white).
    v2 cursor:Cursor wait.
    top open.

    Cursor wait 
        showWhile:[
            Delay waitForSeconds:5
        ]

    |v1 v2 top|

    top := StandardSystemView new.
    top extent:300@300.
    v1 := View origin:0.0@0.0 corner:1.0@0.5 in:top.
    v1 viewBackground:(Color grey:75).
    v1 cursor:(Cursor normal).

    v2 := View origin:0.0@0.5 corner:1.0@1.0 in:top.
    v2 viewBackground:(Color white).
    v2 cursor:(Cursor crossHair).
    top openAndWaitUntilVisible.

    Delay waitForSeconds:3.

    top windowGroup
        withCursor:Cursor wait 
        do:[
              Delay waitForSeconds:5
           ]

    |v1 v2 top|

    top := StandardSystemView new.
    top extent:300@300.
    v1 := View origin:0.0@0.0 corner:1.0@0.5 in:top.
    v1 viewBackground:(Color grey:75).
    v1 cursor:(Cursor normal).

    v2 := View origin:0.0@0.5 corner:1.0@1.0 in:top.
    v2 viewBackground:(Color white).
    v2 cursor:(Cursor crossHair).

    top openAndWaitUntilVisible.

    Delay waitForSeconds:3.

    v1 withCursor:Cursor wait 
       do:[
              Delay waitForSeconds:5
          ]