"

 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.

"

"{ Package: 'stx:libview' }"

"{ NameSpace: Smalltalk }"

Object subclass:#KeyboardForwarder

	instanceVariableNames:'sourceView destinationView destination condition filter'

	classVariableNames:''

	poolDictionaries:''

	category:'Interface-Support-UI'

!

!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 don't 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.

    [see also:]

        WindowEvent WindowSensor WindowGroup

    [author:]

        Claus Gittinger

"

!

examples

"

    catch an enterfields input:

                                                                        [exBegin]

        |top field forwarder catcher|

        catcher := Plug new.

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

                    with:[:key :x :y :view | Transcript showCR:'caught keyPress: ' , key printString.].

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

                    with:[:key :x :y :view | Transcript showCR:'caught 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

                                                                        [exEnd]

    catch an enterfields return-key only:

                                                                        [exBegin]

        |top field forwarder catcher|

        catcher := Plug new.

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

                    with:[:key :x :y :view | Transcript showCR:'caught 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

                                                                        [exEnd]

    catch all of an enterfields input and ignore it:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

"

! !

!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 to:destination condition:nil filter:nil 

!

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 to:destination condition:aCondition filter:nil 

!

to:destination condition:aCondition filter:aFilterBlock

    "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 and aFilterBlock returns true for that key.

     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; filter:aFilterBlock

!

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 toView:destinationView condition:nil filter:nil 

!

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 toView:destinationView condition:aCondition filter:nil 

!

toView:destinationView condition:aCondition filter:aFilterBlock

    "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 and aFilterBlock returns true for that key.

     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; filter:aFilterBlock

! !

!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

!

filter:aOneArgBlock

    "set the filter - if non-nil, only keys for which it returns true are forwarded"

     filter := aOneArgBlock

    "Created: 4.2.1996 / 20:35:15 / cg"

!

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

    |xDel yDel forwardedEvent|

    x isNil ifTrue:[

        "

         already delegated ... ignore

        "

        ^ self

    ].

    filter notNil ifTrue:[

        (filter value:key) ifFalse:[^ self].

    ].

    xDel := x.

    yDel := y.

    x == 0 ifTrue:[

        "

         already delegated ... care to not delegate twice

        "

        xDel := nil.

        yDel := nil.

    ].

    destination notNil ifTrue:[

        destination keyPress:key x:nil y:nil view:aView.

    ] ifFalse:[

        destinationView notNil ifTrue:[

            forwardedEvent := WindowEvent keyPress:key x:xDel y:yDel view:destinationView.

            destinationView

                dispatchEvent:forwardedEvent

                withFocusOn:nil 

                delegate:false

        ]

    ]

    "Modified: / 20.5.1998 / 22:54:05 / cg"

!

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

    |forwardedEvent|

    x < 0 ifTrue:[

        "

         already delegated ... ignore

        "

        ^ self

    ].

    filter notNil ifTrue:[

        (filter value:key) ifFalse:[^ self].

    ].

    destination notNil ifTrue:[

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

    ] ifFalse:[

        destinationView notNil ifTrue:[

            forwardedEvent := WindowEvent keyRelease:key x:-1 y:-1 view:destinationView.

            destinationView dispatchEvent:forwardedEvent withFocusOn:nil delegate:false

        ]

    ]

    "Modified: / 20.5.1998 / 22:54:32 / cg"

! !

!KeyboardForwarder methodsFor:'focus forwarding'!

hasKeyboardFocus:aBoolean

    "forward focus information to my destination"

    destinationView notNil ifTrue:[

        destinationView hasKeyboardFocus:aBoolean

    ].

    "Modified: 25.2.1997 / 23:16:35 / cg"

!

showFocus:explicit

    "forward focus information to my destination"

    |d|

    destinationView notNil ifTrue:[

        d := destinationView

    ] ifFalse:[

        d := destination

    ].

    d notNil ifTrue:[

        d showFocus:explicit

    ]

    "Modified: 25.2.1997 / 23:16:35 / cg"

!

showNoFocus:explicit

    "forward focus information to my destination"

    |d|

    destinationView notNil ifTrue:[

        d := destinationView

    ] ifFalse:[

        d := destination

    ].

    d notNil ifTrue:[

        d showNoFocus:explicit

    ]

    "Modified: 25.2.1997 / 23:16:40 / cg"

! !

!KeyboardForwarder methodsFor:'queries'!

checkCondition:type key:key view:aView

    "return true, if I am interested in an event with type (#keyPress or

     #keyRelease) and key for aView."

    |wg|

    filter notNil ifTrue:[

        (filter value:key) ifFalse:[^ false].

    ].

    condition notNil ifTrue:[

        condition == #noFocus ifTrue:[

            wg := aView windowGroup.

            (wg isNil or:[wg focusView notNil]) ifTrue:[^ false]

        ].

        condition isBlock ifTrue:[

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

        ]

    ].

    sourceView notNil ifTrue:[

        ^ aView == sourceView

    ].

    ^ true

    "Modified: / 31.10.1997 / 20:24:42 / cg"

!

delegatesTo:someone

    "return true, if I delegate events to someone"

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

!

handlesButtonMotion:something inView:aView

    "I am not interested in button events"

    ^ false

!

handlesButtonPress:something inView:aView

    "I am not interested in button events"

    ^ false

!

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

!