"

 COPYRIGHT (c) 1992 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:#EnterFieldGroup

	 instanceVariableNames:'fields currentField leaveAction wrap'

	 classVariableNames:''

	 poolDictionaries:''

	 category:'Interface-Support'

!

!EnterFieldGroup class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1992 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

"

    EnterFieldGroup controls the interaction between EnterFields

    enabling the next/prev field when a field is left. 

    Instances of this class keep track of which field of the group is the 

    currentField (i.e. the one getting keyboard input) and forwards input

    to the active field (having the inputField delegate its input to me).

    The block accessable as leaveAction is evaluated when the last

    field of the group is left (by cursor-down or cr). 

    Usually this block triggers accept on the fields and/or performs some

    followup processing and closes  the topview (for example: in a dialog).

    EnterFieldGroups can be used as a delegate (of the topView) to forward

    input (entered into the topView) to the currently active field.

    Stepping to previous field is via CursorUp/PreviousField,

    to next field via CursorDown/NextField/Tab.

    Notice, that by default, the editField takes the tab-character as

    a normal character. To step using tab, you have to add the Tab key to the

    fields leaveKeys.

    Instance variables:

	fields          <Collection of EditField>       the fields of the group

	currentField    <EditField>                     the active field

	leaveAction     <nil|Block>                     action to perform, when the

							last field is left by a non-wrap

	wrap            <Boolean>                       if true, non-return next-keys wrap

							back to the first field.

							If false (the default), next in

							the last field is taken as return.

							This is ignored, if no leaveAction was 

							defined.

"

!

examples 

