"

 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.

"

Object subclass:#WindowSensor

	instanceVariableNames:'eventSemaphore damage mouseAndKeyboard compressMotionEvents

		ignoreUserInput exposeEventSemaphore catchExpose gotExpose

		gotOtherEvent translateKeyboardEvents shiftDown ctrlDown metaDown

		altDown leftButtonDown middleButtonDown rightButtonDown

		eventListener keyboardListener eventListeners ignoreExposeEvents

		damageEventAccessLock userEventAccessLock'

	classVariableNames:'ControlCEnabled ControlYEnabled EventListener ComposeTable

		GotCompose Compose1 EventListeners'

	poolDictionaries:''

	category:'Interface-Support'

!

!WindowSensor class methodsFor:'documentation'!

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.

"

!

documentation

"

    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 'eventListenesr' to get the event before it is entered into

    the queue. There are 3 possible listening hooks available:

        global EventListener - get keybd/mouse/focus/enter-leave events for all views

        per-sensor eventListener - gets only keybd/mouse/focus/enter-leave events for this sensors wGroup

        per-sensor keyboardListener - only gets keyboard events for this sensors wGroup

    (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 views 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 views 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.

    The old mechanism is kept for a while for backward compatibility, but will eventually

    vanish.

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

        eventListener           <Object>        if non nil, this one will get all pointer

        OBSOLETE - will vanish                  and keyboard events for this sensors views first.

                                                If it returns true, the event is supposed to

                                                be already handled by the listener and not sent to

                                                the view. If false, the event is handled as usual.

                                                This allows applications to catch events for any of

                                                its views.

        keyboardListener        <Object>        if non nil, this one will get all keyboard events 

        OBSOLETE - will vanish                  for this sensors views first (but after the eventListener,

                                                if any).

                                                If it returns true, the event is supposed to

                                                be already handled by the listener and not sent to

                                                the view. If false, the event is handled as usual.

                                                This allows applications to catch events for any of

                                                its views.

                                                ApplicationModels can catch keyboard input with:

                                                    postOpenWith:aBuilder

                                                        aBuilder window sensor keyboardListener:self

        eventListeners          <Collection>    Collection of new event listeners.

                                                Each will be sent a #handleEvent: message.

                                                The event will not be enqueued, if any returns

                                                true.

        keyboardListeners       <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)

        EventListener           <Object>        if non nil, this one will get all pointer

        OBSOLETE - will vanish                  and keyboard events for ALL views first.

                                                If it returns true, the event is supposed to

                                                be already handled by the listener and not enqueued. 

                                                If false, the event is handled as usual.

                                                This allows overall event catchers to be

                                                installed for example to implement event

                                                recorders, active help managers etc.

        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

    [author:]

        Claus Gittinger

    [see also:]

        WindowGroup 

        WindowEvent KeyboardMap KeyboardForwarder EventListener

        DeviceWorkstation View

"

! !

!WindowSensor class methodsFor:'initialization'!

initialize

    "initialize the classes constants"

    ControlCEnabled := true.

    ControlYEnabled := true.

    ComposeTable isNil ifTrue:[

	self initializeComposeKeyTable

    ]

    "

     WindowSensor initialize

    "

    "Modified: / 20.5.1998 / 14:01:52 / cg"

!

