"

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

"

EditTextView subclass:#EditField

	instanceVariableNames:'leaveAction enabled clickAction crAction tabAction converter

		leaveKeys immediateAccept acceptOnLeave acceptOnReturn

		lengthLimit entryCompletionBlock passwordCharacter

		cursorMovementWhenUpdating enableChannel autoScrollHorizontally

		acceptOnTab'

	classVariableNames:'DefaultForegroundColor DefaultBackgroundColor

		DefaultSelectionForegroundColor DefaultSelectionBackgroundColor'

	poolDictionaries:''

	category:'Views-Text'

!

!EditField class methodsFor:'documentation'!

copyright

"

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

"

    an editable text-field. Realized by using an EditTextView,

    and forcing its size to 1 line - disabling cursor movement

    in the vertical direction.

    Basically, an editField is an editor for a single line text,

    and provides the usual access protocol as defined in its superClasses

    (especially: #contents / #contents:).

    The above underlying internal mechanism can be used for fields which

    are passive; i.e. into which text can be entered and the value (string)

    is extracted actively by someone else.

  accepting:

    The opposite way to use editFields is to connect them to a model

    and let the field notify changes to it.

    This notification is called ``accepting''.

    Unless accepted, the models value is not updated from the editFields contents

    this default is the normal operation and way things should work, since most

    uses of editFields are not interrested in every individual change

    (i.e. getting each keyStroke when a long number is entered).

    The default behavior is to ``accept'' when either return or a cursorUp/Down

    key is pressed in a field.

    However, the field can setup to accept/not accept on leave, on return

    or on each individual key input.

    See the methods #acceptOnLeave: / #acceptOnReturn: / #immediateAccept.

    In addition, the set of keys which are considered ``leaveKeys'' can be

    specified by #leaveKeys: (in case you need keys other than Return, CursorUp/Down).

  models value vs. field contents:

    Although the field internally keeps its contents as some string object,

    the application may prefer to think of numbers, floats, yes/no values etc.

    To support this, a converter may defined, which is responsible for conversion of

    strings to/from the models domain value.

    If present (i.e. nonNil), the converter is asked to convert a string to the models

    domain with #readValueFrom:aString and vice versa, a value to a string by #printStringFor:.

    The PrintConverter class already provides a number of standard conversions, see the examples.

    To access a converted value directly (i.e. not via the model), use #editValue.

  grouping:

    Individual fields do not know about being included in a group. This must be arranged on the

    outside, by placing multiple fields into an EnterFieldGroup.

    This groupObject keeps a reference to one active field, and forwards input from any other

    field to the active one. Also have a look at the examples for this.

  input completion:

    To support input completion (i.e. filename completion, classname completion etc.),

    a completionBlock can be defined which (if non-nil) is evaluated when the completion-key

    is pressed and its value is taken as the new field-contents. 

    The physical completion-key is the Tab key (this one cannot be defined by

    the keyboardTranslation mechanism, since that would disable the Tab-key on regular text views.

    Instance variables:

      leaveAction    <Block | nil>              if non-nil, this is evaluated with

						the key (#Return, #CursorUp etc.) when

						the field is left via keyboard keys.

						(fieldGroups use this to decide which

						 field has to be enabled next)

      enabled        <Boolean>                  if false, input is ignored.

      clickAction    <Block | nil>              action performed if the field is

						clicked upon.

						(this is used by the group to

						 set the active field to the clicked upon field)

      crAction       <Block | nil>              if non-nil, keyboard input of a cr are not

						handled specially, instead this block is evaluated

						(however, this block can perform additional checks and send

						 a #accept then)

      tabAction      <Block | nil>              if non-nil, keyboard input of a tab character

						is not entered into the text, instead this block

						is evaluated. Also, no input completion is performed if

						tabAction is nonNil.

      converter      <PrintConverter | nil>     if non-nil, this is supposed to convert between

						the object and its printed representation and vice versa.

						Defaults to nil i.e. assume that strings are edited.

      leaveKeys      <Collection>               keys which are interpreted as 'leaving the field'

      immediateAccept   <Boolean>               if true, every change of the text is immediately

						forwarded to the model/acceptBlock. If false,

						the changed value is only stored in the model

						if the field is left or accepted.

						Default is false.

      acceptOnLeave  <Boolean>                  if true, leaving the field (via cursor keys)

						automatically accepts the value into the model.

						Default is true.

      acceptOnReturn <Boolean>                  if true, leaving the field via return

						automatically accepts the value into the model.

						Default is true.

      acceptOnTab    <Boolean>                  if true, the Tab key accepts and leaves the field.

						If false, Tabs are entered into the contents field like

						ordinary non-control keys.

						AcceptOnTab is ignored if the entryCompletion block is nonNil.

						Default is true.

      lengthLimit    <Number>                   the max. number of allowed characters

      entryCompletionBlock <BlockOrNil>         if non-nil, this is evaluated to complete the entry

						when Tab is pressed.

						Entry completion is used with Filenamefields or in the

						browser for classname/selector completion.

						Setting a nonNil entryCompletion disables acceptOnTab.

      passwordCharacter     <CharacterOrNil>    if non-nil, typed input is replaced by this character

						for display. Used for secret-input fields (such as password entry).

						Default is nil.

      cursorMovementWhenUpdating <Symbol>       defines where the cursor is to be positioned if the

						model changes its value by some outside activity

						(i.e. not by user input into the field).

						Can be one of:

						    #keep / nil     -> stay where it was

						    #endOfLine      -> position cursor after the string

						    #beginOfLine    -> position cursor to the beginning

						The default is nil (i.e. stay where it was before).

"

!

examples 

"

    see more examples in EnterFieldGroup>>examples.

    Step-by-step introduction:

    basic field in some view:

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:0.0@0.0 in:top.

        field width:1.0.                                'let its height as-is'.

        top open

    forward input in topView to the field:

    (currently, the field does not know this - therefore,

     its been told here ... this may change)

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:0.0@0.0 in:top.

        field width:1.0.                                'let its height as-is'.

        top delegate:(KeyboardForwarder toView:field).

        field hasKeyboardFocus:true.

        top open

    to make it look better: set some inset:

        |top field spacing|

        top := StandardSystemView new.

        top extent:200@100.

        spacing := View viewSpacing.

        field := EditField origin:(0.0 @ spacing) in:top.

        field width:1.0.                                        'let its height as-is'.

        field leftInset:spacing; rightInset:spacing.

        top open

    give it an initial contents:

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:(0.0 @ 0@0) in:top.

        field width:1.0.       

        field editValue:'hello world'.

        top open

    have it preselected:

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:(0.0 @ 0.0) in:top.

        field width:1.0.     

        field editValue:'hello world' selected:true.

        top open

    have part of it preselected:

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:(0.0 @ 0.0) in:top.

        field width:1.0.     

        field editValue:'hello world'.

        field selectFromCharacterPosition:1 to:5.

        top open

    set a size limit:

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:(0.0 @ 0.0) in:top.

        field width:1.0.     

        field editValue:'hello'.

        field maxChars:8.

        top open

    set a size limit, initial width and stop it from scrolling

    notice: you may prefer a constant-pitch font (such as courier):

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:(0.0 @ 0.0) in:top.

        field innerWidth:(field font widthOf:'00000000').     

        field editValue:'12345678'.

        field maxChars:8.

        field autoScroll:false.

        top open

    enable / disable:

        |top panel check field ena|

        top := StandardSystemView new.

        top extent:200@100.

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

        panel borderWidth:0.

        panel horizontalLayout:#left.

        panel horizontalInset:View viewSpacing.

        check := CheckBox label:'enable' in:panel.

        check turnOn.

        check action:[:onOff | onOff ifTrue:[field enable] ifFalse:[field disable]].

        panel add:(View new height:30; borderWidth:0).

        field := EditField in:panel.

        field width:1.0.     

        field editValue:'hello'.

        top open

    enable / disable using a channel:

        |top panel check field ena|

        top := StandardSystemView new.

        top extent:200@100.

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

        panel borderWidth:0.

        panel horizontalLayout:#left.

        panel horizontalInset:View viewSpacing.

        ena := true asValue.

        check := CheckBox label:'enable' in:panel.

        check model:ena.

        panel add:(View new height:30; borderWidth:0).

        field := EditField in:panel.

        field enableChannel:ena.

        field width:1.0.     

        field editValue:'hello'.

        top open

    use a converter:

      - numbers (default to 0):

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:0.0@ViewSpacing in:top.

        field width:1.0.

        field leftInset:ViewSpacing;

              rightInset:ViewSpacing.

        field converter:(PrintConverter new initForNumber).

        field editValue:1234.

        field acceptAction:[:value | Transcript showCr:value].

        field crAction:[field accept. top destroy].

        top open.

      - dates:

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:0.0@ViewSpacing in:top.

        field width:1.0.

        field leftInset:ViewSpacing;

              rightInset:ViewSpacing.

        field converter:(PrintConverter new initForDate).

        field editValue:Date today.

        field acceptAction:[:value | Transcript showCr:value class name , ' ' , value printString].

        field crAction:[field accept. top destroy].

        top open.

    setting immediateAccept, makes the field update with every key:

      - immediate accept numbers, defaulting to nil:

        |top field|

        top := StandardSystemView new.

        top extent:200@100.

        field := EditField origin:0.0@ViewSpacing in:top.

        field width:1.0.

        field leftInset:ViewSpacing;

              rightInset:ViewSpacing.

        field converter:(PrintConverter new initForNumberOrNil).

        field immediateAccept:true.

        field editValue:1234.

        field acceptAction:[:value | Transcript showCr:value].

        field crAction:[field accept. top destroy].

        top open.

    grouping multiple fields, and forward keyPres from the outer view to the active field

    (i.e. actually: to the group):

        |top field1 field2 field3 group|

        top := StandardSystemView new.

        top extent:200@100.

        field1 := EditField origin:(0.0 @ 0.0) in:top.

        field1 width:1.0.

        field2 := EditField origin:(0.0 @ 0.0) in:top.

        field2 width:0.5.

        field2 topInset:(field1 height); bottomInset:(field1 height negated).

        field3 := EditField origin:(0.5 @ 0.0) in:top.

        field3 width:0.5.

        field3 topInset:(field1 height); bottomInset:(field1 height negated).

        group := EnterFieldGroup new.

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

        top delegate:(KeyboardForwarder to:group).

        top open.

    in addition: tell the group to close when the last field is left:

        |top field1 field2 field3 group|

        top := StandardSystemView new.

        top extent:200@100.

        field1 := EditField origin:(0.0 @ 0.0) in:top.

        field1 width:1.0.

        field2 := EditField origin:(0.0 @ 0.0) in:top.

        field2 width:0.5.

        field2 topInset:(field1 height); bottomInset:(field1 height negated).

        field3 := EditField origin:(0.5 @ 0.0) in:top.

        field3 width:0.5.

        field3 topInset:(field1 height); bottomInset:(field1 height negated).

        group := EnterFieldGroup new.

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

        group leaveAction:[top destroy].

        top delegate:(KeyboardForwarder to:group).

        top open.

    use a model:

    (see changing model value in inspector when return is pressed in the field)

        |top field model|

        model := 'hello world' asValue.

        top := StandardSystemView new.

        top extent:200@100.