Elements:
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:
|
|||||||||||||||||
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.
Plural form:dialog items
Properties:
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.
Properties:
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. |
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 | 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 | 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 | 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 | 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.
|
||||||||||||||||
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: "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 | 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.
| |||||||||||||||||||
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.