Scripted dialogs. Dialog Technique supported by the Adobe Script Engine.

How to use sample scripts.

EZ Dialogs

// Sample # 1
DialogBegin -100,-15,100,50, "EZ  Sample # 1"
PushButton 130, 35, 190, 55, "OK"
PushButton 55, 35,115, 55, "Cancel"
Static 15,10,205,25, "Click some button."
DialogEnd >> result
Message Quote(result)
Return

Launch this script and inspect the dialog displayed. Position and caption of the dialog box is determined by the parameters used in the first line of the script. First two parameters are coordinates of the left top corner , next two parameters are coordinates of the right bottom corner of the dialog. Dialog contains 3 controls: 2 pushbuttons and a static control. Position ( relative to the dialog's left top ) and caption of each control is determined by the parameters of the script line which corresponds to each control. First two parameters are coordinates of the left top corner , next two parameters are coordinates of the right bottom corner of a control.
Script command 'DialogEnd' actually displays dialog. Dialog stays until user hit any pushbutton  or GoAway button in the caption bar of the dialog . After that variable 'result' obtains the following information ( separated by commas ) :
- caption of the pushbutton that killed the dialog
- state of each control
Try this script twice hitting "OK" and "Cancel". Inspect the content of the variable 'reply' displayed by the Message command.

.. 
Note that only first tokens are different. Other information poured into 'result' is not that important, because pushbuttons and static controls can not have different states. This kind of information may be parsed out of the reply as shown in the following script:
// Sample # 1a
DialogBegin -100,-15,100,50, "EZ  Sample # 1a"
PushButton 130, 35, 190, 55, "OK"
PushButton 55, 35,115, 55, "Cancel"
Static 15,10,205,25, "Click some button."
DialogEnd >> result
Message Quote(result)
If empty(buttonHit)
 Message "User hit Go Away button."
Else
 Message "User hit button " + buttonHit
Endif
Return

Script Engine supports the following controls:
- pushbutton : PushButton
- static text control : Static
- edit text control : Edit
- checkbox : CheckBox
- radiobutton : RadioButton
- listbox : ListBox
- rectangular frame : Rect
Only edit controls, checkboxes, radiobuttons and listboxes may have different states. For edit controls state is a text in the control surrounded by quotes, for listboxes state is the name of the selected item in quotes, for checkboxes and radiobuttons state is either 0 ( unchecked ) or 1  ( checked ). However, command 'DialogEnd' lists states of all controls as they were listed between commands 'DialogBegin' and 'DialogEnd' including those controls which do not change states (pushbuttons, static text controls, rectangular frames) . Script is responcible for parsing and retrieving the right ones.

// Sample #2

DialogBegin -170,-50,170,50, "EZ Sample # 2"
PushButton 260,10,320,30,"OK"
PushButton 260,35,320,55,"Cancel"
Static 15,10,135,30,"Apply text styles:"
CheckBox 15,30,135,50,"Bold"
CheckBox 15,50,135,70,"Italic"
CheckBox 15,70,135,90,"Underline"
Static 150,10,240,25,"Apply font:"
ListBox 140,30,230,95,"Arial","Courier","Symbol","Times"
DialogEnd >> bHit,...,...,...,chkBold,chkItalic,chkUnderlined,...,fontName
If not(bHit = "OK")
 Return
EndIf

Check Bold and Italic, choose Courier, hit OK.

After dialog is dismissed the command 'DialogEnd' produces the following list:
"OK",0,0,0,1,1,0,0,"Courier"
This list will be parsed into the variables as follows:
bHit = "OK"
chkBold = 1
chkItalic = 1
chkUnderlined = 0
fontName = "Courier"
while information on pushbuttons and static text is dumped into trash variables denoted by elliplsis.

Presuming that some text is hilited in a PageMaker document, dialog in the sample #2 could be, for example, followed by the following script lines:

...................
// Sample #2, continue
If chkBold=1
 TypeStyle bold
EndIf
If chkItalic=1
 TypeStyle italic
EndIf
If chkUnderlined=1
 TypeStyle underlined
EndIf
Font fontName
Return

This is several remarkess on the Sample #2

(i) When dialog first displayed, checkboxes initially checked 'off '. To have them checked 'on' from the very beginning, modify one or more lines of the script as follows:
CheckBox 15,30,135,50,"Bold",1
CheckBox 15,50,135,70,"Italic",1
CheckBox 15,70,135,90,"Underline",1

(ii) Listbox should contain at list one item inserted, so the list that follows it's coordinates should not be empty. Also make sure that listed fonts are available.

Sample #3
DialogBegin -180,-75,180,40,"EZ Sample #3"
PushButton 270, 15, 330, 35, "OK"
PushButton 270, 50, 330, 70, "Cancel"

RadioButton 30,20,90,40,"Box",1
RadioButton 100,20,160,40,"Oval"
RadioButton 170,20,240,40,"Polygon"
Rect 25,15,245,45,""

RadioButton 30,70,90,90,"Red",1
RadioButton 100,70,160,90,"Green"
RadioButton 170,70,230,90,"Blue"
Rect 25,65,245,95,""

DialogEnd >> bHit, ...,..., drawBox, drawOval, drawPoly ,..., paintRed,paintGreen, paintBlue,...

If not(bHit="OK")
    Return
EndIf

New
GetPageRect >> pagerect
If drawBox=1
    Box pagerect
EndIf

If drawOval=1
    Oval pagerect
EndIf

If drawPoly=1
    Polygon pagerect
EndIf

If paintRed=1
    Color "Red"
EndIf

If paintGreen=1
    Color "Green"
EndIf

If paintBlue=1
    Color "Blue"
EndIf

Return

Dialog presented by this script contains two independent groups of radiobuttons - one for shape and one for color. Radiobuttons are in group if their script lines follow each other without being separated by any other control. In this sample, shape buttons are separated from the color buttons by the line Rect 25,75,235,105,"". If , for example, rectangles were removed from the dialog script, then the dialog would have just one group of radiobuttons and no more then one button could be checked 'on' at a time.

Chose options "Oval" and "Red" and hit "OK". Command 'DialogEnd' produces the following list of values:
"OK",0,0,0,1,0,0,1,0,0,0
Variables listed to the right of 'DialogEnd' gets assigned as follows:
bHit = "OK"
drawBox = 0
drawOval = 1
drawPoly = 0
paintRed = 1
paintGreen = 0
paintBlue = 0
After dialog is done, the script opens new document, measures size and position of first page in the document, inscribes oval into the page and paints the oval into red.

Scripted dialog engine - second generation.

Dialog definition construct.

'DialogBegin' and 'DialogEnd' commands.

Command 'DialogEnd' does not require parameters. Normally 'DialogEnd' is followed by assignment arrow ' >> ' and one or several names of  a variables.
Reply provided by the 'DialogEnd' command consists of the following comma separated tokens:
First token ( quoted string ) - the caption of the button which got hit by user to complete the dialog.
After the first token follows the information on the state of all controls in the dialog box, one token per control, in the order the controls was defined within DialogBegin ... DialogEnd construct.  Content of a token depends on the type of a control as follows:

Description of the state of a multiple choice listbox looks like "\"item1\",\"item3\",\"item5\""  where \" means quote inside the quoted string. Function unquote( ... ) when applied to such a string converts it into normal comma separated list  "item1","item3","item5" .  Superposition of the quotes is necessary to keep all information about multiple selection as a single token in a list provided by the 'DialogEnd' command.  If not packed into a single token this list could create parsing problems because script ( and script engine ) a priori does not know how many items in a list box will be selected by user.

Suppose that user checked Radio Button 1 on, checked Check Box 1 on, Check Box 2 off, selected "Choice 1" in a simple list box and "Option 1" and "Option 3" in a multiple choice listbox ( use Ctrl - click for multiple selection )
Click pushbutton "OK" to dismiss the dialog. Normally any pushbutton completes the dialog unless it binded with a callback subscript.

Now look at the Dialog Info displayed by the script.

Let's walk along the displayed list.

Here is an example of parsing the reply of the 'DialogEnd' command:

DialogBegin -100,-100,100,25,"Test various controls"
PushButton 5,5,95,20,"OK"
PushButton 105,5,195,20,"Cancel"
RadioButton 15,30,80,40,"Radio Button 1",1
RadioButton 15,45,80,55,"Radio Button 2"
Rect 10,25,85,60,"Frame"
ListBoxMulti 100,25,180,80,"Option 1","Option 2","Option 3"
CheckBox 100,85,180,95,"Check Box 1"
CheckBox 100,100,180,110,"Check Box 1"
ListBox 10,70,80,112,"Choice 1","Choice 2","Choice 3"
DialogEnd >> buttonHit, ..., ..., rad1, rad2, ..., SelectedOptions, chk1, chk2, SelectedChoice, ...
If not ( buttonHit = "OK" )
 Message "Dialog canceled"
 Return
End If
SelectedOptions = UnQuote(SelectedOptions)
info = "User selected " + Str(Len(SelectedOptions)) + " options from the multiple choice listbox."
Message info
Return

Control definition statements.

First 4 parameters are expected to be integer and to specify a position and a size of the control: xLeft, yTop, xRight, yBottom. Coordinates of a control are always relative to the left top corner of the dialog box. Position of the control should not drop out of the dialog box.
Coordinates are followed by the Properties of the control. Properties form a comma separated list of the variable length. In another words, everything starting with 5th parameter in any control definition statement falls into Properties. The structure of Properties depends on the type of a control. Some tokens of Properties are optional and substituted by default values when omitted. Required parameters always go before optional ones, so one can omit any number of the optional parameters from the end of a list, but not in the middle of the list. As soon as an optional parameter is omitted, all optional parameters following this one should be omitted too. Parameters included into Properties are listed below for each type of a control.
 

default values in RED	5th Parameter.	6th Pararameter.	7th Parameter.
PushButton	Caption (quoted string)	ignored	0 if disabled (greyed out)  1 if enabled
Rect	Text (quoted string) to be placed at the left top  corner of the rectangular frame	None	None
CheckBox  RadioButton	Caption (quoted string)	0 if unchecked  1 if checked	0 if disabled  1 if enabled
Static  Edit  EditWin	Text (quoted string)	0 if disabled  1 if enabled	None
ListBox  ComboBox	List of comma separated quoted strings defining  items listed in a listbox	Numeric parameter following the list of items:  0 if disabled  1 if enabled	Initial selection as a quoted string.  By default the first item in the list is selected. Initial selection should be typed exactly as it was mentioned in the item list, sensitively to case and leading/trailing white characters.
ListBoxMulti	List of comma separated quoted strings defining  items listed in a listbox	Numeric parameter following the list of items:  0 if disabled  1 if enabled	Initial selection as a comma separated list of quoted strings . By default the first item in the list is selected. Initial selection should be typed exactly as it was mentioned in the item list, sensitively to case and leading/trailing white characters.

 

 Examples of simple listboxes:

Script	Initial state of the dialog
DialogBegin -50,-50,50,20,"ListBox #1"  ListBox 5,5,95,40,"Choice 1","Choice 2","Choice 3"  PushButton 5,45,95,65,"OK"  DialogEnd  Return
DialogBegin -50,-50,50,20,"ListBox #2"  ListBox 5,5,95,40,"Choice 1","Choice 2","Choice 3",0  PushButton 5,45,95,65,"OK"  DialogEnd  Return
DialogBegin -50,-50,50,20,"ListBox #3"  ListBox 5,5,95,40,"Choice 1","Choice 2","Choice 3",1,"Choice 3"  PushButton 5,45,95,65,"OK"  DialogEnd  Return

Examples of multiple choice listboxes:

Script	Initial state of the dialog
DialogBegin -50,-50,50,25,"ListBoxMulti #1"  ListBoxMulti 5,5,95,50,"Option 1","Option 2","Option 3","Option 4"  PushButton 5,55,95,70,"OK"  DialogEnd  Return
DialogBegin -50,-50,50,25,"ListBoxMulti #2"  ListBoxMulti 5,5,95,50,"Option 1","Option 2","Option 3","Option 4",1,"Option 2","Option 4"  PushButton 5,55,95,70,"OK"  DialogEnd  Return

Important note: Do not confuse Properties of the control ( a list ) and a token included into the string reported by 'DialogEnd' command. This single token is a kind of digest or brief of the full Properties list. The informational bottleneck of the 'dialogend' command could not be widened without compromising on backward compatibility. Thus, for retrieving the full information about the current state of a control there exist another mechanism  - see CallBack subscripts below.

Behaviour of a dialog control when hit by user:

Default behaviour of the controls when clicked by user.

CallBack subscripts.

Let 's modify the first example so that a callback subscript  demonstrates  how GetPaneState/SetPaneState commands work.
 
// script begins
DialogBegin -100,-100,100,35,"Show Properties"
PushButton 5,5,95,20,"OK"
PushButton 105,5,195,20,"Cancel"
RadioButton 15,30,80,40,"Radio Button 1",1
RadioButton 15,45,80,55,"Radio Button 2"
Rect 10,25,85,60,"Frame"
ListBoxMulti 100,25,180,80,"Option 1","Option 2","Option 3"
CheckBox 100,85,180,95,"Check Box 1"
CheckBox 100,100,180,110,"Check Box 1"
ListBox 10,70,80,112,"Choice 1","Choice 2","Choice 3"
PushButton 30,120,170,130,"Show Properties"
CallBack ShowProperties
DialogEnd >> DialogInfo
Message Str(DialogInfo)
Return

Sub ShowProperties
Loop i = 1,9
GetPaneState i >> Prop[i]
EndLoop
Message "PushButton \"OK\" has the following Properties: " + Str(Prop[1])
Message "PushButton \"Cancel\" has the following Properties: " + Str(Prop[2])
Message "Radio Button 1 has the following Properties: " + Str(Prop[3])
Message "Radio Button 2 has the following Properties: " + Str(Prop[4])
Message "Rectangular frame has the folowing Properties: " + Str(Prop[5])
Message "Multiple selection ListBox has the following Properties: " + Str(Prop[6])
Message "Check Box 1 has the following Properties: " + Str(Prop[7])
Message "Check Box 2 has the following Properties: " + Str(Prop[8])
Message "Single selection ListBox has the following Properties: " + Str(Prop[9])

Return
//script ends
 
Paste this script into the Script Palette ( click here to recall how to do it ) and run the script. Script displays a dialog which differs from the one from the previous example only by one new pushbutton with the caption "Show Properties." Feel free to click on and modify any controls except of pushbuttons. After that hit the pushbutton with the caption "Show Properties". See: dialog does not go away, because pushbutton is bound with a callback subscript and its dismissing behaviour is overruled. Instead of that the subscript ( named also ShowProperties)  starts working. This subscript retrieves Properties of each control and displays it for you in a nested dialog. Read and compare the Properties with the state of controls. Hit "OK" on the message, alternate the controls in the dialog and ask to "Show Properties" again and again. As soon as you are done, hit "OK", "Cancel" or "x" button in the dialog and the lesson is over.

The next example shows how callback subscript can alternate the state of the other controls in the dialog.

// script begins
DialogBegin -100,-50,100,20,"Type style"
CheckBox 5,5,70,15,"Normal",1
CallBack Normal
CheckBox 5,20,70,30,"Bold"
CallBack UpdateNormalChkBox
CheckBox 75,5,130,15,"Italic"
CallBack UpdateNormalChkBox
CheckBox 75,20,130,30,"Underline"
CallBack UpdateNormalChkBox
CheckBox 135,5,195,15,"Strikethru"
CallBack UpdateNormalChkBox
CheckBox 135,20,195,30,"Reverse"
CallBack UpdateNormalChkBox
PushButton 30,40,85,55,"OK"
PushButton 115,40,170,55,"Cancel"
DialogEnd
Return

Sub Normal
GetPaneState 1 >> caption,normal,...
If normal = 1
// check off all other check boxes
SetPaneState 2,"Bold",0,1
SetPaneState 3,"Italic",0,1
SetPaneState 4,"Underline",0,1
SetPaneState 5,"Strikethru",0,1
SetPaneState 6,"Reverse",0,1
Else
// the only way to turn "Normal" off is to check on another button
// Check "Normal" back to 'on' to prevent direct unchecking
SetPaneState 1,"Normal",1,1
End If
Endsub

Sub UpdateNormalChkBox
GetPaneState 2 >> caption,bold,...
GetPaneState 3 >> caption,italic,...
GetPaneState 4 >> caption,underline,...
GetpaneState 5 >> caption,strikethru,...
GetpaneState 6 >> caption,reverse,...
// Nomal should be 'on' only if bold=italic=underline=strikethru=reverse=0
If bold,italic,underline,strikethru,reverse=0,0,0,0,0
SetPaneState 1,"Normal",1,1
Else
SetPaneState 1,"Normal",0,1
End If
Endsub

// script ends
 
Expected behaviour of this type style check boxes is the same as in the Type > Character dialog.
 
 
 Next examples shows live modification of the document.

// Script begins

DialogBegin -50,-50,50,60,"Apply paragraph style"
GetStylenames >> ...,styles
ListBox 5,5,95,100,styles
CallBack Apply
DialogEnd
Return

Sub Apply
GetPaneState 1 >> PaneState
// last token of PaneState is a selected style
selStyle = PaneState(Len(PaneState))
style selStyle
EndSub

// Script ends

Open any PageMaker document in a layout view. Put text insertion point into some text - or type in a bogus text if necessary and leave insertion point in the text. Launch the script. Position the dialog box to see simultaneously the dialog and the selected paragraph in the document. Try to hilite different styles in a listbox. Watch what happens to the text.
 

Useful hints and reminders.

Example ( modification of the previous example )

DialogBegin -50,-50,50,60,"Apply paragraph style"
GetStylenames >> ...,styles
ListBox 5,5,95,100,styles
CallBack Apply
DialogEnd
Return

Sub Apply
GetArgs >> prevStyle
GetPaneState 1 >> PaneState
// last token of PaneState is a selected style - see definition of ListBox's Properties
selStyle = PaneState(Len(PaneState))
Style selStyle
Message "Style changed from "+ prevStyle + " to "+ selStyle
EndSub