"{ Encoding: utf8 }"

"

 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.

"

"{ Package: 'stx:libwidg' }"

"{ NameSpace: Smalltalk }"

EditTextView subclass:#EditField

	instanceVariableNames:'leaveAction enabled clickAction crAction tabAction converter

		leaveKeys immediateAccept acceptOnLeave acceptOnReturn

		lengthLimit entryCompletionBlock entryCompletionCharacter

		passwordCharacter autoScrollHorizontally acceptOnTab

		acceptOnLostFocus acceptOnPointerLeave acceptIfUnchanged leaveKey

		doubleClickAction emptyFieldReplacementText leaveKeyActions

		cancelKeys cancelKey cancelKeyActions'

	classVariableNames:'DefaultForegroundColor DefaultBackgroundColor

		DefaultSelectionForegroundColor DefaultSelectionBackgroundColor

		DefaultBorderColor DefaultBorderWidth DefaultLevel

		FieldsHiddenAsPassword'

	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 interested 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 method's #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.

    special key handling:

      usually, editFields are embedded in a form (as in a dialog), 

      which has OK and Cancel buttons at the bottom.

      However, if the editField is in some other popup, it may be required to customize its behavior

      upon certain key events. 

      For this, the following flags are used:

        leaveKeys       - the set of keys, which will lead to an accept (of the value into the model),

                          and leave the focus. If that happens, the responsible key is left in the leaveKey variable.

                          Default are CursorUp, Down and Return

        leaveAction     - if not nil, that action is called after the accept, passing the leaveKey as argument

        acceptOnLeave   - if true, an accept will be performed on leave.

        cancelKeys      - the set of keys which will leve without accepting. If that happens, the responsible

                          key is left in the cancelKey variable.

        cancelAction    - if not nil, that action is called, passing the cancelKey as argument.

    [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 <entryCompletionCharacter> is pressed.

                                                Entry completion is used with Filenamefields or in the

                                                browser for classname/selector completion.

                                                Setting a nonNil entryCompletion disables acceptOnTab.

      entryCompletionCharacter <CharacterOrNil> if non-nil AND entryCompletionBlock is nonNil, that one

                                                is evaluated for completion. Typically used to complete

                                                a fileName (also, classNames in the browser)

                                                Default is #Tab.

      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.

    [author:]

        Claus Gittinger

    [see also:]

        DialogBox

        EnterFieldGroup

        EnterBox EnterBox2

        FilenameEditField EditTextView

"

!

examples

"

    see more examples in EnterFieldGroup>>examples.

    Step-by-step introduction:

    basic field in some view:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    forward input in topView to the field:

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

     its been told here ... this may change)

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    to make it look better: set some inset:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    give it an initial contents:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    have it preselected:

                                                                        [exBegin]

        |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

                                                                         [exEnd]

    have part of it preselected:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    set a size limit:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

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

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

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    enable / disable:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    enable / disable using a channel:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    use a converter:

      - numbers (default to 0):

                                                                        [exBegin]

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

        field horizontalInset:spacing.

        field converter:(PrintConverter new initForNumber).

        field editValue:1234.

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

        field crAction:[field accept. top destroy].

        top open.

                                                                        [exEnd]

      - dates:

                                                                        [exBegin]

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

        field horizontalInset:spacing.

        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.

                                                                        [exEnd]

    setting immediateAccept, makes the field update with every key:

      - immediate accept numbers, defaulting to nil:

                                                                        [exBegin]

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

        field horizontalInset:spacing.

        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.

                                                                        [exEnd]

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

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

                                                                        [exBegin]

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