eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'EnterBox':
Home

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

Class: EnterBox

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--TopView
                  |
                  +--StandardSystemView
                     |
                     +--ModalBox
                        |
                        +--DialogBox
                           |
                           +--EnterBox
                              |
                              +--EnterBox2
                              |
                              +--EnterBoxWithList
                              |
                              +--FilenameEnterBox
                              |
                              +--ListSelectionBox
                              |
                              +--TextBox
Package:
stx:libwidg
Category:
Views-DialogBoxes
Version:
rev: 1.82 date: 2019/07/16 14:41:16
user: cg
file: EnterBox.st directory: libwidg
module: stx stc-classLibrary: libwidg
Author:
Claus Gittinger

Description:


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 functionality 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 it is 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')

Related information:

    DialogBox
    EnterBox2
    YesNoBox
    ListSelectionBox
    FileSelectionBox
    FileSaveBox
    EditField
    EditTextView
    EnterFieldGroup

Class protocol:

defaults
o  defaultExtent
return the default extent of my instances.
The value returned here is usually ignored, and
the value from preferredExtent taken instead.

o  minExtent

easy startup
o  request: aTitle
create and show an enterBox asking for aTitle.
Return the entered string or an empty string (if abort was pressed).
The string may be empty, in case return was pressed immediately.

usage example(s): 

     EnterBox request:'Enter a string:'

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

instance creation
o  action: aBlock
create and return a new EnterBox
which will evaluate aBlock when 'ok' is pressed.
Obsolete (but kept for backward compatibility):
boxes are never used without a proper label

usage example(s): 

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

o  title: titleString
create and return a new EnterBox with title aString

o  title: titleString action: aBlock
create and return a new EnterBox with title aString,
which will evaluate aBlock when 'ok' is pressed

o  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

o  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

Instance protocol:

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

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

accessing-components
o  enterField
provide access to the entryfield

o  labelField
provide access to the labelfield

accessing-contents
o  contents
return my contents

o  contents: aString
set my contents

o  initialAnswer: aString
for protocol compatibility - an alias for initialText:

o  initialText: aString
define the initial text in the enterfield. all will be selected initially

o  initialText: aString selectFrom: start to: stop
define the initial text in the enterfield, and the part to be selected

o  initialText: someString selected: selected
define the initial text in the enterfield; optionally, all is selected initially

o  selectFrom: start to: stop
define the initial selection in the enterfield

o  selectFromCharacterPosition: start to: stop
define the initial selection in the enterfield

accessing-look
o  noCancel
make the cancel button invisible - i.e. only the ok button is shown.
Not useful here, but useful with display-only textBoxes.

o  title: aString
set the title to be displayed at top of the enterBox.
This is NOT the window title.

o  title: titleString okText: okString
set title and text in okbutton.
This title is NOT the window title.

o  title: titleString okText: okString abortText: abortString
set title and texts in the buttons.
This title is NOT the window title.

change & update
o  update: something with: someArgument from: changedObject
sent if my enterbox thinks it needs more real-estate ...

initialization
o  addEnterField: aWidget
height

o  createEnterField
this has been extracted from the initialize method
to allow redefinition in subclasses. (FilenameEnterBox for example).
It shall return a new instance of the desired editField class.

o  initialize
bad name: this is the window label

o  reAdjustGeometry
sent late in the setup process - gives me a chance
to resize for new font dimensions

queries
o  computePreferredExtent
compute the boxes preferredExtent from the components' sizes

startup
o  request
open the box and return the entered string
or an empty string, if abort was pressed

o  request: title
set the title, open the box and return the entered string,
or the empty string, if abort was pressed.

usage example(s): 

     EnterBox request:'enter some string:'

     |bx|
     bx := EnterBox new.
     bx label:'foo bar baz'.
     bx request:'enter some string:'

o  request: title onCancel: cancelValue
set the title, open the box and return the entered string,
or cancelValue if abort was pressed.

usage example(s): 

     EnterBox request:'enter some string:' onCancel:nil

     |bx|
     bx := EnterBox new.
     bx label:'foo bar baz'.
     bx request:'enter some string:' onCancel:#foo

o  requestOnCancel: cancelValue
open the box and return the entered string
or cancelValue, if abort was pressed

o  requestPassword: title
set the title, set password mode, open the box and return the entered string
or nil, if abort was pressed

o  requestPassword: title onCancel: cancelValue
set the title, set password mode, open the box and return the entered string
or cancelValue, if abort was pressed

user actions
o  actionArgument
fetch the entered string, optionally trim spaces and return it

Examples:


examples (for ST-80 compatibility, please use Dialog messages): simple (most common): 
    |someString|

    someString := EnterBox request:'enter a string'.
    Transcript showCR:someString
creating first, setting actions and manually opening: 
    |box|

    box := EnterBox new.
    box title:'your name please:'.
    box action:[:arg | Transcript showCR:'entered: ''' , arg printString , ''''].
    box open
turning off trimming of leading/trailing spaces (seldom required): 
    |box|

    box := EnterBox new.
    box title:'your name please:'.
    box action:[:arg | Transcript showCR:'entered: ''' , arg printString , ''''].
    box trimBlanks:false.
    box open
non-modal (just for the demo; it does not really make sense, since cancel-button has no effect): 
    |box|

    box := EnterBox new.
    box title:'your name please:'.
    box action:[:arg | Transcript showCR:'entered: ' , arg printString].
    box openModeless
for easier instance creation, there are also some combination methods: 
    |box|

    box := EnterBox
             title:'your name please:'
             action:[:arg | Transcript showCR:'entered: ' , arg printString].
    box open
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: 
    |box string|

    box := EnterBox request:'input some string:'.
    string isNil ifTrue:[
        Transcript showCR:'no input'
    ] ifFalse:[
        Transcript showCR:('the entered string was: ' , string)
    ]
of course, this can be written shorter as: 
    |string|

    string := EnterBox request:'input some string:'.
    string isNil ifTrue:[
        Transcript showCR:'no input'
    ] ifFalse:[
        Transcript showCR:('the entered string was: ' , string)
    ]
A box for passwords is created with: 
    |box|

    box := EnterBox
             title:'your name please:'
             action:[:arg | Transcript showCR:'entered: ' , arg printString].
    box enterField passwordCharacter:$*.
    box showAtPointer
or simply: 
    |string|

    string := EnterBox requestPassword:'enter your password:'.
    Transcript showCR:string.
ATTENTION: for ST-80 compatibility, please use protocol from Dialog (which is an alias for DialogBox): 
    |string|

    string := Dialog request:'input some string:'.
    string isNil ifTrue:[
        Transcript showCR:'no input'
    ] ifFalse:[
        Transcript showCR:('the entered string was: ' , string)
    ]
and: 
    |string|

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

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 19 Apr 2024 13:10:17 GMT