Class: KeyboardForwarder

• Inheritance
• Description
• Related information
• Class protocol
  • instance creation
• Instance protocol
  • accessing
  • event forwarding
  • focus forwarding
  • queries
• Examples

Inheritance:

   Object
   |
   +--KeyboardForwarder

Package:

stx:libview

Category:

Interface-Support-UI

Version:

rev: 1.30 date: 2018/05/12 12:25:01

user: cg

file: KeyboardForwarder.st directory: libview

module: stx stc-classLibrary: libview

Author:

Claus Gittinger

Description:

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.

Related information:

    WindowEvent
    WindowSensor
    WindowGroup

Class protocol:

 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.

 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.

 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.

 to: destination condition: aCondition

create and return a new KeyboardForwarder to redirect any key event
to destination
(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.

 to: destination condition: aCondition filter: aFilterBlock

create and return a new KeyboardForwarder to redirect any key event
to destination
(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.

 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.

 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.

 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.

Instance protocol:

 condition: aCondition

set the condition - typically a block

 destination

return the destination

 destination: anObject

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

 destinationView

return the destination view

 destinationView: aView

set the destination view

 filter: aOneArgBlock

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

 sourceView

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

 sourceView: aView

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

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

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

 hasKeyboardFocus: aBoolean

forward focus information to my destination

 showFocus: explicit

forward focus information to my destination

 showNoFocus: explicit

forward focus information to my destination

 checkCondition: typeOfEvent key: key view: aView

return true, if I am interested in an event with type
(#keyPress or #keyRelease) and key for aView.

 delegatesTo: someone

return true, if I delegate events to someone

 handlesButtonMotion: something inView: aView

I am not interested in button events

 handlesButtonPress: something inView: aView

I am not interested in button events

 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.

 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.

 handlesPointerEnter: something inView: aView

I am not interested in pointer events

 handlesPointerLeave: something inView: aView

I am not interested in pointer events

Examples:

    |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

    |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

    |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