"

 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' }"

DialogBox subclass:#EnterBox

	instanceVariableNames:'labelField enterField trimBlanks'

	classVariableNames:''

	poolDictionaries:''

	category:'Views-DialogBoxes'

!

!EnterBox 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

"

   Historic note:

        originally, ST/X had separate classes for the various entry methods;

        there were YesNoBox, EnterBox, InfoBox and so on.

        In the meantime, the DialogBox class (and therefore its alias: Dialog)

        is going to duplicate most funcionality found in these classes.

        In the future, those existing subclasses' functionality is going to

        be moved fully into Dialog, and the subclasses will be replaced by dummy

        delegators. (They will be kept for backward compatibility, though).

    this class implements a pop-up box to enter some string

    with 2 buttons; a cancel button, and a trigger-action button.

    Normally, the box is created and opened with the single message:

        EnterBox request:'someString'

    which returns nil if aborted and the entered string otherwise.

    However, to control more details of the box, it may also be created first

    (EnterBox new) and then modified as appropriate before its shown.

    For example, the boxes title can be changed with: 

        aBox title:'some string'

    The two button-labels default to 'abort' and 'ok'; 

    they can be changed using:

        aBox okText:'someString'

        aBox abortText:'someString'

    The initial text in the enterfield can be set using:

        aBox initialText:'someString'

    when the ok-button is pressed, an action is performed, which is

    set using:

        aBox action:[ ... ]

    the abort-action defaults to no-action, but can also be set.

    The box can be opened modal (i.e. the currently active view will

    be suspended) or modeless. The default is modal (i.e. sending #open

    is equivalent to #openModal).

    Most of the above is also available via messages to Dialog for ST-80 compatibility

    (i.e. Dialog request:someString' is the same as EnterBox request:'someString')

    [author:]

        Claus Gittinger

    [see also:]

        DialogBox

        EnterBox2 YesNoBox ListSelectionBox FileSelectionBox FileSaveBox

        EditField EditTextView

        EnterFieldGroup

"

!

examples 

"

    examples (for ST-80 compatibility, please use Dialog messages):

    simple (most common):

                                                                        [exBegin]

        |someString|

        someString := EnterBox request:'enter a string'.

        Transcript showCR:someString

                                                                        [exEnd]

    creating first, setting actions and manually opening:

                                                                        [exBegin]

        |box|

        box := EnterBox new.

        box title:'your name please:'.

        box action:[:arg | Transcript showCR:'entered: ''' , arg printString , ''''].

        box open

                                                                        [exEnd]

    turning off trimming of leading/trailing spaces (seldom required):

                                                                        [exBegin]

        |box|

        box := EnterBox new.

        box title:'your name please:'.

        box action:[:arg | Transcript showCR:'entered: ''' , arg printString , ''''].

        box trimBlanks:false.

        box open

                                                                        [exEnd]

    non-modal

    (just for the demo; it does not really make sense,

     since cancel-button has no effect):

                                                                        [exBegin]

        |box|

        box := EnterBox new.

        box title:'your name please:'.

        box action:[:arg | Transcript showCR:'entered: ' , arg printString].

        box openModeless

                                                                        [exEnd]

    for easier instance creation, there are also some combination methods:

                                                                        [exBegin]

        |box|

        box := EnterBox 

                 title:'your name please:'

                 action:[:arg | Transcript showCR:'entered: ' , arg printString].

        box open

                                                                        [exEnd]

    If the box is needed to ask for a simple string, you can also use the

    #request method, to bring up a box, let it ask for something and return

    the entered string. This method will return nil, if the box was

    closed with the 'abort' button.

    Example:

                                                                        [exBegin]

        |box string|

        box := EnterBox request:'input some string:'.

        string isNil ifTrue:[

            Transcript showCR:'no input'

        ] ifFalse:[

            Transcript showCR:('the entered string was: ' , string)

        ]

                                                                        [exEnd]

    of course, this can be written shorter as:

                                                                        [exBegin]

        |string|

        string := EnterBox request:'input some string:'.

        string isNil ifTrue:[

            Transcript showCR:'no input'

        ] ifFalse:[

            Transcript showCR:('the entered string was: ' , string)

        ]

                                                                        [exEnd]

    A box for passwords is created with:

                                                                        [exBegin]

        |box|

        box := EnterBox 

                 title:'your name please:'

                 action:[:arg | Transcript showCR:'entered: ' , arg printString].

        box enterField passwordCharacter:$*.

        box showAtPointer

                                                                        [exEnd]

    or simply:

                                                                        [exBegin]

        |string|

        string := EnterBox requestPassword:'enter your password:'.

        Transcript showCR:string.

                                                                        [exEnd]

    ATTENTION:

    for ST-80 compatibility, please use protocol from Dialog 

    (which is an alias for DialogBox):

                                                                        [exBegin]

        |string|

        string := Dialog request:'input some string:'.

        string isNil ifTrue:[

            Transcript showCR:'no input'

        ] ifFalse:[

            Transcript showCR:('the entered string was: ' , string)

        ]

                                                                        [exEnd]

    and:    

                                                                        [exBegin]

        |string|

        string := Dialog requestPassword:'enter your password:'.

        Transcript showCR:string.

                                                                        [exEnd]

"

    "Modified: 16.11.1995 / 21:28:11 / cg"

! !

!EnterBox class methodsFor:'instance creation'!

action:aBlock

    "create and return a new EnterBox 

     which will evaluate aBlock when 'ok' is pressed"

    ^ (self new) action:aBlock

    "(EnterBox action:[:string | Transcript showCR:string]) showAtPointer"

!

title:titleString

    "create and return a new EnterBox with title aString"

    ^ self new title:titleString

!

title:titleString action:aBlock

    "create and return a new EnterBox with title aString,

     which will evaluate aBlock when 'ok' is pressed"

    ^ (self title:titleString) action:aBlock

!

title:titleString okText:okText abortText:abortText action:aBlock

    "create and return a new EnterBox with title aString, and buttons showing

     okText and abortText; it will evaluate aBlock when 'ok' is pressed"

    ^ (self title:titleString okText:okText action:aBlock) abortText:abortText 

!

title:titleString okText:okText action:aBlock

    "create and return a new EnterBox with title aString, and ok button showing

     okText; it will evaluate aBlock when 'ok' is pressed"

    ^ (self title:titleString action:aBlock) okText:okText

! !

!EnterBox class methodsFor:'defaults'!

defaultExtent

    "return the default extent of my instances.

     The value returned here is usually ignored, and

     the value from preferredExtent taken instead."

    ^ (Screen current pixelPerMillimeter * (60 @ 20)) rounded

    "Modified: / 22.1.1998 / 09:57:26 / md"

    "Modified: / 27.7.1998 / 20:15:52 / cg"

!

minExtent

    ^ self defaultExtent

! !

!EnterBox class methodsFor:'easy startup'!

request:aTitle

    "create and show an enterBox asking for aTitle.

     Return the enterred string or an empty string (if abort was pressed).

     The string may be empty, in case return was pressed immediately."

    ^ self new request:aTitle

    "

     EnterBox request:'enter a string'

    "

    "Modified: 27.1.1996 / 14:34:23 / cg"

!

requestPassword:aTitle

    "create and show an enterBox asking for aTitle.

     The box is setup to NOT display entered characters (as with password entry).

     Return the entered string or nil (if abort was pressed).

     The string may be empty, in case return was pressed immediately."

    ^ self new requestPassword:aTitle

    "

     |s|

     s := EnterBox requestPassword:'enter a string'.

     Transcript showCR:'you entered: ' , s

    "

    "Created: 16.11.1995 / 21:25:08 / cg"

! !

!EnterBox methodsFor:'accessing-behavior'!

entryCompletionBlock:aBlock

    "define an entryCompletion block; if nonNil, that one

     is evaluated if TAB is pressed in the field and should

     try to complete the input.

     The block gets the current contents and the field itself as optional arguments

     (i.e. it can be a 0, 1 or 2-arg block).

     Typically used with fileName-boxes."

    enterField entryCompletionBlock:aBlock

    "Modified: 22.5.1996 / 15:19:31 / cg"

!

trimBlanks:aBoolean

    "set/clear blank trimming in the returned string.

     By default, leading and trailing spaces are removed from the input;

     setting trimBlanks to false disables this behavior.

     (not normally useful in most applications)"

    trimBlanks := aBoolean

    "Created: 22.5.1996 / 15:23:45 / cg"

! !

!EnterBox methodsFor:'accessing-components'!

enterField

    "provide access to the entryfield"

    ^ enterField

    "Created: 16.11.1995 / 21:23:48 / cg"

!

labelField

    "provide access to the labelfield"

    ^ labelField

    "Created: 16.11.1995 / 21:23:48 / cg"

! !

!EnterBox methodsFor:'accessing-contents'!

contents

    "return my contents"

    ^ enterField contents

!

contents:aString

    "set my contents"

    enterField contents:aString

!

initialAnswer:aString

    "for protocol compatibility - an alias for initialText:"

    self initialText:aString

!

initialText:aString

    "define the initial text in the enterfield. all will be selected initially"

    self initialText:aString selected:true

!

initialText:aString selectFrom:start to:stop

    "define the initial text in the enterfield, and the part to be selected"

    self initialText:aString.

    self selectFromCharacterPosition:start to:stop

!

initialText:someString selected:selected

    "define the initial text in the enterfield; optionally, all is selected initially"

    enterField initialText:someString selected:selected

!

selectFrom:start to:stop

    "define the initial selection in the enterfield"

    enterField selectFromLine:1 col:start toLine:1 col:stop

!

selectFromCharacterPosition:start to:stop

    "define the initial selection in the enterfield"

    enterField selectFromCharacterPosition:start to:stop

! !

!EnterBox methodsFor:'accessing-look'!

noCancel

    "make the cancel button invisible - i.e. only the ok button is shown.

     Not useful here, but useful with display-only textBoxes."

    abortButton beInvisible.

!

title:aString

    "set the title to be displayed at top of enterBox"

    |oldSize|

    aString ~= labelField label ifTrue:[

        oldSize := labelField extent.

        labelField label:aString.

        labelField forceResize.

        shown ifTrue:[

            labelField extent ~= oldSize ifTrue:[

                self resize

            ]

        ] ifFalse:[

            self sizeChanged:nil.

        ]

    ]

!

title:titleString okText:okString

    "set title and text in okbutton"

    (titleString ~= labelField label or:[okString ~= okButton label]) ifTrue:[

        okButton label:okString.

        okButton resize.

        labelField label:titleString.

        labelField forceResize.

        shown 

            ifTrue:[self resize]

            ifFalse:[ self sizeChanged:nil].

    ]

!

title:titleString okText:okString abortText:abortString

    "set title and texts in the buttons"

    (titleString ~= labelField label 

     or:[okString ~= okButton label

     or:[abortString ~= abortButton label]]) ifTrue:[

        okButton label:okString.

        okButton resize.

        abortButton label:abortString.

        abortButton resize.

        labelField label:titleString.

        labelField forceResize.

        shown 

            ifTrue:[self resize]

            ifFalse:[ self sizeChanged:nil].

    ]

! !

!EnterBox methodsFor:'change & update'!

update:something with:someArgument from:changedObject

    "sent if my enterbox thinks it needs more real-estate ..."

    changedObject == enterField ifTrue:[

	something == #preferredExtent ifTrue:[

	    shown ifTrue:[self resizeUnderPointer].