Class: DisplaySurface

• Inheritance
• Description
• Class protocol
  • initialization
  • queries
• Instance protocol
  • accessing
  • accessing-cursor
  • accessing-hierarchy
  • accessing-limits
  • accessing-misc
  • accessing-names
  • accessing-private
  • attributes access
  • button menus
  • clipboard
  • drawing
  • enable/disable events
  • event dispatching
  • event handling
  • event simulation
  • filling
  • initialization & release
  • keyboard commands
  • queries
  • queries-contents
  • testing
  • user interaction & notifications

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--DisplayRootView
         |
         +--SimpleView

Package:

stx:libview

Category:

Graphics-Support

Version:

rev: 1.252 date: 2023/11/29 15:23:10

user: cg

file: DisplaySurface.st directory: libview

module: stx stc-classLibrary: libview

Description:

this abstract class describes stuff common to any Window on a display
device. i.e. RootWindow, TopWindows, PopUps and Subwindows.
That is, they have a viewBackground, cursor etc. and especially events.
A special feature is the delegate field, which allows key- and button
events to be stolen from a view.
If the delegate is non-nil, these events will be sent to it instead.
So you can change a view's behavior even if it was not initially designed
for it. Also, controller functionality could be simulated using delegates.

[instance variables:]

    viewBackground  <Color|Form|Image>      the view's background

    cursor          <Cursor>                the cursor

    eventMask                               mask specifying the enabled
                                            events.

    backed                                  one of #always, #whenMapped or #never
                                            corresponds to X's backing store mechanism.
                                            May be ignored by other devices.

    flags                                   flag bits

        saveUnder                               bit 1; 1 if saveunder store for
                                                        that view is enabled

        gotExpose                               bit 2; 1 if an expose/noExpose event arrived
                                                        (for exposure handling after a scroll)

   delegate                                for event delegation

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:

 initialize

 isAbstract

Return if this class is an abstract class.
True is returned here for myself only; false for subclasses.
Abstract subclasses must redefine this again.

Instance protocol:

 addUpdateRectangle: newRectangle

