Auto Dialogs and Live Dialogs

Auto Dialogs

Live Dialogs

• to create and initialise the Dialog Director environment (dd install...),
• to create & display the dialog (dd make dialog...),
• to repeatedly interact with the user (dd interact with user...),
• to get properties from dialog items (dd get...),
• to set properties of dialog items (dd set...),
• to close and delete the dialog (dd delete dialog...),
• and to finally clean up and remove the Dialog Director environment (dd uninstall).

dd install -- Suffix with any options
set d to dd make dialog <a dialog record>
repeat
	set i to dd interact with user -- Wait for user input
	if i = <index of an exit item> then
		exit repeat
	else if i = <index of an item that requires script support> then
		-- Update necessary dialog items, open another dialog, etc. E.g.:
		dd set <a property> of item <an index> of d to <a value>
	end if
end repeat
set theResult to dd get value of every item of d -- Get all dialog item values
dd delete d -- Remove the dialog
dd uninstall -- Sometime before we quit

Event Handlers

Notes and Documentation Conventions

• All parameters marked with an asteriskare optional.
• The default value of a parameter is shown in parenthesis following the description.
• Typing <command> + <control> + 'Q' will safely terminate a dd auto dialog or dd interact with user call with an error code 1. (This is handy to know if you manage to create a dialog with no push buttons.)

dd auto dialog:

set aDialog to {size:[320, 95], timeout after:60, contents:[
	{class:push button, bounds:[250, 65, 310, 85], name:"OK"}, 
	{class:push button, bounds:[170, 65, 230, 85], name:"Cancel"}, 
	{class:static text, bounds:[10, 10, 310, 10 + 32], contents:"A very simple dialog box.
Just testing!"}]}

get dd auto dialog aDialog with grayscale

This event creates an Auto Dialog containing the items described in the dialog record, it displays the dialog, it manages the interaction of the dialog with the user, then (when a push button is pressed) it deletes the dialog and returns a list of values, one for each dialog item (and one for the dialog window). This list represents the state of the dialog at termination. Passive items that do not have a value return null. The last item in the list is a rectangle that represents the final bounds of the dialog window. This can be used with a moveable window to set the initial bounds property of the dialog record such that on a subsequent call to dd auto dialog the previous window position is restored (see "Remember Pos.as" example). See the dialog item classes below to find what values they return and the section Introductory Examples to find how to extract them from the result.

The with fonts parameter specifies a list of font spec records that defines the global font table. This global font table stays in affect until a balancing call to dd uninstall. See class font spec for details.

Setting the grayscale parameter to true forces all DD windows to be drawn with grey backgrounds and item frames & group boxes, icon buttons and pop-up menus to adopt a 3D appearance similar to Apple's greyscale appearance for System 7.5 (AGA) guidelines. If used in conjunction with the Appearance Manager from Mac OS 8 then most other dialog items take on a similar 3D appearance.

The float above parameter makes the window float above either a single application (e.g. float above application "Finder") or all applications (float above every application). This may be used with any of the window styles. If used with dialogs whose window style is standard dialog, movable dialog, plain dialog or shadowed dialog then the window will behave in a modal fashion, beeping on clicks outside the window as usual. Additionally, if a floating, non-modal, DD window contains items that may accept keyboard input then clicking in that window transfers the keyboard focus to it. It will retain this focus until it is either closed, it no longer contains any items that may accept keyboard input or the user clicks in another window or the menu bar.

The given script: parameter is experimental. It is used to define a parent script context that contains handlers named via push button actions (see class push button). The standard usage is given script:me. This is only required if named action handlers are used and the script is not run as an applet (where the applets script will automatically provide a default context). When given script: is used a copy of the specified script is made. This uses extra memory and any changes made to global variables and script properties are lost when the dialog terminates and are not propagated back to the original script.

Note:

dd calc dialog bounds:

set dRect to dd calc window bounds [260, 95]

Use this event to pre-calculate the bounds property of a dialog. The rectangle returned will depend on your monitor size and setup as well as the [width, height] parameter. In combination with the rectangle returned by dd auto dialog or dd get bounds of <dialog> you can use this to remember and restore the last position of any movable dialog window. See the "Remember Pos.as" example script.

dd count dialogs:

This event returns the current number of open DD windows in the target application. If DD is not currently installed in the target application then dd count dialogs will return 0.

dd delete:

set dlog to dd make dialog ... -- dlog is now a dialog ref of the form 'dialog id #'


-- Deleting dialog Items
dd delete item 3 of dialog 1 -- Delete the 3rd dialog item of the front most dialog

dd delete first item of dlog -- Delete the first dialog item of dialog 'dlog'

dd delete items 2 thru 4 of dlog -- Delete dialog items 2, 3 & 4 of dialog 'dlog'

dd delete items -3 thru -1 of dialog id 1 -- Delete the last 3 dialog items of the back most dialog 'dlog'

-- Deleting dialogs
dd delete dialog 1 -- Delete the front most dialog
	- or -
dd delete dlog -- Delete the dialog 'dlog' and any in front of it
	- or -
dd delete dialog id 1 -- Delete all the dialogs (as dialog id 1 is the back most dialog)

1. Dialog Items: It dynamically deletes one or more dialog items from an active dialog. Once deleted all the properties of those items are inaccessible. Deleting from other then the end of the dialog items list causes the items to move up the list to fill the places of the deleted items (they don't move on screen). The dialog is automatically updated to reflect any visual changes.
2. Dialogs: It closes and deletes the specified dialog and any other dialogs in front of it and all their contents. Any references to dialogs become invalid once the dialog is deleted. Thus you must dd get any properties you need before deleting a dialog. See dd make dialog below for details of dialog numbers and IDs. This event may only be called between dd install and dd uninstall.

dd get:

set dlog to dd make dialog ... -- dlog is now a dialog reference

set n to dd get value of item 7 of dlog -- Retrieve the value of dialog item 7 of dlog
set n to dd get value of dialog item 7 of dialog 1 -- Same as above
set dVals to dd get value of every item of dlog -- Retrieve the value of every item of dlog and the dialog's bounds rect
set someVals to dd get value of items 3 thru -1 of dialog 1 -- Retrieve the value of items 3 to (contents's length)

set windowRect to dd get bounds of dlog -- Get the current bounds of the dialog window

A list containing the current value properties of any contiguous range of dialog items in any open dialog may be obtained by using a call of the form dd get value of items <first index> thru <last index> of <dialog ref>. Any dialog items that have no value property will return a null in the appropriate position in the list. See dd make dialog below for details of dialog numbers and IDs. This event may only be called between dd install and dd uninstall.

dd install:

dd install with grayscale

The dd install event creates and sets up the DD environment within the currently targeted application (i.e. the application that was the argument of the containing tell statement or the application that is running the script, if it's not in a tell statement). The font, grayscale & floating arguments apply to all dialogs created between this call and its matching dd uninstall call. Calling dd install more than once for the same target application and without calling dd uninstall between is safe and is ignored.

The dd install call is necessary prior to any calls to dd make dialog, dd interact with user, dd get, dd set, dd make, dd delete and dd uninstall. This call is not necessary if your script only makes calls to dd auto dialog, dd calc dialog bounds and dd count dialogs. However, if your script is likely to make more than one call to dd auto dialog then it is faster (and better practice) to call dd install at the beginning of your script (and dd uninstall at the end).

The with fonts parameter specifies a list of font spec records that defines the global font table. This global font table is used by all subsequent dialogs and dialog items and stays in affect until a balancing call to dd uninstall. See class font spec for more details.

Setting the grayscale parameter to true forces all DD windows to be drawn with grey backgrounds and item frames & group boxes, icon buttons and pop-up menus to adopt a 3D appearance similar to Apple's greyscale appearance for System 7.5 (AGA) guidelines. If used in conjunction with the Appearance Manager from Mac OS 8 then most other dialog items take on a similar 3D appearance.

The float above parameter makes all DD windows float above either a single application (e.g. float above application "Finder") or all applications (float above every application). It may be used with any of the window styles. If used with dialogs whose window style is standard dialog, movable dialog, plain dialog or shadowed dialog then the window will behave in a modal fashion, beeping on clicks outside the window as usual. Additionally, if a floating, non-modal, DD window contains items that may accept keyboard input then clicking in that window transfers the keyboard focus to the window. It will then retain the keyboard focus until it is either closed, it no longer contains any items that may accept keyboard input or the user clicks in another window or the menu bar.

The given script: parameter is experimental. It is used to define a parent script context that contains handlers named via push button actions (see class push button). The standard usage is given script:me. This is only required if named action handlers are used and the script is not run as an applet (where the applets script will automatically provide a default context). When given script: is used a copy of the specified script is made. This uses extra memory and any changes made to global variables and script properties are lost when the dialog terminates and are not propagated back to the original script.

Note: All the optional parameters of a dd auto dialog call are ignored if it is made between calls to dd install and dd uninstall i.e. the values used are those that were passed to the dd install call.

Warning: There is a known problem when using Script Debugger v1.0.x. If, from a script run in Script Debugger, an attempt is made to call a named script handler and no script is specified via given script: then Script Debugger may crash.

dd interact with user:

set d to dd make dialog ...
repeat
	set i to dd interact with user -- Wait for user input
	if i = 1 then -- Cancel button
		exit repeat
	else if i = 2 then -- Start button
		StartSomething()
	else if i = 3 then -- Stop button
		StopSomething()
	else
		-- Handle other items here
	end if
end repeat
dd delete d -- Remove the dialog

This event enables and handles any user interaction with the front most Live Dialog. Interaction consists of window updating of any previously obscured areas of the window and all user mouse-clicks and keyboard input. The event handler retains control until the user modifies one of the dialog items in the front dialog window. When this happen the dialog item is updated and the index of that item is returned as the result of the event. If the for max ticks parameter is specified then if no suitable user interaction takes place within the specified time span (where a tick is 1/60 second) then the event returns null. Thus it is important to call dd interact with user repeatedly and often, especially if the for max ticks parameter is used, so as to not lock out the user. This event may only be called between dd install and dd uninstall.

If the front dialog window has a close box (in the top left corner of its window frame) then dd interact with user will return -1 if this was clicked by the user. It does not close the window.

dd make:

	-- Create a push button in the back most window
dd make {class:push button, bounds:[20, 65, 80, 85], name:"One"} at dialog -1

This event allows the dynamic creation of one or more dialog items in an open dialog. Currently the new dialog items are always appended to the end of the specified dialog's dialog item list. The dialog is automatically updated to reflect any visual changes. This event may only be called between dd install and dd uninstall. (See the example scripts "More Choices.as" and "Internet Assistant.as".)

dd make dialog:

set dA to dd make dialog ...	-- dA is dialog id 1 = dialog 1

set dB to dd make dialog ...	-- dA is dialog id 1 = dialog 2
			-- dB is dialog id 2 = dialog 1

set dC to dd make dialog ...	-- dA is dialog id 1 = dialog 3
			-- dB is dialog id 2 = dialog 2
			-- dC is dialog id 3 = dialog 1

This event creates and displays a Live Dialog containing the items described in the dialog record. A reference to the newly created dialog is returned. This reference may be used in subsequent calls to dd get, dd set, dd make and dd delete. The reference is of the form 'dialog id #'. Each open dialog has both a unique and constant ID number and a unique but varying index number. The first dialog created (within a particular DD environment) is always dialog id 1, the second (if the first is still open) is dialog id 2, etc..

The front most dialog is always dialog 1 (or dialog id (dd count dialogs)), the second from the front is dialog 2, etc.. The back most dialog is always dialog id 1 (or dialog -1).

The reference returned by dd make dialog is valid until the dialog is deleted. This event handler may only be called between dd install and dd uninstall.

dd set:

dd set value of item 3 of dialog 1 to "Some Text"
dd set value of items 2 thru 6 of dialog 1 to ["A String", 1, null, myName, false]

set theListItem to a reference to item 5 of dialog id 3 -- A list box item
dd set contents of theListItem to theNewListContents
dd set value of theListItem to theNewListContents's length -- Select last item

dd set bounds of theMovingButton to [x, y, x + 60, y + 20]
dd set name of theOKButton to "Not OK"
dd set enabled of theOKButton to (true) -- Parenthesis to stop AppleScript changing it
dd set contents of theStaticText to "Not so static, Huh!"

dd set bounds of dialog 1 to theNewBounds

This event allows the setting of many different properties of dialog items in any currently open dialog. It is the converse of dd get. It sets a given property of a given dialog item (or range of dialog items) in a given dialog. It also allows the setting of a dialog window's bounds rectangle.

A dialog item's index is its position in the dialog's contents property. The dialog item indices used by dd get and dd set may be either these position integers or negative integers representing the position from the end of the contents list. Thus dialog item -1 is always the last dialog item, dialog item -2 the second last etc.

The same property of any contiguous range of dialog items in any open dialog may be set by using a single call of the form dd set <property name> of items <first index> thru <last index> of <dialog ref> to <value list>. If setting the value property of a range of dialog items, then for any dialog items that have no value property a null may be placed in the appropriate position in <value list>.

See dd make dialog above for details of dialog numbers and IDs. This event may only be called between dd install and dd uninstall.

dd uninstall:

This event cleans up and removes the DD environment created by an earlier call to dd install. The clean up process includes closing and deleting any open/active dialogs. This event may only be called after dd install. Further calls to dd uninstall result in an error being returned.