initializeComposeKeyTable

    "setup the composeKey table"

    ComposeTable := #(

	"/ format is:

	"/ ( key1 key2 <character or asciiValue> )

	"/

	($+ $+ $#)         "/ number-sign

	($A $A $@)         "/ at-sign

	($( $- ${)         "/ left brace

	($) $- $})         "/ right brace

	($| $c 16rA2)      "/ cent-sign 

	($| $S $$)         "/ dollar-sign

	($= $L 16rA3)      "/ pound-sign     

	($= $Y 16rA5)      "/ yen-sign        

	($!! $s 16rA7)      "/ section-sign    

	($O $C 16rA9)      "/ copyright        

	($< $< 16rAB)      "/ french <<-quotes 

	($O $R 16rAE)      "/ registered       

	($/ $u 16rB5)      "/ greek mu         

	($!! $p 16rB6)      "/ paragraph sign   

	($> $> 16rBB)      "/ french >> quotes 

	($^ $0 16rB0)      "/ degree sign      

	($+ $- 16rB1)      "/ plus-minus       

	($^ $2 16rB2)      "/ superscript-2    

	($^ $3 16rB3)      "/ superscript-3    

	($^ $. 16rB7)      "/ middle dot       

	($^ $1 16rB9)      "/ superscript-1    

	($1 $4 16rBC)      "/ 1/4              

	($1 $2 16rBD)      "/ 1/2              

	($3 $4 16rBE)      "/ 3/4              

	($? $? 16rBF)      "/ ?-inverted       

	($- $: 16rF7)      "/ divide           

	"/ diacriticals: Compose diacrit character

	"/ grave

	($A $` 16rC0)      "/ A-`              

	($a $` 16rE0)      "/ a-`              

	($E $` 16rC8)      "/ E-`              

	($e $` 16rE8)      "/ e-`              

	($I $` 16rCC)      "/ I-`              

	($i $` 16rEC)      "/ i-`              

	($O $` 16rD2)      "/ O-`              

	($o $` 16rF2)      "/ o-`              

	($U $` 16rD9)      "/ U-`              

	($u $` 16rF9)      "/ u-`              

	"/ acute

	($A $' 16rC1)      "/ A-'             

	($a $' 16rE1)      "/ a-'             

	($E $' 16rC9)      "/ E-'            

	($e $' 16rE9)      "/ e-'           

	($I $' 16rCD)      "/ I-'          

	($i $' 16rED)      "/ i-'         

	($O $' 16rD3)      "/ O-'        

	($o $' 16rF3)      "/ o-'       

	($U $' 16rDA)      "/ U-'      

	($u $' 16rFA)      "/ u-'     

	($Y $' 16rDD)      "/ Y-'    

	($y $' 16rFD)      "/ y-'   

	"/ circumflex

	($A $^ 16rC2)      "/ A-^              

	($a $^ 16rE2)      "/ a-^             

	($E $^ 16rCA)      "/ E-^            

	($e $^ 16rEA)      "/ e-^           

	($I $^ 16rCE)      "/ I-^          

	($i $^ 16rEE)      "/ i-^         

	($O $^ 16rD4)      "/ O-^        

	($o $^ 16rF4)      "/ o-^       

	($U $^ 16rDB)      "/ U-^      

	($u $^ 16rFB)      "/ u-^     

	"/ tilde

	($A $~ 16rC3)      "/ A-~              

	($a $~ 16rE3)      "/ a-~             

	($O $~ 16rD5)      "/ O-~            

	($o $~ 16rF5)      "/ o-~           

	($N $~ 16rD1)      "/ N-tilde      

	($n $~ 16rF1)      "/ n-~         

	"/ ring above

	($a $* 16rE5)      "/ a-*              

	($A $* 16rC5)      "/ A-*             

	"/ cedille

	($C $, 16rC7)      "/ C-,              

	($c $, 16rE7)      "/ c-,             

	"/ dieresis

	($A $" 16rC4)      "/ A-"              

	($a $" 16rE4)      "/ a-"             

	($E $" 16rCB)      "/ E-"            

	($e $" 16rEB)      "/ e-"           

	($I $" 16rCF)      "/ I-"          

	($i $" 16rEF)      "/ i-"         

	($O $" 16rD6)      "/ O-"        

	($o $" 16rF6)      "/ o-"       

	($U $" 16rDC)      "/ U-"      

	($u $" 16rFC)      "/ u-"     

	($y $" 16rFF)      "/ y-"    

	"/ slashed

	($o $/ 16rF8)      "/ o-/        

	($O $/ 16rD8)      "/ O-/    

	"/ ligatures

	($s $s 16rDF)      "/ german sz        

	($a $e 16rE6)      "/ (french) ae     

	($A $E 16rC6)      "/ (french) AE    

    ).

    "              

     WindowSensor initializeComposeKeyTable

    "

    "Created: 22.4.1996 / 14:06:43 / cg"

    "Modified: 24.4.1996 / 16:37:08 / cg"

! !

!WindowSensor class methodsFor:'instance creation'!

new

    "return a new initialized instance"

    ^ self basicNew initialize

    "Modified: 22.4.1996 / 16:19:40 / cg"

! !

!WindowSensor class methodsFor:'accessing'!

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

     - see documentation for what this can be used for"

    EventListeners isNil ifTrue:[

        EventListeners := OrderedCollection new:2

    ].

    (EventListeners identityIndexOf:aListener) == 0 ifTrue:[

        EventListeners add:aListener

    ]

!

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

!

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"

    ComposeTable := aTable

!

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

    "

    ControlCEnabled := aBoolean

    "Modified: / 29.10.1997 / 15:48:29 / cg"

!

removeEventListener:aListener

    "remove a global eventListener (with new protocol - #handleEvent:)

     - see documentation for what this can be used for"

    EventListeners notNil ifTrue:[

        EventListeners removeIdentical:aListener ifAbsent:nil

    ].

! !

!WindowSensor class methodsFor:'accessing - obsolete'!

eventListener

    "return the eventListener 

     - see documentation for what this can be used for"

    self obsoleteMethodWarning:'use the new eventListeners: protocol; read the documentation'.

    ^ EventListener

!

eventListener:aListener

    "set the eventListener 

     - see documentation for what this can be used for"

    self obsoleteMethodWarning:'use the new eventListeners: protocol; read the documentation'.

    EventListener := aListener

! !

!WindowSensor class methodsFor:'event processing'!

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)."

    |ret ev|

    "/ backward compatibility ... will vanish

    EventListener notNil ifTrue:[

        EventListener postCreateView:aView.

    ].

    "/ new protocol

    EventListeners size > 0 ifTrue:[

        ev := WindowEvent

                 for:aView

                 type:#postCreateView

                 arguments:nil.

        EventListeners do:[:aListener |

            aListener processEvent:ev

        ]

    ].

!

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)."