"

 COPYRIGHT (c) 1995 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:#KeyboardForwarder

	 instanceVariableNames:'sourceView destinationView destination condition'

	 classVariableNames:''

	 poolDictionaries:''

	 category:'Interface-Support'

!

!KeyboardForwarder class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1995 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 can be used to forward keyboard

    events to some object or other view (install them via aView delegate:).

    Event delegation allows to add additional keyboard functions to views

    WITHOUT modifying their code or changing controllers.

    Also, it allows to catch certain individual keys to ignore them or

    perform different functions.

    Notice, that delegates dont have to be instances of

    myself; any object with a protocol similar to mine can be used as

    a delegate. 

    (i.e. any object that responds to 

     handlesKeyPress:view: / keyPress:x:y:view: / delegatesTo: etc.)

    However, I provide the most common functions required for conditional

    event delegation and instances of myself are for example used to forward 

    events from elements of some dialogBoxes to the enterfield/fieldGroup - 

    (which allows keyboard input to be forwarded to the active text-field even 

     while the mouse pointer is somewhere else)

    Another application of delegation is to catch keyboard input to some standard

    widget, optionally processing and resending the key-event.

    I can either forward the key event to another view, or to some general

    object - the difference is that views are sent a #keyXXX:x:y: message,

    while general destinations get a #keyXXX:x:y:view: message, with the original

    view (the one in which the event occurred) as additional argument.

    Instance Variables:

	destinationView         <View>          the view which shall receive

						the forwarded keyboard events.

	destination             <Object>        the object which shall receive

						the forwarded keyboard events.

	sourceView              <ViewOrNil>     if non-nil, only events from this

						view are forwarded.

						(currently nowhere used)

	condition               <Symbol>        an additional condition for forwarding

						currently only #noFocus is implemented.

						The #noFocus condition will only forward

						events if no explicit focus has been

						set in the windowGroup.

				<Block>         condition block - event is forwarded,

						if it evaluates to true.

						The block gets 3 arguments:

						    eventType   #keyPress or #keyRelease

						    key         the key

						    view        the originating view

    For more info on event handling/forwarding, see the documentation in

    WindowSensor, WindowGroup and especially in WindowEvent.

"

!

examples

