"

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

"

ModalBox subclass:#DialogBox

	instanceVariableNames:'buttonPanel okButton okAction abortButton abortAction

		acceptReturnAsOK yPosition leftIndent rightIndent bindings

		addedComponents inputFieldGroup acceptOnLeave acceptValue

		tabableElements hideOnAccept acceptCheck needResize'

	classVariableNames:''

	poolDictionaries:''

	category:'Views-DialogBoxes'

!

!DialogBox class methodsFor:'documentation'!

copyright

"

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

"

    this class implements the common behavior of dialogboxes.

    DialogBox is an (abstract) superclass of many other boxes - see InfoBox,

    WarningBox, YesNoBox etc. for concrete examples.

    Most of them simply add buttons or other elements.

    For programmatically created boxes, instances support adding of components

    in a top-to-bottom fashion, and also keep track of added text-fields and,

    since they are most common, automatically create an EnterFieldGroup for

    them.

    Caveat: more adding support is required - especially for row-wise

    construction.

    Historic note:

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

        there were YesNoBox, EnterBox, InfoBox and so on.

        ST-80 has all this defined in the common Dialog.

        Therefore, for compatibility, many ST/X methods defined here in Dialogs 

        class protocol simply dispatch to some other boxes class method.

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

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

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

    instance variables:

        buttonPanel      <PanelView>    contains the button(s)

        okButton         <Button>       the ok-Button

        okAction         <Block>        the action to be performed when ok is pressed,

                                        or return is pressed.

        acceptReturnAsOK <Boolean>      if true, pressing the return-key counts

                                        as if ok was pressed. Default is true.

        abortButton      <Button>       the cancel-Button

        abortAction      <Block>        the action to be performed when cancel is

                                        pressed.

        yPosisition      <Integer>      current y position when adding components

        leftIndent       <Integer>      left inset to use when adding components

        rightIndent      <Integer>      right inset to use when adding components

        addedComponents  <Collection>   programmatically added components

        inputFieldGroup  <EnterFieldGroup>   

                                        for added input fields

        acceptOnLeave    <Boolean>      if true (the default) and there are 

                                        tabable inputFields, accept and close when

                                        the last field is left. If false, the ok

                                        button must be pressed to close the box.

        acceptedValue    v(<Boolean>)   valueHolder on a boolean

                                        after close: holds true if box was accepted

                                        (i.e. ok-Button was pressed), false if box was

                                        closed via cancel or window manager.

    For compatibility with ST-80, this class is also available under

    the global names DialogView and Dialog (see patches file).

"

!

examples

