Object Classes

Notes and Documentation Conventions

• All properties marked with an asterisk* are optional.
• The default value of a property is shown in parenthesis following the description.
• All of the help properties are currently ignored.
• All text/string properties are currently limited to a maximum of 255 bytes (characters?) in length.
• The 'label' property was previously called 'name' but I cannot decide whether it should be called 'name', 'label' or 'title'.
• Properties marked with [W] are writeable while a dialog is open (via dd set).
• Properties marked with [R/W] are readable and writeable while a dialog is open (via dd get and dd set).
• Rectangles are always specified [left, top, right, bottom] relative to the dialog window's origin (which is in its top-left corner). Right must be greater than or equal to left. Bottom must be greater than or equal to top. All four values must be integers.

Class dialog:

Elements:
dialog item by numeric index

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:

Plural form:dialog items

Properties:

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:

Properties:

Example:

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 dialog item is a button that toggles on and off on alternate mouse clicks.

Class radio button:

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:

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:

Examples:

	-- 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:
	"1;2;3;4;(-;6;<BBold;<IItalic;<UUnderline;10"}

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

Properties:

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.