"

    catch an enterfields input:

	|top field forwarder catcher|

	catcher := Plug new.

	catcher respondTo:#keyPress:x:y:view:

		    with:[:key :x :y :view | Transcript showCr:'cought keyPress: ' , key printString.].

	catcher respondTo:#keyRelease:x:y:view:

		    with:[:key :x :y :view | Transcript showCr:'cought keyRelease: ' , key printString.].

	top := StandardSystemView new.

	top extent:200@200.

	field := EditField in:top.

	field origin:0.0@0.0; width:1.0.

	forwarder := KeyboardForwarder to:catcher. 

	field delegate:forwarder.

	top open

    catch an enterfields return-key only:

	|top field forwarder catcher|

	catcher := Plug new.

	catcher respondTo:#keyPress:x:y:view:

		    with:[:key :x :y :view | Transcript showCr:'cought return'].

	top := StandardSystemView new.

	top extent:200@200.

	field := EditField in:top.

	field origin:0.0@0.0; width:1.0.

	forwarder := KeyboardForwarder 

			to:catcher 

			condition:[:type :key :view | (type == #keyPress) & (key == #Return)].

	field delegate:forwarder.

	top open

    catch all of an enterfields input and ignore it:

	|top field forwarder|

	top := StandardSystemView new.

	top extent:200@200.

	field := EditField in:top.

	field origin:0.0@0.0; width:1.0.

	forwarder := KeyboardForwarder to:nil. 

	field delegate:forwarder.

	top open

"

! !

!KeyboardForwarder class methodsFor:'instance creation'!

from:sourceView to:destination

    "create and return a new KeyboardForwarder to redirect key events

     for sourceView to destination. Events from other than the sourceView

     will not be forwarded. The forwarded event will be reported including

     the original view as argument (i.e. as #keyPress:x:y:view:). 

     Use this, if the destination is not a view."

    ^ self new sourceView:sourceView; destination:destination

!

from:sourceView toView:destinationView

    "create and return a new KeyboardForwarder to redirect key events

     for sourceView to destinationView. Events from other than the sourceView

     will not be forwarded. The forwarded event will be reported excluding

     the original view as argument (i.e. as #keyPress:x:y:). 

     Use this, if the destination is a view."

    ^ self new sourceView:sourceView; destinationView:destinationView

!

to:destination

    "create and return a new KeyboardForwarder to redirect any key event

     to destination (Independent of the view in which the event originally

     occurred). The forwarded event will be reported including

     the original view as argument (i.e. as #keyPress:x:y:view:). 

     Use this, if the destination is not a view."

    ^ self new destination:destination

!

to:destination condition:aCondition

    "create and return a new KeyboardForwarder to redirect any key event

     to destinationView (Independent of the view in which the event originally

     occurred) but only, if some condition as specified by aCondition

     is met. The forwarded event will be reported including

     the original view as argument (i.e. as #keyPress:x:y:view:). 

     Use this, if the destination is not a view."

    ^ self new destination:destination; condition:aCondition

!

toView:destinationView

    "create and return a new KeyboardForwarder to redirect any key event

     to destinationView (Independent of the view in which the event originally

     occurred). The forwarded event will be reported excluding

     the original view as argument (i.e. as #keyPress:x:y:). 

     Use this, if the destination is a view."

    ^ self new destinationView:destinationView

!

toView:destinationView condition:aCondition

    "create and return a new KeyboardForwarder to redirect any key event

     to destinationView (Independent of the view in which the event originally

     occurred) but only, if some condition as specified by aCondition

     is met. The forwarded event will be reported excluding

     the original view as argument (i.e. as #keyPress:x:y:). 

     Use this, if the destination is a view."

    ^ self new destinationView:destinationView; condition:aCondition

! !

!KeyboardForwarder methodsFor:'accessing'!

condition:aCondition

    "set the condition - typically a block"

    condition := aCondition

!

destination

    "return the destination"

    ^ destination

!

destination:anObject 

    "set the destination 

     - that one will get the event with an additional view arg."

    destination := anObject

!

destinationView

    "return the destination view"

    ^ destinationView

!

destinationView:aView

    "set the destination view"

    destinationView := aView

!

sourceView

    "get the sourceView - if nonNil, only events from this view will be forwarded"

    ^ sourceView

!

sourceView:aView

    "set the sourceView - if nonNil, only events from this view will be forwarded"

    sourceView := aView

! !

!KeyboardForwarder methodsFor:'event forwarding'!

keyPress:key x:x y:y view:aView

    "handle a delegated event - this is sent by the sensor to actually

     forward the event (i.e. after I returned true on handlesKeyPress:.

     Take care of cyclic delegation (via a kludge-test for negative coordinate)."

    x < 0 ifTrue:[

	"

	 already delegated ... ignore

	"

	^ self

    ].

    destination notNil ifTrue:[

	destination keyPress:key x:-1 y:-1 view:aView.

    ] ifFalse:[

	destinationView notNil ifTrue:[

	    WindowEvent

		sendEvent:#keyPress:x:y:

		arguments:(Array with:key with:-1 with:-1)

		view:destinationView

	]

    ]

!

keyRelease:key x:x y:y view:aView

    "handle a delegated event - this is sent by the sensor to actually

     forward the event (i.e. after I returned true on handlesKeyRelease:.

     Take care of cyclic delegation (via a kludge-test for negative coordinate)."

    x < 0 ifTrue:[

	"

	 already delegated ... ignore

	"

	^ self

    ].

    destination notNil ifTrue:[

	destination keyRelease:key x:-1 y:-1 view:aView

    ] ifFalse:[

	destinationView notNil ifTrue:[

	    WindowEvent

		sendEvent:#keyRelease:x:y:

		arguments:(Array with:key with:-1 with:-1)

		view:destinationView

	]

    ]

! !

!KeyboardForwarder methodsFor:'queries'!

checkCondition:type key:key view:aView

    condition notNil ifTrue:[

	condition == #noFocus ifTrue:[

	    aView windowGroup focusView notNil ifTrue:[^ false]

	].

	condition isBlock ifTrue:[

	    (condition value:type value:key value:aView) ifFalse:[^ false]

	]

    ].

    sourceView notNil ifTrue:[

	^ aView == sourceView

    ].

    ^ true

!

delegatesTo:someone

    "return true, if I delegate events to someone"

    ^ destination == someone or:[destinationView == someone]

!

handlesKeyPress:key inView:aView

    "this is the query from the sensor to ask me if I would like to

     get a keyPress event for key from aView. Return true, if I want so,

     false otherwise."

    ^ self checkCondition:#keyPress key:key view:aView

!

handlesKeyRelease:key inView:aView

    "this is the query from the sensor to ask me if I would like to

     get a keyRelease event for key from aView. Return true, if I want so,

     false otherwise."

    ^ self checkCondition:#keyRelease key:key view:aView

! !