Object Classes

This section describes the many object classes contained within the Dialog Director suite. A complete list of dialog item types supported by this release can be seen in the diagram below. The classes in italics are not instantiable, and only exist for implementation and nomenclature purposes.

The Dialog Director class hierarchy

Notes and Documentation Conventions

Class dialog:

data used to create a dialog

dialog item by numeric index

size* point Size of window: [width, height]. Specifying a window size forces the dialog box to be centred on the main screen.
bounds* rectangle Bounds of window. (rect of main screen inset by 16 pixels) [R/W]
style* window frame style The kind window and style of window frame. One of:
Style Description
standard window Standard movable document window
standard dialog Standard modal dialog window (default)
movable dialog Movable modal dialog window
plain dialog Borderless modal dialog window
shadowed dialog Borderless modal dialog window with a drop shadow
standard palette Standard floating window (requires Mac OS 7.5?)
sideways palette Floating window with title bar on left (requires Mac OS 7.5?)
closeable* boolean Indicates whether the window has a close box. This only functions for dialogs whose style is standard window, standard palette or sideways palette. (false)
name* string The title of window. This is displayed in some of the styles of window frame. ("")
help* string Help string. [currently unused]
timeout after* integer Seconds after which the window closes automatically. (no timeout)
font* font spec [Obsolete]
default item* integer Index of the default (outlined) push button. (first push button item)
contents a list of dialog item The dialog items contained in this window.

dd auto dialog {size:[260, 95], timeout after:60, default item:3, contents:dItems}

The size and bounds properties are mutually exclusive. The bounds property of a dialog may now be read from and written to at runtime via dd get bounds of <dialog ref> and dd set bounds of <dialog ref> to <a rectangle>. Note that the style of the window has no bearing on its modal/modeless nature. All dialog director windows are modal within their application context, but movable windows allow the user to switch applications. Movable windows are primarily designed for use in applets and droplets. If they are used in embedded or attached scripts then the contents of the application's other windows may not be updated until all the DD windows are closed. However, if a script attempts to open a non-movable dialog in a background application the application menu's title icon will flash until that application is brought to the front or the command times out. If the optional closeable property is set to true then clicking in the window's close box will either dismiss the dialog, if it was created via dd auto dialog, or it will return -1 to dd interact with user, if the dialog was created via dd make dialog, leaving it up to the script to close the window (or not). The optional default item property specifies the index of the default push button item. Setting it to 0 means there are no default or cancel items. See class push button below and "Default Button.as" example. The contents property is a list of records that specifies the initial dialog items that appear in the window.

Class dialog item:

a dialog item

Plural form:dialog items


class class This property must be set to the class of the required item.
bounds rectangle The bounding rectangle of the item: [left, top, right, bottom]
font* integer The index of the font spec to use for this item's text. (varies with class) [W]
help* string The help text. ("") [currently unused]
enabled* boolean, integer or list True, false, or the other items on which this item depends. (true) [W]

All sub-classes of dialog item inherit the properties of this class (with the exception of dummy item which does not have bounds or font properties). The help and enabled properties have no meaning for the passive item classes static text, frame, pict, icon and gauge. You should never have to create an actual instance of the dialog item class.

Dialog items that display text will display that text using the font spec specified via the font property. The font property should be an index of the required font spec (1 - 20) in the global font spec table. The font property may be changed dynamically using dd set font of <item ref> to <integer> [Note: this has not been tested in all cases]. Control items (push button, check box, radio button, radio group & generic control) should always only use font specs whose color property is black ([0, 0, 0]), which is the default colour setting.

The depends on property (from v0.5.1) has been replaced with the enabled property. The enabled property provides the same functionality as depends on plus dialog items may be created in a disabled state. This is most useful in live dialogs. The enabled property may now be set dynamically also by using dd set enabled.

Class push button:

a push button item


class class This property must be set to push button.
bounds rectangle The bounding rectangle of this button: [left, top, right, bottom] [W]
font* integer The index of the font spec to use for the button's name. (2) [W]
help* string The help text for this button. ("") [currently unused]
enabled* boolean, integer or list True, false, or the other items on which this button depends. (true) [W]
name string The title/name of this button. [W]
action* anything Button's action when pressed. (no action)
Return value:
If no action is specified:
boolean True if this button was used to dismiss the dialog, otherwise false.
If an action specified:
anything The result of the action if the button was pressed, otherwise null.


set pb1 to {class:push button, bounds:[430, 390, 490, 410], name:"OK", help:"Dismiss"}