"

    without a group - user has to enter mouse into the next field to activate it;

    Cursor-keys dont work:

	|top panel field1 field2 field3|

	top := StandardSystemView new.

	top extent:200@200.

	panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

	panel add:(field1 := EditField extent:(1.0 @ nil)).

	panel add:(field2 := EditField extent:(1.0 @ nil)).

	panel add:(field3 := EditField extent:(1.0 @ nil)).

	top open

    with a group - Return-key or CursorKey enables next field:

    (but still, mouse pointer has to be moved into any of the fields,

     because the topView does not forward its input into the fields)

	|top panel group field1 field2 field3|

	top := StandardSystemView new.

	top extent:200@200.

	panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

	panel add:(field1 := EditField extent:(1.0 @ nil)).

	panel add:(field2 := EditField extent:(1.0 @ nil)).

	panel add:(field3 := EditField extent:(1.0 @ nil)).

	group := EnterFieldGroup new.

	group add:field1; add:field2; add:field3.

	top open

    same, enables tabbing via the Tab key:

	|top panel group field1 field2 field3|

	top := StandardSystemView new.

	top extent:200@200.

	panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

	panel add:(field1 := EditField extent:(1.0 @ nil)).

	panel add:(field2 := EditField extent:(1.0 @ nil)).

	panel add:(field3 := EditField extent:(1.0 @ nil)).

	group := EnterFieldGroup new.

	group add:field1; add:field2; add:field3.

	field1 leaveKeys:(EditField defaultLeaveKeys copyWith:#Tab).

	field2 leaveKeys:(EditField defaultLeaveKeys copyWith:#Tab).

	field3 leaveKeys:(EditField defaultLeaveKeys copyWith:#Tab).

	top open

    with a group - Return-key or CursorKey enables next field:

    input into topView is forwarded to the group:

	|top panel group field1 field2 field3|

	top := StandardSystemView new.

	top extent:200@200.

	panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

	panel add:(field1 := EditField extent:(1.0 @ nil)).

	panel add:(field2 := EditField extent:(1.0 @ nil)).

	panel add:(field3 := EditField extent:(1.0 @ nil)).

	group := EnterFieldGroup new.

	group add:field1; add:field2; add:field3.

	top delegate:group.

	top open

    as above, but close the box when the last field is left:

	|top panel group field1 field2 field3|

	top := StandardSystemView new.

	top extent:200@200.

	panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

	panel add:(field1 := EditField extent:(1.0 @ nil)).

	panel add:(field2 := EditField extent:(1.0 @ nil)).

	panel add:(field3 := EditField extent:(1.0 @ nil)).

	group := EnterFieldGroup new.

	group add:field1; add:field2; add:field3.

	group leaveAction:[top destroy].

	top delegate:group.

	top open

    same as above, with Tab-key stepping:

	|top panel group field1 field2 field3|

	top := StandardSystemView new.

	top extent:200@200.

	panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

	panel add:(field1 := EditField extent:(1.0 @ nil)).

	panel add:(field2 := EditField extent:(1.0 @ nil)).

	panel add:(field3 := EditField extent:(1.0 @ nil)).

	group := EnterFieldGroup new.

	group add:field1; add:field2; add:field3.

	group leaveAction:[top destroy].

	field1 leaveKeys:(EditField defaultLeaveKeys copyWith:#Tab).

	field2 leaveKeys:(EditField defaultLeaveKeys copyWith:#Tab).

	field3 leaveKeys:(EditField defaultLeaveKeys copyWith:#Tab).

	top delegate:group.

	top open

    the next example shows that the input order is defined by the

    order in the group; NOT by the physical layout of the fields in the superview:

    (i.e. you can arrange your fields in multiple framedBoxes, panels or

     subviews - independent of the tab-stepping order)

	|top panel group field1 field2 field3|

	top := StandardSystemView new.

	top extent:200@200.

	panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

	panel add:(field1 := EditField extent:(1.0 @ nil)).

	panel add:(field2 := EditField extent:(1.0 @ nil)).

	panel add:(field3 := EditField extent:(1.0 @ nil)).

	group := EnterFieldGroup new.

	group add:field3; add:field2; add:field1.

	group leaveAction:[top destroy].

	top delegate:group.

	top open

    using a single model for all fields:

    (here, we use a Plug to simulate a more complex model):

	|top panel group field1 field2 field3 model

	 value1 value2 value3|

	top := StandardSystemView new.

	top extent:200@200.

	panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

	panel add:(field1 := EditField extent:(1.0 @ nil)).

	panel add:(field2 := EditField extent:(1.0 @ nil)).

	panel add:(field3 := EditField extent:(1.0 @ nil)).

	group := EnterFieldGroup new.

	group add:field1; add:field2; add:field3.

	group leaveAction:[top destroy].

	value1 := 'one'. value2 := 'two'. value3 := 'three'.

	model := Plug new.

	model respondTo:#value1 with:[value1].

	model respondTo:#value1: with:[:arg | value1 := arg].

	model respondTo:#value2 with:[value2].

	model respondTo:#value2: with:[:arg | value2 := arg].

	model respondTo:#value3 with:[value3].

	model respondTo:#value3: with:[:arg | value3 := arg].

	field1 model:model; aspect:#value1; change:#value1:.

	field2 model:model; aspect:#value2; change:#value2:.

	field3 model:model; aspect:#value3; change:#value3:.

	top delegate:group.

	top openModal.

	Transcript showCr:'value1: ' , value1.

	Transcript showCr:'value2: ' , value2.

	Transcript showCr:'value3: ' , value3.

    the above is done automatically for you, if you add inputFields

    to a dialogBox:

	|box model

	 value1 value2 value3|

	box := DialogBox new.

	box extent:200@200.

	value1 := 'one'. value2 := 'two'. value3 := 'three'.

	model := Plug new.

	model respondTo:#value1 with:[value1].

	model respondTo:#value1: with:[:arg | value1 := arg].

	model respondTo:#value2 with:[value2].

	model respondTo:#value2: with:[:arg | value2 := arg].

	model respondTo:#value3 with:[value3].

	model respondTo:#value3: with:[:arg | value3 := arg].

	(box addInputFieldOn:model) aspect:#value1; change:#value1:.

	box addVerticalSpace.

	(box addInputFieldOn:model) aspect:#value2; change:#value2:.

	box addVerticalSpace.

	(box addInputFieldOn:model) aspect:#value3; change:#value3:.

	box open.

	Transcript showCr:'value1: ' , value1.

	Transcript showCr:'value2: ' , value2.

	Transcript showCr:'value3: ' , value3.

"

! !

!EnterFieldGroup class methodsFor:'instance creation'!

new

    ^ self basicNew wrap:false

! !

!EnterFieldGroup methodsFor:'accessing'!

leaveAction:aBlock

    "set the action to perform when the last field is left.

     Usually, this is to accept the values of all fields and perform

     some additional processing (such as closing a dialog)."

    leaveAction := aBlock

!

wrap:aBoolean

    "specifies if leaveing the last field via non-Return

     should wrap back to the first, or leave the group"

    wrap := aBoolean

! !

!EnterFieldGroup methodsFor:'adding / removing'!

add:aField

    |thisIndex next action|

    fields isNil ifTrue:[

	fields := OrderedCollection new

    ].

    fields add:aField.

    thisIndex := fields size.

    aField delegate:self.

    aField hideCursor.

    aField disable.

    "set the fields enableAction to disable active field"

    aField enableAction:[

"/ Transcript showCr:'enable field with: ' , aField editValue.

"/        currentField notNil ifTrue:[

"/            currentField disable

"/        ].

"/        currentField := aField

	self makeActive:aField

    ].

    "set the fields leaveAction to enable next field"

    aField leaveAction:[:key |

"/ Transcript showCr:'left field with: ' , aField editValue.

	currentField notNil ifTrue:[

	    currentField disable.

	    currentField hideCursor.

	].

	action := key.

	((key == #CursorUp) or:[key == #PreviousField]) ifTrue:[

	    (thisIndex == 1) ifTrue:[

		next := fields size

	    ] ifFalse:[

		next := thisIndex - 1

	    ]

	].

	((key == #CursorDown) 

	or:[key == #NextField

	or:[key == #Tab]]) ifTrue:[

	    (thisIndex == (fields size)) ifTrue:[

		wrap ifFalse:[

		    action := #Return.

		] ifTrue:[

		    next := 1

		].

	    ] ifFalse:[

		next := thisIndex + 1

	    ]

	].

	(action == #Return) ifTrue:[

	    (thisIndex == (fields size)) ifTrue:[

		leaveAction notNil ifTrue:[

		    leaveAction value.

		    currentField := nil

		] ifFalse:[

		    next := 1

		]

	    ] ifFalse:[

		next := thisIndex + 1

	    ]

	].

	next notNil ifTrue:[

	    self makeActive:(fields at:next) 

	]

    ].

    fields size == 1 ifTrue:[

	"the first one"

	self makeActive:aField

    ]

! !

!EnterFieldGroup methodsFor:'event forwarding'!

buttonPress:button x:x y:y view:aView

    "clicking on a field activates it and forwards the click to it"

    self makeActive:aView.

    aView buttonPress:button x:x y:y

!

buttonShiftPress:button x:x y:y view:aView

    "clicking on a field activates it and forwards the click to it"

    self makeActive:aView.

    aView buttonShiftPress:button x:x y:y

!

handlesButtonPress:button inView:aView

    "query from event processor: am I interrested in button-events ?

     yes I am (to activate the clicked-on field)."

   ^ true

!

handlesButtonShiftPress:button inView:aView

    "query from event processor: am I interrested in button-events ?

     yes I am (to activate the clicked-on field)."

    ^ true

!

handlesKeyPress:key inView:aView

    "query from event processor: am I interrested in key-events ?

     yes I am (to forward it to the active field)."

    ^ true

!

handlesKeyRelease:key inView:aView

    "query from event processor: am I interrested in key-events ?

     yes I am (to forward it to the active field)."

    ^ true

!

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

    "key-press in any field - forward the key to the active field

     (with -1/-1 as coordinate to indicate that the key was pressed

      outside. However, this info is not used by any view currently)"

    currentField notNil ifTrue:[

	currentField keyPress:key x:-1 y:-1

    ]

!

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

    "key-release in any field - forward the key to the active field.

     (with -1/-1 as coordinate to indicate that the key was pressed

      outside. However, this info is not used by any view currently)"

    currentField notNil ifTrue:[

	currentField keyRelease:key x:-1 y:-1

    ]

! !

!EnterFieldGroup methodsFor:'misc'!

activateFirst

    "pass controll to my first field"

    fields notNil ifTrue:[

	self makeActive:(fields first)

    ]

! !

!EnterFieldGroup methodsFor:'private'!

makeActive:aField

    "make a specific field the active one"

    currentField notNil ifTrue:[

	currentField disable.

	currentField hideCursor.

	currentField hasKeyboardFocus:false.