return true, if the newRectangle is not already contained in the updateRegion
(i.e. if it added any pixels to the region

 application

to be redefined in real widgets.
Here nil is returned as fallback

 applicationClassName

nil if I have no application

 basicViewBackground: aColorOrFormOrViewBackground

set the viewBackground to something, a color, image or form.
The viewBackground is the color or pattern with which exposed
regions are filled - do not confuse this with the drawing background
color, which is used with opaque drawing.

 controller

return nil - I have no controller

 depth

return the depth in pixels of the view.
Notice, that this is currently the devices depth,
but support for mixed depth views is being prepared.
(especially useful on SGI, with 24bit view)

 insideColor: aColor

set the view's background color - ST-80 compatibility

 keyboardMap

by default, use my device's standard mapping.
However, subclasses may redefine this, to return their own
keyboard map (for example a terminalView may want treat CTRL-C as regular key)

 monitorScaleFactor

answer the os scale factor for the current monitor of his view,
regardless if the app is high dpi aware or not.

this is the scale factor the user did enter in the os settings,
for e.g. the user can choose between 100, 125, 150 etc.
here we return 1, 1.25 1.5

 renderer

warning: this is experimental and not yet implemented

 renderer: aRenderer

warning: this is experimental and not yet implemented

 sensor

I can only return a SynchronousWindowSensor,
since I do not have a window group

 sensorOrNil

I can only return nil,
since I do not have a window group and so there is no sensor.

 setViewBackground

install the viewBackground for the receiver on the device

 updateRegion

 updateRegion: aCollectionOfRectanglesOrNil

Modified (format): / 26-10-2023 / 19:41:41 / Stefan Vogel

 viewBackground

return the viewBackground

 viewBackground: aColorOrFormOrViewBackground

set the viewBackground to something, a color, image or form.
The viewBackground is the color or pattern with which exposed
regions are filled - do not confuse this with the drawing background
color, which is used with opaque drawing.

 viewBackgroundAndClear: aColorOrImageOrForm

set the viewBackground to aColorOrImageOrForm, a color, image or form.
and clear the View.
The viewBackground is the color or pattern with which exposed
regions are filled - do not confuse this with the drawing background
color, which is used with opaque drawing.

 viewGravity

return the view's gravity

 widget

ST-80 compatibility

 windowClass: classString name: nameString

 windowGroup

return nil - I have no windowGroup

 windowName: aString

 cursor

return the view's cursor

 cursor: aCursor

set the view's cursor. This cursor will be automatically displayed whenever
the mouse-pointer enters the receiver.
Cursors are typically set at view creation time and left as installed.

Usage example(s):

|v| v := View new. v cursor:(Cursor wait). v open. [v shown] whileFalse:[Processor yield]. [v shown] whileTrue:[ (Delay forSeconds:1) wait. v cursor:(Cursor normal). (Delay forSeconds:1) wait. v cursor:(Cursor wait). ]

 cursor: aCursor now: showImmediately

set the view's cursor. This cursor will be automatically displayed whenever
the mouse-pointer enters the receiver.
Cursors are typically set at view creation time and left as installed.
The showImmediately parameter controls if the request is to be buffered,
or enforced immediately. Under XWindows, that makes a performance difference if many
cursors (a whole group) are set, because the setting involves an XServer round trip.

Usage example(s):

|v| v := View new. v cursor:(Cursor wait). v open. [v shown] whileFalse:[Processor yield]. [v shown] whileTrue:[ (Delay forSeconds:1) wait. v cursor:(Cursor normal). (Delay forSeconds:1) wait. v cursor:(Cursor wait). ]

 setCursor

 withCursor: aCursor do: aBlock

evaluate aBlock showing aCursor until ready; then restore the old cursor
and return the value as returned by aBlock.

Notice, that this method only changes the cursor for a SINGLE (sub-)view.
Most applications want to have the cursor changed in all of its views.
Use 'aView windowGroup withCursor:do:' or 'aView topView withCursor:do:'
to accomplish this.

 withExecuteCursorDo: aBlock

evaluate aBlock while showing an execute cursor in all my views.
Return the value as returned by aBlock.

 withReadCursorDo: aBlock

evaluate aBlock while showing a readCursor in all my views.
Return the value as returned by aBlock.

 withVisibleCursor: aCursor do: aBlock

evaluate aBlock, showing a aCursor.
Return the value of aBlock.
Ensure, that the cursor is visible for the user for a minimal amount of time (100ms)
(even if the computation would be too quick for a cursor to be visible,
show the execute cursor for some time as a feedback).

 withWaitCursorDo: aBlock

evaluate aBlock while showing a waitCursor in all my views.
Return the value as returned by aBlock.

 withWriteCursorDo: aBlock

evaluate aBlock while showing a writeCursor in all my views.
Return the value as returned by aBlock.

 delegate

return the delegate - that's the one getting keyboard and button events.
See dispatchEvent:... method

 delegate: someOne

set the delegate - keyboard- and button events will be forwarded to
that object if it is interested in them.
See the dispatchEvent... method.

 subViews

** This method must be redefined in concrete classes (subclassResponsibility) **

 superView

return the superView - nil here

 topComponent

return the topView - that the one with no superview

 topView

return the topView - that's the one with no superview

 maxExtent

return the view's maximum extent - this is nil here.
Only standardSystemViews support this.

 maxExtent: extent

set the view's maximum extent - ignored here.
Only standardSystemViews support this.

 minExtent

return the view's minimum extent - this is nil here.
Only standardSystemViews support this.

 minExtent: extent

set the view's minimum extent - ignored here.
Only standardSystemViews support this.

 automationUUID

return my uuid (for automation and the polonium st/x capture/replay tool).
This is a widget id, as specified in the uispec (if it is defined there).
Will be the same for all instances
(i.e. the same in different instances of the application).
Contrast this with the instanceUUID, which is unique for each view.

Notice: old uiSpecs do not provide/define a uuid, and nil is returned;
so the application's specs must be re-edited and saved again.

Usage example(s):

Transcript topView automationUUID Transcript topView instanceUUID

 automationUUID: aUuidOrUuidString

set my uuid (for automation and the pollonium st/x capture/replay tool).
This is a widget id, as specified in the uispec (if it is definedthere).
Will be the same for all instances
(i.e. the same in different instances of the application).
Contrast this with the instanceUUID, which is unique for each view.

Notice: old uiSpecs do not provide/define a uuid, and nil is returned from automationUUID;
so the application's specs must be re-edited and saved again.

 backingStore: how

turn on/off backingStore (saving my pixels)
how may true/false, but also #always, #whenMapped or #never.

 eventMask

return a (numeric) mask of allowed events -
this is X-specific and will be removed / replaced by symbolic values)

 eventMask: aMask