Currently all push button items dismiss the dialog. If no default button is specified in the dialog record (via the default item property) then the first push button item becomes the default button. During dialog execution the return and enter keys map to the default button. The first push button item that is not the default button becomes the cancel button. The escape key and <command> + '.' map to the cancel button. The action property defaults to null meaning that there is no action. For auto dialog this also indicates that the push button dismisses the dialog. An action may also be:

* a dialog record - in which case a new dialog is opened modally on top of the current one. When dismissed this sub-dialog sets the value property of the button as if dd auto dialog had been call on the sub-dialog itself.

* a handler script/function - the handler (which must have no parameters) is executed and the result becomes the value of the button. There are limitations in what may be done in an action script. However, these limitations are still the subject of experimentation. For example: it is possible to call dd auto dialog in an action script, and this does work with some simple dialogs. However, this feature is not supported. Below is a simple example of an action script.

on GetFile()
	choose file with prompt "Select a file:"
end GetFile

set pb3 to {class:push button, bounds:[100, 50, 160, 70], name:"Open...", action:GetFile}

* a string that is a handler's name - the handler which must be in the parent script context (see section dd auto dialog or dd install) is called with an optional parameter that is the index of the button and the result (if any) becomes the value of the button. The string must be in lower case (canonical form) regardless of the case of the handler's real name. The advantage of this style of action is that the handler may be parameterised; the handler has access to global variables, properties and other handlers; and it is faster and uses less memory than a handler script. Here is a complete example:

property gPresses : 0

on DoButton given item:i
	set gPresses to gPresses + 1
	display dialog "DoButton: Item " & i & " was pressed.  Presses = " & gPresses
end DoButton

on AnAction()
	display dialog "AnAction: A push button was pressed."
end AnAction

dd auto dialog {size:[80, 130], contents:[{class:push button, bounds:[10, 100, 70, 120], name:"OK"}, 
	{class:push button, bounds:[10, 10, 70, 30], name:"One", action:"dobutton"}, 
	{class:push button, bounds:[10, 40, 70, 60], name:"Two", action:"dobutton"}, 
	{class:push button, bounds:[10, 70, 70, 90], name:"Three", action:"anaction"}]} 
	given script:me	-- Use this only when running from a script editor.  Remove before saving as an applet.

Any errors that occur in an action are propagated through and returned by the dd auto dialog/dd interact with user command so try blocks should be used as necessary. An action will be executed each time its button is pressed. For any particular button only the last action's result is returned (or null if nothing was returned or the action was never executed). If an explicit return statement is not used then AppleScript returns the result of the last statement executed. Tip: To set a push button to do a one shot action make it inversely dependent upon itself, and ensure that its action does not return null. E.g. if the button's item index is 5 then set its enabled property to -5, and its action property to a dialog record or function:

on Bang()
	return 1
end Bang

{class:push button, bounds:[0, 0, 60, 20], name:"One Shot", action:Bang, enabled:-5}

The script may also be written:

on Bang()
	dd set enabled of item 5 of dialog 1 to (false)
end Bang

{class:push button, bounds:[0, 0, 60, 20], name:"One Shot", action:Bang}

Note: The value property of a push button may be set only indirectly via an action handler's return statement.

Class check box:

a check box item
class class This property must be set to check box.
bounds rectangle [W]
font* integer The index of the font spec to use for the button's name. (2) [W]
help* string
enabled* boolean, integer or list [W]
name string [W]
value* boolean If true then the check box is checked. (false) [R/W]
Return value:
boolean True if this check box is checked, otherwise false.

A check box dialog item is a button that toggles on and off on alternate mouse clicks.

Class radio button:

a single radio button item
class class This property must be set to radio button.
bounds rectangle [W]
font* integer The index of the font spec to use for the button's name. (2) [W]
help* string
enabled* boolean, integer or list [W]
name string [W]
value* boolean If true then this radio button is selected/on. (false) [R/W]
Return value:
boolean True if this radio button is selected/on, otherwise false.

A radio button dialog item is a button that switches on when clicked, and off when another member of its group is clicked. A contiguous set of adjacent radio button dialog items form a group. Radio button groups are delimited by any other type of dialog item. Clicking one member of a group sets its value to true (and highlights it), and the value of the previously on member of the group to false (and unhighlights it).

The main use of radio buttons is for when either a non-regular layout is required or when members of the group require different dependencies. Otherwise a radio group dialog item is probably more suitable.

Note: Setting the value of a radio button does not affect the values of any other members of the group. Thus it is necessary to set the value of one radio button to false and one to true to maintain a consistent appearance

