"

 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 addedComponents

		inputFieldGroup acceptOnLeave acceptValue tabableElements

		hideOnAccept acceptCheck needResize autoAccept focusToOKOnLeave

		bindings namedComponents'

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

        The programmatic interface is best suited for row-wise

        arranged components; laying out elements in columns is a bit

        complicate - for complicated dialogs, it may be better to not use

        the automatic arrangement, but instead give explicit layouts to

        the components (in a subclass).

    Compatibility note:

        For ST-80 compatibility, DialogBox is also accessable under

        the global named 'Dialog' (which is the name of an ST-80 class,

        providing a very similar protocol).

        This may lead to confusion, if DialogBox is recompiled - you have

        to manually assign Dialog again to refer to the new DialogBox class.

        In future versions of ST/X, DialogBox may be renamed to Dialog.

    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.

        autoAccept       Boolean        if true, pressing ok (or return)

                                        sends #accept to all subcomponents.

                                        I.e. all subfields update their models

                                        first. The default is true.

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

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

    [author:]

        Claus Gittinger

    [see also:]

        Button CheckToggle Toggle

        EditField SelectionInListView FileSelectionList

        FramedBox Separator

        ( introduction to view programming :html: programming/viewintro.html )

"

!

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 of

    ST/X may do this and make those subclasses obsolete.

    However, dummy stubs will remain to exist for backward compatibility

    (i.e. do not fear using YesNoBox, EnterBox etc.)

    For most simple standard dialogs, there are ready to use

    methods in the class protocol.

    For example:

      info & warnings:

                                                                        [exBegin]

        Dialog information:'hi there'

                                                                        [exEnd]

                                                                        [exBegin]

        Dialog warn:'oops'

                                                                        [exEnd]

      yes/no questions:

                                                                        [exBegin]

        (Dialog confirm:'is this simple ?')

        ifTrue:[

            Transcript showCR:'thats what I expected'

        ] ifFalse:[

            Transcript showCR:'read more examples and documentation'

        ]

                                                                        [exEnd]

      yes/no question with cancel option:

                                                                        [exBegin]

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

            ]

        ]

                                                                        [exEnd]

      asking for a string:

                                                                        [exBegin]

        |s|

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

        s notEmpty ifTrue:[

            Transcript showCR:'you entered: ' , s.

        ]

                                                                        [exEnd]

      asking for a string with given default:

                                                                        [exBegin]

        |s|

        s := Dialog 

                request:'enter your name, please:'

                initialAnswer:(OperatingSystem getLoginName).

        s notEmpty ifTrue:[

            Transcript showCR:'you entered: ' , s.

        ]

                                                                        [exEnd]

      asking for a filename:

                                                                        [exBegin]

        |s|

        s := Dialog 

                requestFileName:'select a file, please:'

                default:''.

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

                                                                        [exEnd]

      with a namefiler pattern:

                                                                        [exBegin]

        |s|

        s := Dialog 

                requestFileName:'select a file, please:'

                default:''

                pattern:'*.rc'.

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

                                                                        [exEnd]

      another namefiler pattern:

                                                                        [exBegin]

        |s|

        s := Dialog 

                requestFileName:'select a file, please:'

                default:''

                pattern:'*.rc;*.st;*.h'.

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

                                                                        [exEnd]

      with changed button label and pattern:

                                                                        [exBegin]

        |s|

        s := Dialog 

                requestFileName:'select a file, please:'

                default:''

                ok:'show'

                abort:'cancel'

                pattern:'*.rc'.

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

                                                                        [exEnd]

      asking for a password:

                                                                        [exBegin]

        |s|

        s := Dialog 

                requestPassword:'enter your secret, please:'.

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

                                                                        [exEnd]

      multiple choice dialogs:

                                                                        [exBegin]

        Dialog 

           choose:'choose any' 

           fromList:nil

           values:nil

           buttons:#('one' 'two' 'three' 'four') 

           values:#(1 2 3 4) 

           lines:nil

           cancel:nil

                                                                        [exEnd]

      multiple choice dialog, with list & buttons:

                                                                        [exBegin]

         Transcript showCR:(

             Dialog 

                choose:'choose example' 

                fromList:#('one' 'two' 'three' 'four') 

                values:#(1 2 3 4) 

                buttons:#('five' 'six' 'seven')

                values:#(5 6 7)

                lines:4

                cancel:[Transcript flash. #aborted]

         )

                                                                        [exEnd]

    You can (and often have to) construct custom dialogs programmatically, 

    from individual components. As shown in the following examples:

    basic (unusable) example:

                                                                        [exBegin]

        DialogBox new open

                                                                        [exEnd]

    still unusable - only an ok-button:

                                                                        [exBegin]

        DialogBox new addOkButton; open

                                                                        [exEnd]

    both ok- and abortButtons:

                                                                        [exBegin]

        DialogBox new addAbortButton; addOkButton; open

                                                                        [exEnd]

    with different ok-label:

                                                                        [exBegin]

        DialogBox new addAbortButton; addOkButtonLabelled:'yeah'; open

                                                                        [exEnd]

    adding a (centered by default) textlabel gives an infoBox:

                                                                        [exBegin]

        DialogBox new

            addTextLabel:'hello';

            addOkButton; 

            open

                                                                        [exEnd]

    a textlabel with abort- and okButton gives a yesNoBox:

                                                                        [exBegin]

        DialogBox new

            addTextLabel:'hello';

            addAbortButton; 

            addOkButton; 

            open

                                                                        [exEnd]

    the same, adjusting the labels contents to the left:

                                                                        [exBegin]

        |box|

        box := DialogBox new.

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

        box addAbortButton; 

            addOkButton; 

            open

                                                                        [exEnd]

    with modified buttons:

                                                                        [exBegin]

        |box|

        box := DialogBox new.

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

        box addAbortButtonLabelled:'not really'. 

        (box addOkButtonLabelled:'yes, absolutely') 

                activeBackgroundColor:Color red. 

        box open

                                                                        [exEnd]

    mswindows style (different up/down bitmaps in buttons):

    ((try tabbing ...)

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    two textlabels:

                                                                        [exBegin]

        DialogBox new

            addTextLabel:'hello';

            addTextLabel:'world';

            addAbortButton; 

            addOkButton; 

            open

                                                                        [exEnd]

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

    preferredExtents of its components):

                                                                        [exBegin]

        DialogBox new

            label:'a simple dialog';

            addTextLabel:'hello';

            addAbortButton; 

            addOkButton; 

            extent:200@200;

            sizeFixed:true;

            open

                                                                        [exEnd]

    asking the box if it was closed via ok:

                                                                        [exBegin]

        (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'

        ]

                                                                        [exEnd]

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

    used for ST-80 compatibility, suggests it):

                                                                        [exBegin]

        DialogBox new

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

            addOkButton; 

            open

                                                                        [exEnd]

                                                                        [exBegin]

        DialogBox new

            addTextLabel:'hello';

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

                                magnifiedTo:200@150);

            addTextLabel:'world';

            addAbortButton; 

            addOkButton; 

            open

                                                                        [exEnd]

    adding an input field (on a string model):

                                                                        [exBegin]

        |stringModel|

        stringModel := '' asValue.

        (DialogBox new

            addTextLabel:'Please enter a string:';

            addInputFieldOn:stringModel; 

            addAbortButton; 

            addOkButton; 

            open

        ) accepted ifTrue:[

            Transcript showCR:'entered: ', stringModel value

        ]

                                                                        [exEnd]

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

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

                                                                        [exBegin]

        |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

        ]

                                                                        [exEnd]

    of course, the model may contain a value initially:

                                                                        [exBegin]

        |firstName lastName p line i name|