eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'KeyboardForwarder':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: KeyboardForwarder


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:

instance creation
o  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.

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

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

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

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

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

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

o  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:

accessing
o  condition: aCondition
set the condition - typically a block

o  destination
return the destination

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

o  destinationView
return the destination view

o  destinationView: aView
set the destination view

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

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

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

event forwarding
o  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).

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

focus forwarding
o  hasKeyboardFocus: aBoolean
forward focus information to my destination

o  showFocus: explicit
forward focus information to my destination

o  showNoFocus: explicit
forward focus information to my destination

queries
o  checkCondition: typeOfEvent key: key view: aView
return true, if I am interested in an event with type
(#keyPress or #keyRelease) and key for aView.

o  delegatesTo: someone
return true, if I delegate events to someone

o  handlesButtonMotion: something inView: aView
I am not interested in button events

o  handlesButtonPress: something inView: aView
I am not interested in button events

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

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

o  handlesPointerEnter: something inView: aView
I am not interested in pointer events

o  handlesPointerLeave: something inView: aView
I am not interested in pointer events


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:'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
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:'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
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


ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 06 Dec 2019 00:31:31 GMT