Class radio group:

a group of radio buttons
class class This property must be set to radio group.
bounds rectangle The bounding rectangle of the first radio button.
font* integer The index of the font spec to use for each button's name. (2) [W]
help* string
enabled* boolean, integer or list [W]
value* integer The index of the selected button. (1) [W]
button offset point The relative offset of each button: [dx, dy]. If no max down property is specified then the bounding rectangle of each button is offset by (dx, dy) from the previous button's bounds. if a max down property is specified then the bounding rectangle of each button is offset by (0, dy) from the previous button's bounds for the first maxDown buttons then the next button is offset by (dx, 0) from the first button's bounding rectangle. This creates vertical columns of buttons.
max down* integer maximum number of buttons in vertical direction before wrapping to the next column. (no wrapping)
contents list of strings The button name list.
Return value:
    integer Index of the currently selected button.
set theItems to ["One", "Two", "Three", "Four", 5, 6, 7, 8, 9, 10, 11, 12]
	-- Create 2.4 columns of 5 items each
set rg1 to {class:radio group, bounds:[20, 40, 120, 56], button offset:[105, 20], max down:5, contents:theItems}
	-- Create 1 diagonal column of 12 items
set rg2 to {class:radio group, bounds:[20, 140, 120, 156], button offset:[10, 20], contents:theItems}

A radio group is a single dialog item that provides set of interlinked radio buttons arranged in either a straight line or a regularly spaced grid. Every button in the group is the same size and adjacent buttons have the same spacing. In a straight line layout the line of buttons may go in any direction, dependent on the setting of the button offset property. In a grid layout buttons are arranged in vertical columns. The number of buttons in each column is controlled by the max down property. The final column need not be full.

As a radio group is a single dialog item it returns a single value which is an integer representing the index of the selected button. Also, dynamically setting the value property of a radio group switches off the currently selected radio button and switches on the one specified.

Class pop up:

a pop-up menu item
class class This property must be set to pop up.
bounds rectangle
font* integer The index of the font spec to use for the menu's current value. (4) [W]
enabled* boolean, integer or list [W]
name string Label/title of pop-up item.
name width* integer Amount of space (in pixels) to reserve on the left of the bounding rectangle for its name. (width of name + 8)
value* integer or string Default selection. (1) [W]
text field* integer The index of a type-in text field. (no type-in)
contents list of strings The menu item list. [W] This consists of either a single string or a list of strings. If the single string form is used with a string of exactly 4 characters then the AppendResMenu toolbox function is called to create a menu of the names of the resources of that type. Common uses are "FONT" (to create a menu of all fonts) and "DRVR" (to create a menu of the items in the "Apple Menu Items" folder). If the string is not 4 characters long then it may be longer than the 255 character limit imposed on all other strings. Each string may define one or more menu items. You may embed metacharacters in the string(s) to define various characteristics of a menu item.
Here are the metacharacters that you may specify in the data parameter:
Metacharacter Description
; or return Separates menu items.
^ When followed by an icon number, defines the icon for the item. If the keyboard equivalent field contains (ASCII character 28), this number is interpreted as a script code. [NOT functional]
! When followed by a character, defines the mark for the item.
< When followed by one or more of the characters B, I, U, O, and S, defines the character style of the item to Bold, Italic, Underline, Outline, or Shadow, respectively.
/ When followed by a character, defines the keyboard equivalent for the item. To specify that the menu item has a script code, small icon, or reduced icon, use the SetItemCmd procedure to set the keyboard equivalent field to (ASCII character 28), (ASCII character 29), or (ASCII character 30), respectively. [NOT functional]
( Defines the menu item as disabled. Use "(-" for a grey dividing line.
Return value:
If contents is not a 4 character string:
integer Index of the currently selected menu item.
If contents is a 4 character (resource type) string:
string Text of the currently selected menu item.


	-- For mu1 items through 12 of theItems are automatically coerced to strings
set theItems to ["One", "Two", "Three", "Four", 5, 6, 7, 8, 9, 10, 11, 12]
set mu1 to {class:pop up, name:"Nums:", bounds:[300, 250, 480, 270, value:10, contents:theItems}
	-- In mu2 item 5 is a grey dividing line and items 7, 8 & 9 are in the named styles
set mu2 to {class:pop up, name:"Test:", bounds:[10, 40, 130, 59], name width:30, contents:

	-- This complete example presents a dialog with a type-in style pop-up
set dTypeInPopUp to {size:[120, 80], contents:[
	{class:push button, bounds:[50, 50, 110, 70], name:"OK"}, 
	{class:pop up, bounds:[95, 10, 130, 29], contents:"9;10;12;14;18;24;36;48", text field:3}, 
	{class:text field, bounds:[50, 12, 90, 28], name:"Size:", name bounds:[10, 12, 50, 28], value:9}]}
dd auto dialog dTypeInPopUp with grayscale

Currently each pop-up menu requires a dummy menu resource (type 'MENU'). There are 16 menu resources included in the "Dialog Director" scripting addition file numbered sequentially from 32720. This limits the maximum number of menus in all open DD windows to 16 per application. If you need more than 16 menus at a time you can add extra menu resources to either your script document (preferred) or the "Dialog Director" scripting addition file using ResEdit. These extra menus should have IDs numbered sequentially from 32736.

The Pop up dialog item provides a pop-up menu style control. DD v0.6 completely reimplements pop-up controls and introduces new style pop-ups when the grayscale dialog option is set to true. DD v0.7 further enhances the appearance of greyscale pop ups and add the ability to set dynamically set their contents.

If a resource-names style menu is created (such as with contents:"FONT") then the value may be initialised to a string e.g. value:"Helvetica". In this case calls of the form dd get value of refToThisPopUp return a string (the name of the current menu selection) and calls of the form dd set value of refToThisPopUp to newValue require a string (the name of a menu item) for the to (newValue) parameter.

Class list box:

a scrolling, text list


class class This property must be set to list box.
bounds rectangle
font* integer The index of the font spec to use for the list's contents. (4) [W]
enabled* boolean, integer or list [W]
value* integer or list The selected item or items. (0 Æ no selection) [R/W]
flags* integer Selection flags for this list. (130)This property controls the selection algorithm. The constants below may be added together to define the required behaviour for a particular list.
Constant Description
2 disable highlighting of empty cells
4 allow use of shift key to deselect items
8 shift-drag selects items passed by cursor
16 reset list before responding to shift-click
32 prevent discontiguous selections
64 enable multiple item selection without shift key
128 allow only one item to be selected at once
The values of the flags property for standard list behaviours are 130 for single item selection, and 0 for arbitrary multiple item selection.
contents list of strings The list items. Each string represents a single list item. Items that can to coerced to strings are also valid e.g. numbers and data types. [W]
action* integer The value returned when a list item is double clicked. (0 Æ no double click)
column widths* list of integers The widths of the text alignment columns. (single column of list's width)
Return value:
If only single selections are allowed:
integer Index of the currently selected item or 0 if no selection.
If multiple selections are allowed:
list of integers List of indices of the currently selected items or 0 if no selection.

List boxes may be controlled via the keyboard using the following keys (i.e. they may accept the keyboard focus): home select first item end select last item up arrow move selection to previous item down arrow move selection to next item page up move selection up by list box height page down move selection down by list box height tab move keyboard focus to next focusable item shift-tab move keyboard focus to previous focusable item backspace delete last character in internal buffer (see other) clear clear internal buffer (see other) other characters typed within 1 second intervals are appended to an internal buffer which is used to select the first matching item. This is not case sensitive and does not require the list to be in alphabetical order.


	-- List the items in the System folder and force the user to select one.
set lbItems to list folder (path to system folder)
set sysFolderDlog to {size:[220, 220], contents:[
	{class:list box, bounds:[10, 10, 210, 172], contents:lbItems, action:2}, 
	{class:push button, bounds:[150, 190, 210, 210], name:"OK", enabled:1}]}
dd auto dialog sysFolderDlog

Setting the action property to a integer other than 0 indicates that when a list item is double-clicked then dd interact with user should return that value. Also dd auto dialog will dismiss the dialog, and if action is the index of a push button item then its value in the returned list will be true. A typical use of this property is to set it to 1 (or whatever is the index of the default button). Setting the property to 0 (the default) indicates that double-clicks should be treated the same as single clicks.

The column widths property allows the creation of a list box that uses tab characters in the list's contents' item strings to break the list into up to 10 vertical columns of varying width. This can be used to align check marks before an item's text or columnise date, name, amount items for instance.

The height of a list box should be a multiple of the row height + 2 (for the frame). For the standard Chicago font the row height is 16. Therefore height of list box = (rows displayed) * 16 + 2. A list box may be dependent on other items. The text of a disabled list box is draw in grey and the scrollbar is hidden.

Note: The value property may now be initialised to a list of cell indices to highlight.
Note: Setting the value property scrolls the list to the nearest highlighted item.