Class: WindowSensor

• Inheritance
• Description
• Class protocol
  • accessing
  • event processing
  • initialization
  • instance creation
  • queries
• Instance protocol
  • Compatibility-ST80
  • accessing
  • accessing-private
  • event flushing
  • event processing
  • event processing-private
  • event queue
  • event simulation
  • initialization
  • queries-event queue
  • queries-key & button state
  • queries-pointer
  • special

Inheritance:

   Object
   |
   +--WindowSensor
      |
      +--SynchronousWindowSensor

Package:

stx:libview

Category:

Interface-Support-UI

Version:

rev: 1.388 date: 2024/04/28 08:09:53

user: cg

file: WindowSensor.st directory: libview

module: stx stc-classLibrary: libview

Description:

Instances of this class keep track of events and damage areas for a group of 
views. All incoming expose rectangles and events (from Workstation) are 
collected here, until someone (usually the windowGroup process)
gets a chance to handle them. 
In contrast to ST-80 (which has one windowSensor per window), ST/X usually
only assigns one sensor per windowGroup.
(however, you could manually arrange for per view private sensors - at least, theoretically)

When adding an expose rectangle, WindowSensor tries to merge the rectangle 
with the list of existing damages to minimize redrawing.

Processing of compose key sequences is done here; if a Compose
key event arrives, the following 2 characters are used to search an
entry in the composeTable, and are replaced by the character found there.
For example, pressing Compose-a-` gives the french a-accent-grave character;
pressing Compose-a-e gives the ae ligature.

Beside the above, windowSensors provide facilities (hooks) to allow
so-called 'eventListeners' to get the event before it is entered into
the queue. There are 4 possible listening hooks available:

    global EventListener - get keybd/mouse/focus/enter-leave events for all views and all displays
    per-display eventListener - gets only keybd/mouse/focus/enter-leave events for one display (see GraphicsDevice)
    per-sensor eventListener - gets only keybd/mouse/focus/enter-leave events for this sensor's windowGroup
    per-sensor keyboardListener - only gets keyboard events for this sensor's windowGroup

(actually, there are two more mechanisms, event delegation which allows
 delegation of key- and buttonEvents of a specific view,
 and per-windowGroup eventHooks)

Global eventListeners are installed via a class method (addEventListener:) to
the WindowSensor class; local listeners are installed via instance methods.
A listener may return true to signal that it has handled the event and that the
event should NOT be enqueued. 
Likewise, if it returns false, the event is processed as usual 
(i.e. enqueued and forwarded to the view's controller).
If there are multiple listeners, all of them get a chance to process the event,
but it will not be enqueued, if any returned true.

The global listeners are called before any local listener, which are called
before any keyboard listeners. 
If any listener-group has eaten the event, later (local) listeners wont get the event.

EventListeners have been added to allow the implementation of event recorders,
screen savers or other spy functionality. 
They also allow hooking up views which otherwise insist on doing things themself.

Notice, that beside event listening, you can also define a delegate for
a view's keyboard and button events. 
Read the documentation in WindowEvent for more info.

NOTICE: in previous releases, only one listener was allowed, which was notified
via #buttonPress/#buttonRelease ... invocations.
We have changed this to allow multiple handlers, and also to pass the event to a single
#handleEvent method.

[instance variables:]
    eventSemaphore          <Semaphore>     the semaphore to be signalled when an event
                                            (or damage) arrives

    damage                  <Collection>    collection of damage events

    mouseAndKeyboard        <Collection>    collection of user events

    compressMotionEvents    <Boolean>       if true, multiple motion events are
                                            compressed to one event. If false, each
                                            event is handled individual.
                                            (should be set to false when doing free-hand drawing)

    ignoreUserInput         <Boolean>       if true, key & button events are ignored
                                            (usually set to true by WindowGroup, while a
                                             modalbox covers a view)

    shiftDown               <Boolean>       true while shift/meta/control-key is pressed
    metaDown                                (to support ST-80 style query: sensor shiftDown)
    ctrlDown
    altDown                                 (notice, that on most systems, alt and meta key is
                                             the same, both reported as #Alt)

    exposeEventSemaphore    <Semaphore>     X-special: semaphore to be signalled when
                                            expose event arrives after a copyArea.

    catchExpose             <SetOfView>     if nonEMpty, the drawables which wait for
                                            an expose/noExpose event.  (after a copyArea)

    gotExpose               <SetOfView>     the set of drawables which got an expose/noExpose
                                            event.  (after a copyarea)

    gotOtherEvent           <SetOfView>     set of drawables which received if other events,
                                            while waiting for expose (after a copyarea).

    translateKeyboardEvents <Boolean>       if true, keyboard events are translated via
                                            the devices leyboardMap; if false, they
                                            are reported as raw-keys. Default is true.


    eventListeners          <Collection>    Collection of new event listeners.
                                            Each will be sent a #handleEvent: message.
                                            The event will not be enqueued, if any returns
                                            true.

    accessLock              <Semaphore>     controls access to the event queues

[class variables:]

    ControlCEnabled         <Boolean>       if true (which is the default) Control-C
                                            will interrupt the process handling the
                                            view.
                                            For secure stand-alone applications,
                                            this can be set to false, in which case 
                                            Control-C does NOT interrupt the process.
                                            (actually, Control-C is wrong here; the actual
                                             key is #UserInterrupt, which may be mapped onto
                                             any key)

    ControlYEnabled         <Boolean>       if true (which is the default) Control-Y
                                            will raise the abortSignal in the process 
                                            handling the view.
                                            This can be used to abort a long operation
                                            (such as a long fileRead in the fileBrowser)
                                            without entering the debugger.
                                            (actually, Control-Y is wrong here; the actual
                                             key is #UserAbort, which may be mapped onto
                                             any key)

    EventListeners          <Collection>    Collection of new event listeners.
                                            Each will be sent a #handleEvent: message.
                                            The event will not be enqueued, if any returns
                                            true.

    ComposeTable            <Array>         compose-key translation table

copyright
COPYRIGHT (c) 1993 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:

 addEventListener: aListener

add a global eventListener (with new protocol - #handleEvent:)
This one gets a chance to intercept all events for ANY sensor
(i.e. any view on any device).
Warning: the listener gets invoked synchronously, directly from the
display event dispatcher. It shall not terminate or block the system for long.
See documentation for what this can be used for

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

 addSynchronousEventListener: aListener

add a global eventListener (with new protocol - #handleEvent:)
This one gets a chance to intercept all events for ANY sensor
(i.e. any view on any device).
Warning: the listener gets invoked synchronously, directly from the
display event dispatcher. It shall not terminate or block the system for long.
See documentation for what this can be used for

 composeTable

return the compose-key table.
Entries consist of 3-element arrays each, where
the first two entries (of each entry) are the raw characters,
and the third is the resulting composed-key

 composeTable: aTable

set the compose-key table.
Entries consist of 3-element arrays each, where
the first two entries (of each entry) are the raw characters,
and the third is the resulting composed-key

 controlCEnabled: aBoolean

enable/disable Control-C processing.
If enabled, pressing CNTL-C in a view will interrupt it and bring
its process into the debugger (actually raising a UserInterrupt signal).
Otherwise, CNTL-C is sent to the view like any other key.
The default is true (enabled).
Be very careful - only disable CNTL-C handling for well-debugged
applications ... however, even if disabled, there still is the CNTL-C
key on the startup (x)-terminal window (which can also be disabled).

 controlPeriodEnabled: aBoolean

enable/disable Control-. processing.
If enabled, pressing CNTL-. is handled like UserInterrupt and will usually interrupt it.
Notice, that this flag only controls the translation of CTRL-. to CTRL-C;
UserInterrupts may still be disabled by other flags.

 deadKeyEatsSpace

return true if dead-key space should eat the space

Usage example(s):

WindowSensor deadKeyEatsSpace

 deadKeyEatsSpace: aBoolean

return true if dead-key space should eat the space

Usage example(s):

WindowSensor deadKeyEatsSpace:false WindowSensor deadKeyEatsSpace:true

 deadKeyLanguage

return the per language default for deadKey handling.
(see CharacterArray)

Usage example(s):

WindowSensor deadKeyLanguage WindowSensor deadKeyLanguage:'de'. WindowSensor deadKeyLanguage:nil. WindowSensor deadKeyLanguage:'fr'.

 deadKeyLanguage: aLanguageString

set to only use per-language dead keys
(see CharacterArray).
If set to nil, you all dead keys will be recognized;
if set to a language ('de', 'fr', 'es', 'nl', etc),
only deadkeys relevant for that language are recognized.
This is work in progress.

Usage example(s):

WindowSensor deadKeyLanguage:nil. WindowSensor deadKeyLanguage:'de'. WindowSensor deadKeyLanguage:'fr'.

 deadKeysEnabled

return the default for deadKey handling.

Usage example(s):

WindowSensor deadKeysEnabled

 deadKeysEnabled: aBoolean

set the default for deadKey handling.

Usage example(s):

WindowSensor deadKeysEnabled:true. WindowSensor deadKeysEnabled:false.

 eventListeners

 removeEventListener: aListener

remove a global eventListener (with new protocol - #handleEvent:)
- see documentation for what this can be used for

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

 removeSynchronousEventListener: aListener

remove a global eventListener (with new protocol - #handleEvent:)
- see documentation for what this can be used for

 postViewCreateNotification: aView

invoked right before a new view is created.
Notify listeners and allow for the origin/extent to be
changed. (For example, recorder/playback applications may
want to make certain that the playback view is at the same
position - or record any origin changes to translate later
synthetic events).

 preViewCreateNotification: aView

invoked right before a new view is created.
Notify listeners and allow for the origin/extent to be
changed. (For example, recorder/playback applications may
want to make certain that the playback view is at the same
position - or record any origin changes to translate later
synthetic events).

 initialize

initialize the classes constants

Usage example(s):

self initializeComposeKeyTable

Usage example(s):

WindowSensor initialize

 initializeComposeKeyTable

setup the composeKey table

Usage example(s):

WindowSensor initializeComposeKeyTable

 mouseWheelScale

if set, mouse wheel motions are scaled by this number

 mouseWheelScale: aNumber

if set, mouse wheel motions are scaled by this number

 mouseWheelThreshold

if set, mouse wheel motions are only reported if the scaled amount is above this

 new

return a new initialized instance

 cursorPoint

ST-80 compatibility:
return the position of the cursor on the current display.

Usage example(s):

WindowSensor cursorPoint

Instance protocol:

 blueButtonPressed

ST-80 compatibility: return true, if the right mouse button is pressed.
You should no use it in 'normal' applications.
Instead, keep track of the buttons state in your views or controllers
button-event methods.

 eventQuit: event

ST-80 compatibility:
push an event for terminating the topViews application

 mousePointForEvent: anEvent
( an extension from the stx:libcompat package )

 redButtonPressed

ST-80 compatibility: return true, if the left mouse button is pressed.
You should no use it in 'normal' applications.
Instead, keep track of the buttons state in your views or controllers
button-event methods.

 yellowButtonPressed

ST-80 compatibility: return true, if the middle mouse button is pressed.
You should no use it in 'normal' applications.
Instead, keep track of the buttons state in your views or controllers
button-event methods.

 addEventListener: aListener

add a local eventListener (with new protocol - #processEvent:)
This one gets a chance to intercept all events for this sensor
(i.e. for this windowGroup).
Warning: the listener gets invoked synchronously, directly from the
display event dispatcher. It shall not terminate or block the system for long.
See documentation for what this can be used for

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

 addSynchronousEventListener: aListener

add a local eventListener (with new protocol - #processEvent:)
This one gets a chance to intercept all events for this sensor
(i.e. for this windowGroup).
Warning: the listener gets invoked synchronously, directly from the
display event dispatcher. It shall not terminate or block the system for long.
See documentation for what this can be used for

 compressMotionEvents: aBoolean

turn on/off motion event compression.
Normally, motion event compression is enabled; however,
applications which want to follow every motion
(i.e. paint-like applications) may want to get them all)

 deadKeysEnabled

return true if deadkeys are enabled (to combine diacriticals)

 deadKeysEnabled: aBoolean

set to true to enable deadkeys (to combine diacriticals)

 eventSemaphore

return the semaphore used to signal event arrival

 eventSemaphore: aSemaphore

set the semaphore used to signal event arrival

 ignoreExposeEvents: aBoolean

turn on/off expose event ignoring

 ignoreUserInput

return true, if user events are currently ignored

 ignoreUserInput: aBoolean

turn on/off ignoring of user events processing.
This can be used to avoid having events queued for a master-view,
while a modal dialog is open for it.

 lastEvent

 removeAllEventListeners

remove all local eventListeners

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

 removeAllSynchronousEventListeners

remove all local eventListeners

 removeEventListener: aListener

remove a local eventListener (with new protocol - #processEvent:)
- see documentation for what this can be used for

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

 removeSynchronousEventListener: aListener

remove a local eventListener (with new protocol - #processEvent:)
- see documentation for what this can be used for

 criticalDamageEventQueueAccess: aBlock

perform some action which needs synchronized (exclusive)
access to the damage event queue.
(i.e. protected by a critical region)

 criticalEventQueueAccess: whichLock do: aBlock

perform some action which needs synchronized (exclusive)
access to one of the event queues.
(i.e. protected by a critical region)

 criticalUserEventQueueAccess: aBlock

perform some action which needs synchronized (exclusive)
access to the user event queue.
(i.e. protected by a critical region)

 damageEventAccessLock

return the semaphore which controls access to the damage event queue.
This should probably not be exposed to the public,
so be prepared that this method may vanish.

 userEventAccessLock

return the semaphore which controls access to the mouse and keyboard event queue.
This should probably not be exposed to the public,
so be prepared that this method may vanish.

 compressKeyPressEventsWithKey: aKey

count and remove multiple pending keyPress events for the
same key, aKey. This is currently used in TextViews to compress
multiple cursorUp/cursorDown events and do the scroll in one
operation. (to avoid run-after-cursor on slow displays)

 flushAllEvents

 flushButtonEventsFor: aView

throw away all pending mouse button events for aView,
or any view, if the argument is nil.

 flushEventsFor: aView

throw away all events for aView,
or any view, if the argument is nil.

 flushEventsFor: aViewOrNil inQueue: anEventQueue where: aCondition

throw away all pending events in anEventQueue for aView,
for which aCondition returns true.
Or any view for which aCondition returns true, if the argument is nil.
A helper for the various flush entries.
Returns the last flushed event or nil.

 flushEventsFor: aViewOrNil inQueue: anEventQueue withType: eventType

throw away all pending events in anEventQueue for aView,
which have a type of eventType.
A helper for the various flush entries.
Returns the last flushed event or nil.

 flushEventsFor: aViewOrNil where: aBlock

throw away all events for aView, for which aBlock evaluates to true
or any view, if the argument is nil.

 flushEventsFor: aViewOrNil withType: type

throw away all events for aView,
(or any view, if the argument is nil) which have a particular type.

 flushExposeEvents

throw away all pending expose events; this
can be done after a full redraw (or in views, which are
doing full redraws anly)

 flushExposeEventsFor: aView

throw away all pending expose events for aView,
or any view, if the argument is nil.
This can be done after a full redraw
(or in views, which are always doing full redraws -
instead of drawing the clip-area only)

 flushKeyboard

ST-80 compatibility: throw away all pending keyboard events

 flushKeyboardFor: aView

throw away all pending keyboard events for aView,
or any view, if the argument is nil.

 flushMotionEventsFor: aView

throw away all pending motion events for aView,
or for any view, if the argument is nil.

 flushUserEvents

throw away all pending user events (i.e. key & button stuff)

 flushUserEventsFor: aView

throw away all pending user events for aView (i.e. key & button stuff),
or for any view, if the argument is nil.

 flushUserEventsFor: aView where: aBlock

throw away all pending user events (i.e. key & button stuff)
for which aBlock returns true.
For aView or for any view, if the argument is nil.

 flushUserEventsFor: aView withType: type

throw away all pending user events with specified type for aView (i.e. key & button stuff),
or for any view, if the argument is nil.

 flushUserEventsFor: aView withType: type andArgument: arg

throw away all pending user events with specified type for aView (i.e. key & button stuff),
or for any view, if the argument is nil.

 flushUserEventsFor: aView withType: type withArguments: args

throw away all pending user events with specified type for aView (i.e. key & button stuff),
or for any view, if the argument is nil.

 lastMotionEventFor: aView

throw away all pending motion events for aView,
or for any view, if the argument is nil.
Returns the very last (valid) motion event.

 buttonMotion: buttonAndModifierState x: x y: y view: aView

mouse was moved - this is sent from the device (Display)

 buttonMultiPress: button x: x y: y view: aView

mouse button was pressed - this is sent from the device (Display)

 buttonPress: button x: x y: y view: aView

mouse button was pressed - this is sent from the device (Display)

 buttonRelease: button x: x y: y view: aView

mouse button was released- this is sent from the device (Display)

 clientMessage: type format: format eventData: data view: aView

some other process has sent data to a view.
This is an X-specific event. (see copyDataEvent for win32 variant)

 configureX: x y: y width: w height: h view: aView

a view's size or position has changed - this is sent from the device (Display)

 copyDataEvent: parameter eventData: data view: aView

some other process has sent data to a view.
This is a Win32-specific event. (see clientMessage for x-windows variant)

 coveredBy: coveringSiblingView view: coveredView

aView was covered by one of its siblings - this is sent from the device (Display)

 createWindow: view x: x y: y width: w height: h

A window has been created in a view.
This is a synthetic event, useful for some event recorders

 destroyedView: aView

view was destroyed (from window manager) - this is sent from the device (Display)

 dropFiles: files view: view position: dropPositionOrNil handle: dropHandleOrNil

 dropMessage: dropType data: dropValue view: targetView position: dropPositionOrNil handle: dropHandleOrNil

 exposeX: left y: top width: width height: height view: aView

an expose event arrived - this is sent from the device (Display)

 focusInView: aView

view got input focus - this is sent from the device (Display)

 focusOutView: aView

view lost input focus - this is sent from the device (Display)

 graphicsExposeX: left y: top width: width height: height final: final view: aView

a graphic expose event arrived - this is sent from the device (Display)

 hotkeyWithId: aHotkeyId key: aKey view: aView

hotkey was pressed - this is sent from the device (Display).

 keyPress: keyIn x: x y: y view: aView

key was pressed - this is sent from the device (Display).
beside the keyboard translation, CntlC processing is done here.

 keyRelease: keyIn x: x y: y view: aView

key was released - this is sent from the device (Display).

 mappedView: aView

view was mapped (from window manager) - this is sent from the device (Display)

 mouseWheelMotion: state x: x y: y amount: amount deltaTime: dTime view: aView

mouse-wheel was turned - this is sent from the device (Display)

 nativeWidgetCommand: command arguments: argVector view: aView

native widget action - this is sent from the device (Display).
These are only delivered if native widgets are enabled under win32

 noExposeView: aView

an noexpose event arrived - this is sent from the device (Display)

 pasteFromClipBoard: something view: aView

a clipboard paste - this is handled like a user event

 pointerEnter: state x: x y: y view: aView

mouse cursor was moved into the view - this is sent from the device (Display)

 pointerLeave: state view: aView

mouse cursor was moved out of the view - this is sent from the device (Display)

 preViewCreateNotification: aView

invoked right before a new view is created.
Notify listeners and allow for the origin/extent to be
changed. (For example, recorder/playback applications may
want to make certain that the playback view is at the same
position - or record any origin changes to translate later
synthetic events).

 propertyChange: aView property: propertyId state: aSymbol time: time

A window has been created in a view

 saveAndTerminateView: aView

view should save & terminate (from window manager) - this is sent from the device (Display)

 selectionClear: selectionID time: time view: aView

the selection owner has changed (someone else has the selection)

 terminateView: aView

view should terminate (from window manager) - this is sent from the device (Display)

Usage example(s):

Logger info:'sensor terminateView: %1' with:aView.

 trayAction: command arguments: argVector view: aView

native widget action - this is sent from the device (Display)

 unmappedView: aView

view was unmapped (from window manager) - this is sent from the device (Display)

 visibilityOf: aView changedTo: how

view was mapped (from window manager) - this is sent from the device (Display)