"

 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.

"

'From Smalltalk/X, Version:2.10.5 on 3-may-1995 at 2:41:07 am'!

ModalBox subclass:#DialogBox

	 instanceVariableNames:'buttonPanel okButton okAction abortButton abortAction

		acceptReturnAsOK yPosition leftIndent addedComponents

		inputFieldGroup acceptOnLeave accepted tabableElements'

	 classVariableNames:''

	 poolDictionaries:''

	 category:'Views-DialogBoxes'

!

!DialogBox class methodsFor:'documentation'!

version

"

$Header: /cvs/stx/stx/libwidg/DialogBox.st,v 1.13 1995-05-10 02:29:19 claus Exp $

"

!

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.

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

	accepted         <Boolean>      after close: true if box was accepted

					(i.e. ok-Button was pressed)

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

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

"

!

examples

"

    mostly, DialogBox is used as an abstract class as a base for InfoBox, 

    YesNoBox etc.

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

    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

    two textlabels:

	DialogBox new

	    addTextLabel:'hello';

	    addTextLabel:'world';

	    addAbortButton; 

	    addOkButton; 

	    open

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

    preferedExtents 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:'real life:') == 0 ifTrue:[

		line := p nextLine.

	    ].

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

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

		firstName value: name asCollectionOfWords first.

		lastName  value: name asCollectionOfWords last

	    ].

	    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

	]

   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 on:fileName.

	l useIndex:false.

	l doubleClickAction:[:name | top okPressed].

	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 on:fileName.

	l useIndex:false.

	l doubleClickAction:[:name | top okPressed].

	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.

	]

    again, setting the boxes initial size and fixing it

    (let it ignore the components' preferedExtent):

	|top fixFrame l scr fileName|

	fileName := '' asValue.

	top := DialogBox new.

	top extent:300@300.

	fixFrame := View new.

	fixFrame extent:(1.0 @ 300).

	l := FileSelectionList on:fileName.

	l useIndex:false.

	l doubleClickAction:[:name | top okPressed].

	scr := ScrollableView forView:l.

	fixFrame add:scr in:(0.0@0.0 corner:1.0@1.0).

	top addComponent:fixFrame.

	top addAbortButton; addOkButton.

	top openModal.

	top accepted ifTrue:[

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

	]

   adding a panel with checkBoxes:

	|top panel b value1 value2 value3 value4|

	value1 := true asValue.

	value2 := false asValue.

	value3 := false asValue.

	value4 := true asValue.

	top := DialogBox new.

	top extent:200@300.

	panel := VerticalPanelView new.

	b := CheckBox on:value1. b label:'check1'.

	panel addSubView:b.

	b := CheckBox on:value2. b label:'check2'.

	panel addSubView:b.

	b := CheckBox on:value3. b label:'check3'.

	panel addSubView:b.

	b := CheckBox on:value4. b label:'check4'.

	panel addSubView:b.

	top addComponent:panel.

	top addAbortButton; addOkButton.

	top open.

	top accepted ifTrue:[

	    Transcript show:'value1: '; showCr:value1 value.

	    Transcript show:'value2: '; showCr:value2 value.

	    Transcript show:'value3: '; showCr:value3 value.

	    Transcript show:'value4: '; showCr:value4 value.

	]

   same, using a more convenient interface:

	|box value1 value2 value3 value4|

	value1 := true asValue.

	value2 := false asValue.

	value3 := false asValue.

	value4 := true asValue.

	box := DialogBox new.

	box extent:200@300.

	box addCheckBox:'check1' on:value1.

	box addVerticalSpace.

	box addCheckBox:'check2' on:value2.

	box addVerticalSpace.

	box addCheckBox:'check3' on:value3.

	box addVerticalSpace.

	box addCheckBox:'check4' on:value4.

	box addAbortButton; addOkButton.

	box open.

	box accepted ifTrue:[

	    Transcript show:'value1: '; showCr:value1 value.

	    Transcript show:'value2: '; showCr:value2 value.