"

    historically, DialogBox was used as an abstract class as a base for InfoBox, 

    YesNoBox etc. However, the programmatic construction protocol (addComponent)

    now allows those classes to be easily replaced and future versions may

    do this and make those subclasses obsolete.

    For most simple standard dialogs, there are ready to use

    methods in the class protocol.

    For example:

      info & warnings:

        Dialog information:'hi there'

        Dialog warn:'oops'

      yes/no questions:

        (Dialog confirm:'is this simple ?')

        ifTrue:[

            Transcript showCr:'thats what I expected'

        ] ifFalse:[

            Transcript showCr:'read more examples and documentation'

        ]

      yes/no question with cancel option:

        |answer|

        answer := Dialog confirmWithCancel:'is this simple ?'.

        answer isNil ifTrue:[

            Transcript showCr:'no easy decision'

        ] ifFalse:[

            answer ifTrue:[

                Transcript showCr:'thats what I expected'

            ] ifFalse:[

                Transcript showCr:'read more examples and documentation'

            ]

        ]

      asking for a string:

        |s|

        s := Dialog request:'enter your name, please:'.

        s notEmpty ifTrue:[

            Transcript showCr:'you entered: ' , s.

        ]

      asking for a string with given default:

        |s|

        s := Dialog 

                request:'enter your name, please:'

                initialAnswer:(OperatingSystem getLoginName).

        s notEmpty ifTrue:[

            Transcript showCr:'you entered: ' , s.

        ]

      asking for a filename:

        |s|

        s := Dialog 

                requestFileName:'select a file, please:'

                default:''.

        Transcript show:'you entered: '; showCr:s.

      with changed button label and pattern:

        |s|

        s := Dialog 

                requestFileName:'select a file, please:'

                default:''

                ok:'show'

                abort:'cancel'

                pattern:'*.rc'.

        Transcript show:'you entered: '; showCr:s.

      asking for a password:

        |s|

        s := Dialog 

                requestPassword:'enter your secret, please:'.

        Transcript show:'you entered: '; showCr:s.

    However, you can construct dialogs programmatically, as shown in

    the following examples:

    basic (unusable) example:

        DialogBox new open

    still unusable - only an ok-button:

        DialogBox new addOkButton; open

    both ok- and abortButtons:

        DialogBox new addAbortButton; addOkButton; open

    with different ok-label:

        DialogBox new addAbortButton; addOkButtonLabelled:'yeah'; open

    adding a textlabel gives an infoBox:

        DialogBox new

            addTextLabel:'hello';

            addOkButton; 

            open

    a textlabel with abort- and okButton gives a yesNoBox:

        DialogBox new

            addTextLabel:'hello';

            addAbortButton; 

            addOkButton; 

            open

    the same, adjusting the labels contents to the left:

        |box|

        box := DialogBox new.

        (box addTextLabel:'hello') adjust:#left.

        box addAbortButton; 

            addOkButton; 

            open

    with modified buttons:

        |box|

        box := DialogBox new.

        (box addTextLabel:'are you certain ?') adjust:#left.

        box addAbortButtonLabelled:'not really'. 

        (box addOkButtonLabelled:'yes, absolutely') 

                activeBackgroundColor:Color red. 

        box open

    mswindows style:

        |b box|

        box := DialogBox new.

        (box addTextLabel:'are you certain ?') adjust:#left.

        b := Button new.

        b activeLogo:(Image fromFile:'bitmaps/cancel_down.bmp').

        b passiveLogo:(Image fromFile:'bitmaps/cancel_up.bmp').

        b focusLogo:(Image fromFile:'bitmaps/cancel_focus.bmp').

        b beImageButton.

        box addAbortButton:b.

        b := Button new.

        b activeLogo:(Image fromFile:'bitmaps/ok_down.bmp').

        b passiveLogo:(Image fromFile:'bitmaps/ok_up.bmp').

        b focusLogo:(Image fromFile:'bitmaps/ok_focus.bmp').

        b beImageButton.

        box addOkButton:b.

        box open

    two textlabels:

        DialogBox new

            addTextLabel:'hello';

            addTextLabel:'world';

            addAbortButton; 

            addOkButton; 

            open

    fixing the dialogs size (suppres it calculating its size from the

    preferredExtents of its components):

        DialogBox new

            label:'a simple dialog';

            addTextLabel:'hello';

            addAbortButton; 

            addOkButton; 

            extent:200@200;

            sizeFixed:true;

            open

    asking the box if it was closed via ok:

        (DialogBox new

            label:'a simple dialog';

            addTextLabel:'hello';

            addAbortButton; 

            addOkButton; 

            extent:200@200;

            sizeFixed:true;

            open

        ) accepted ifTrue:[

            Transcript showCr:'yes'

        ] ifFalse:[

            Transcript showCr:'no'

        ]

    textLabels are not limited to strings (although, the name which is

    used for ST-80 compatibility, suggests it):

        DialogBox new

            addTextLabel:(Image fromFile:'bitmaps/garfield.gif');

            addOkButton; 

            open

        DialogBox new

            addTextLabel:'hello';

            addTextLabel:((Image fromFile:'bitmaps/garfield.gif')

                                magnifiedTo:200@150);

            addTextLabel:'world';

            addAbortButton; 

            addOkButton; 

            open

    adding an input field (on a string model):

        |stringModel|

        stringModel := '' asValue.

        (DialogBox new

            addTextLabel:'Please enter a string:';

            addInputFieldOn:stringModel; 

            addAbortButton; 

            addOkButton; 

            open

        ) accepted ifTrue:[

            Transcript showCr:'entered: ', stringModel value

        ]

    multiple input fields (notice, that the dialog connects the fields

    in a group, so stepping is allowed via Cursor and Return keys):

        |firstName lastName|

        firstName := '' asValue.

        lastName := '' asValue.

        (DialogBox new

            addTextLabel:'Please enter your name:';

            addInputFieldOn:firstName; 

            addVerticalSpace;

            addInputFieldOn:lastName; 

            addAbortButton; 

            addOkButton; 

            open

        ) accepted ifTrue:[

            Transcript showCr:'entered: ', firstName value , ' ' , lastName value

        ]

    of course, the model may contain a value initially:

        |firstName lastName p line i name|

        firstName := '' asValue.

        lastName := '' asValue.

        p := PipeStream readingFrom:'finger ' , OperatingSystem getLoginName.

        p notNil ifTrue:[

            line := p nextLine.

            (i := line findString:'Name:') ~~ 0 ifTrue:[

                name := line copyFrom:(i + 'Name:' size).

            ] ifFalse:[

                (i := line findString:'real life:') == 0 ifTrue:[

                    line := p nextLine.

                ].

                (i := line findString:'real life:') ~~ 0 ifTrue:[

                    name := line copyFrom:(i + 'real life:' size).

                ]

            ].

            name notNil ifTrue:[

                firstName value: name asCollectionOfWords first.

                lastName  value: name asCollectionOfWords last.

                Transcript showCr:'initially ' , firstName value , ' ' , lastName value.

            ].

            p close.

        ].

        (DialogBox new

            addTextLabel:'Please enter your name:';

            addInputFieldOn:firstName; 

            addVerticalSpace;

            addInputFieldOn:lastName; 

            addAbortButton; 

            addOkButton;

            open

        ) accepted ifTrue:[

            Transcript showCr:'entered: ', firstName value , ' ' , lastName value

        ]

    validated password entry:

        |box firstEntry secondEntry|

        firstEntry := '' asValue.

        secondEntry := '' asValue.

        box := DialogBox new.

        (box addTextLabel:'Please enter your secret:') adjust:#left.

        (box addInputFieldOn:firstEntry) passwordCharacter:$*. 

        box addVerticalSpace.

        (box addInputFieldOn:secondEntry) passwordCharacter:$*. 

        box addAbortButton. 

        box addOkButton. 

        box open.

        box accepted ifTrue:[

            firstEntry value ~= secondEntry value ifTrue:[

                Transcript showCr:'wrong input - try again'

            ] ifFalse:[

                Transcript showCr:'entered: ', firstEntry value

            ]

        ]

   constructing a dialog from other elements:

     adding a fileSelectionList:

     (since the dialog adds the component with its preferred extent,

      ignoring the 300-height, this looks ugly ... 

      ... especially when resized vertically)

        |top l scr fileName|

        fileName := '' asValue.

        top := DialogBox new.

        l := FileSelectionList new.

        l useIndex:false.

        l doubleClickAction:[:name | top okPressed].

        l action:[:name | fileName value:name].

        scr := ScrollableView forView:l.

        scr extent:(1.0 @ 300).

        top addComponent:scr.

        top addAbortButton; addOkButton.

        top openModal.

        top accepted ifTrue:[

            Transcript show:'fileName: '; showCr:fileName value storeString.

        ]

    same, looks better, since the height is made larger (not using 

    fileLists preferredExtent):

        |top l scr fileName|

        fileName := '' asValue.

        top := DialogBox new.

        l := FileSelectionList new.

        l useIndex:false.

        l doubleClickAction:[:name | top okPressed].

        l action:[:name | fileName value:name].

        scr := ScrollableView forView:l.

        top addComponent:scr withExtent:300@300.

        top addAbortButton; addOkButton.

        top openModal.

        top accepted ifTrue:[

            Transcript show:'fileName: '; showCr:fileName value storeString.

        ]