set a (numeric) mask of allowed events -
this is X-specific and will be removed / replaced by symbolic values)

 getKeyboardFocus

tell the Display to assign keyboard focus to the receiver

 instanceUUID

return my unique uuid.
This will be assigned once and only once per instance
(i.e. the same type of view within different applications will
have different instanceUUIDs)

 isInputOnly

return true, if the receiver is an input only view - that is:
the view will realize as a transparent view, into which you cannot
draw, but get events as usual. Thich can be used to catch events away from
others, which where never meant to work in such a setup.
(for example, if you want to manipulate views in some DrawTool-like manner).
This uses a special X feature, which might not be supported in the near future
or on other plattforms.

 preferredDepth

return a non nil integer, if a specific depth is wanted in this view.
Return nil if we do not care (i.e. the display's default is wanted).
This is experimental and may change/vanish - do not use it.

 preferredVisual

return a non nil id, if a specific visual is wanted in this view.
Return nil if we do not care (i.e. the display's default is wanted).
This is experimental and may change/vanish - do not use it.

 saveUnder

return the saveUnder flag

 saveUnder: aBoolean

turn on/off saveUnder (saving pixels under myself)
- used for temporary views (i.e. PopUps and ModalBoxes)

 setPointerPosition: aRelativePoint

set the pointer to aRelativePoint relative to the view's origin.
Warning: moving the mouse pointer may lead to the mouse falling off the table
after a while. So it should be used very very seldom (if at all)

Usage example(s):

Transcript setPointerPosition:Transcript extent // 2. Screen current rootView setPointerPosition:100@100.

 uuid

Transcript topView uuid
Transcript topView instanceUuid


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

 uuid: aUuidOrUuidString

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

 icon

return the view's icon - this is nil here.
Only standardSystemViews support labels and icons.

 icon: aBitmap

set the view's icon - ignored here.
Only standardSystemViews support labels and icons.

 iconLabel

return the view's icon label.
This is nil here.
Only standardSystemViews support labels and icons.

 iconLabel: aLabel

set the view's icon label.
Ignored here.
Only standardSystemViews support labels and icons.

 iconMask

return the view's iconMask - this is nil here.
Only standardSystemViews may support labels and icons.

 iconView

return the view's iconView - this is nil here.
Only standardSystemViews support labels and icons.

 iconView: aView

set the view's icon view - ignored here.
Only standardSystemViews support labels and icons.

 label

return the view's label - this is nil here

 label: aLabel

set the view's label.
Ignored here.

 label: aLabel iconLabel: iconLabel

set both the label and the iconLabel.
Ignored here.

 clearGotExposeFlag

internal; used to wait for an expose-event after a scroll operation

 gotExpose

internal; used to wait for an expose-event after a scroll operation

 setGotExposeFlag

internal; used to wait for an expose-event after a scroll operation

 getAttribute: key

 objectAttributes

return a Collection of attributes - nil if there is none.

 objectAttributes: aDictionary

(comment from inherited method)
set the collection of attributes.

The default implementation here uses a global Dictionary to store
attributes which may be too slow for high frequency change&update.
Therefore, some classes may redefine this for better performance.

 setAttribute: key to: newValue

 getMiddleButtonMenu

return the menu associated with the middle mouse button.
This is a possibly obsolete hook for views which do not define their own menu,
but are configured from the outside. Nowadays, widgets provide their own menu
or are configured using a menuHolder.

 middleButtonMenu

return the menu associated with the middle mouse button.
Here, return a hooked on menu, but usually redefined to provide a widget-specific
menu.

 middleButtonMenu: aMenu

associate aMenu with the middle mouse button.
This is a possibly obsolete hook for views which do not define their own menu,
but are configured from the outside. Nowadays, widgets provide their own menu
or are configured using a menuHolder.

 setMiddleButtonMenu: aMenu

associate aMenu with the middle mouse button.
Do not destroy the old menu if any

 getClipboardObject

return the object selection
- either the local one, or the display's clipBoard buffer.

 getClipboardText

return the copyBuffers contents
- either the local one, or the display's clipBoard buffer.

 getClipboardText: selectionBufferSymbol

return the clipboard or text selection - either the local one,
or one of the display's clipBoard buffers determined by selectionBufferSymbol,
which should be one of:
#clipboard
or:
#selection.

Return aString or nil if there is no selection

 getSelection

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

 getTextSelection

return the copyBuffers contents
- either the local one, or the display's clipBoard buffer.

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

 getTextSelection: selectionBufferSymbol

return the text selection - either the local one, or one of the display's
clipBoard buffers determined by selectionBufferSymbol, which should be one of:
#clipboard
or:
#selection.

Return aString or nil if there is no selection

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

 setClipboardObject: anObject

set the object selection - both the local one, and tell the display
that we have changed it (i.e. place it into the clipBoard).

 setClipboardText: aStringOrStringCollection

set the text selection - both the local one, and tell the display
that we have changed it (i.e. place it into the clipBoard).

 setSelection: anObject

set the object selection - both the local one, and tell the display
that we have changed it (i.e. place it into the clipBoard).

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

 setTextSelection: aStringOrStringCollection

set the text selection - both the local one, and tell the display
that we have changed it (i.e. place it into the clipBoard).

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

 fillDeviceRectangleWithPattern: aPixmap x: xIn y: yIn width: wIn height: hIn patternOffset: pattOffs

fill a rectangular area with some pattern.
A helper for devices which do not support pixmap drawing (i.e. win95).
This is never invoked with X11 or Win-NT/XP/Vista systems.
Caller must ensure that aPixmap is really a form.
CG: mhm it seems that XQuartz has a bug and also has problems doing this.
therefore it is actually not obsolete.

 fillRectangleWithPattern: aPixmap x: x y: y width: w height: h patternOffset: pattOffs

fill a rectangular area with aPixmap.
A helper for devices which do not support pixmap filling (i.e. win95 screens).
This is never invoked with X11 or Win-NT/XP/Vista systems.
Caller must ensure that the aPixmap is really a form.
CG: mhm it seems that XQuartz has a bug and also has problems doing this.
therefore it is actually not obsolete.

 flashRectangle: rect

flash part of the view - fill it flashColor, then white,
finally redraw.
Can be used to bring attention to some line/part of view

Usage example(s):

Display rootView flashRectangle:(10@10 corner:100@100) Display rootView flashRectangle:(100@100 corner:200@300)

 redraw

nothing done here

 compressMotionEvents: aBoolean

enable/disable motion event compression
(i.e. replacing all motion events by the last one).
Compression makes almost always sense, except when
doing things like freehand drawing

 disableButtonEvents

disable all button events

 disableButtonMotionEvents

disable button motion-while-button-is-pressed events

 disableButtonPressEvents

disable button press events

 disableButtonReleaseEvents

disable button release events

 disableEnterLeaveEvents

disable both mouse-pointer enter and leave events

 disableEvent: anEventSymbol

disable an event -
this is a private (internal) method not to be used externally.
for a list of allowed event symbols see Workstation class

 disableMotionEvents

disable mouse-pointer motion events

 enableButtonEvents

enable both mouse button press and release events.
These are enabled by default anyway.

 enableButtonMotionEvents

enable mouse-pointer motion-while-button-is-pressed events.
These are enabled by default anyway.

 enableButtonPressEvents

enable mouse button press events.
These are enabled by default anyway.

 enableButtonReleaseEvents

enable mouse button release events.
These are enabled by default anyway.

 enableEnterEvents

enable mouse-pointer enter events

 enableEnterLeaveEvents

enable both mouse-pointer enter and leave events

 enableEvent: anEventSymbol

enable an event -
this is a private (internal) method not to be used externally.
for a list of allowed event symbols see Workstation class

 enableFocusEvents

enable keyboard focus change events

 enableKeyEvents

this is a compatibility leftover -
starting with 2.10.3, keyPress is always enabled to allow
^C processing.

 enableKeyPressEvents

this is a compatibility leftover -
starting with 2.10.3, keyPress is always enabled to allow
^C processing.

 enableKeyReleaseEvents

enable key release events

 enableLeaveEvents

enable mouse-pointer leave events

 enableMotionEvents

enable mouse-pointer motion events (those without a pressed button)

 dispatchEvent: event

dispatch an event

 dispatchEvent: type arguments: arguments

dispatch an event.
Obsoleted - now we always pass around event objects.

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

 dispatchEvent: ev type: type arguments: argArrayIn withFocusOn: focusView delegate: doDelegate

dispatch the event represented by type and arguments either to my delegate,
or to my controller (which may be myself, if I implement the controller functionality myself).
If focusView is nonNil, and it is a keyboard event, it is forwarded to this
view (but not if there was a delegate in the first place).

If doDelegate is true, keyboard and button events are forwarded to a
delegate object (if non-nil). DoDelegate may be passed as true, to
handle events which are already delegated.
If there is a delegate, only messages which are understood by it are
forwarded. Also, the delegate is asked if it is willing to handle the event
before.
Delegated messages get the original view as an extra argument.
Delegation has higher priority than both controller or focusView
forwarding.

 dispatchEvent: event withFocusOn: focusViewOrNil

dispatch the event

 dispatchEvent: event withFocusOn: focusViewOrNil delegate: doDelegate

dispatch the event

 activateMenu

if there is a menu, show it.

 activateMenu: aMenu

if aMenu is a menu, show it.

 buttonMotion: state x: x y: y

mouse was moved while button is pressed - do nothing here

 buttonMultiPress: button x: x y: y

button was pressed fast after previous press - default to press-again

 buttonPress: button x: x y: y

button was pressed - if it's middle button and there is a menu, show it.

 buttonRelease: button x: x y: y

 buttonShiftPress: button x: x y: y

button was pressed - if it's middle button and there is a menu, show it.
Nothing is done here. Subclasses may redefine this.

 catchExpose

this MUST be sent BEFORE doing a bit-blt copy (i.e. copyFrom...),
to tell the sensor that incoming expose events are to be remembered.
Sometime after the bit-blt, waitForExpose should be sent, to finally
suspend until the expose/noExpose event arrives.
This is an X speciality - for devices that do not need this kind of
asynchronous bit-blt confirmation, this is a noop.
(well, the windows interface simulates it as well)
Answer true if the sender is required to do a waitForExpose, false if not.

 coveredBy: aView

the receiver has been covered by another view;
we are not interested in that here (but see modalBox for more).

 deviceButtonMotion: state x: x y: y

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a #buttonMotion with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonMotion:x:y:

 deviceButtonMultiPress: butt x: x y: y

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a buttonMultiPress with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonMultiPress:x:y:

 deviceButtonPress: butt x: x y: y

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a buttonPress with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonPress:x:y:

 deviceButtonRelease: butt x: x y: y

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a buttonRelease with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonRelease:x:y:

 deviceButtonShiftPress: butt x: x y: y

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a buttonShiftPress with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonShiftPress:x:y:

 deviceExposeX: x y: y width: w height: h

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send an expose with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #exposeX:x:y:width:height:

 deviceGraphicsExposeX: x y: y width: w height: h final: final

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a graphicsExpose with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #graphicsExposeX:x:y:width:height:

 deviceKeyPress: key x: x y: y

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a keyPress with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #keyPress:x:y:

 deviceKeyRelease: key x: x y: y

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a keyRelease with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #keyRelease:x:y:

 devicePointerEnter: state x: x y: y

this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a pointerEnter with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #pointerEnter:x:y:

 exposeX: x y: y width: w height: h

an expose event - nothing done here

 focusIn

got keyboard focus - do nothing here

 focusOut

lost keyboard focus - do nothing here

 graphicsExposeX: x y: y width: w height: h final: final

an expose event after a scroll - do normal redraw processing

 handlesMouseWheelMotion: event inView: aView

we do not handle delegated mousewheel events - subclasses may handle them

 hotkeyWithId: aId rawKey: aKey

default action is to do nothing - may be reimplemented

 keyPress: key x: x y: y

a key was pressed in this view.
Here only keyCommands are handled - more action has to
be implemented by redefining this method

 keyRelease: key x: x y: y

default action is to do nothing

 mouseWheelMotion: buttonState x: x y: y amount: amount deltaTime: dTime

ignored

 noExpose

a no expose event after a scroll (event-mode only)

 pointerEnter: state x: x y: y

mouse cursor entered view - do nothing here

 pointerLeave: state

mouse cursor left view - do nothing here

 resizeRequest

initionally does nothing

 waitForExpose

wait until an expose event arrives (to wait for scroll-finish)