Class poly push button:

Example:

	-- A triangular push button
{class:poly push button, bounds:[195, 30, 340, 150], contents:[0, 0, 145, 60, 60, 120, 0, 0]}

A poly push button is a transparent polygonal area that behaves like a push button. It may be used to effect arbitrary shaped, push button like, dialog items in combination with parts of or whole pict, icon and static text dialog items. In order to activate the button the user must click the mouse within the button's polygon as defined by its contents property, or within the rectangle defined by its bounds property if no contents property is specified.

The contents property defines the coordinates of the vertices of the polygon. It consists of a list of pairs of integers that specify the x and y coordinates of each vertex. The first pair must be duplicated exactly by the last pair i.e. [x1, y1, x2, y2, ..., xn, yn, x1, y1]. Thus a list of 8 integers (4 vertices) defines a triangle. The coordinates of each vertex are specified relative to the top-left corner of the bounds rectangle. This means the button can be relocated by simply using a different bounds setting.

Class poly toggle button:

Example:

	-- A triangular toggle button
{class:poly toggle button, bounds:[195, 30, 340, 150], contents:[0, 0, 145, 60, 60, 120, 0, 0]}

A poly toggle button is a transparent polygonal area, similar to a poly push button, that behaves like a check box (or toggling button). Alternate clicks toggle it between on & off states. In its off state the button is transparent (invisible). In its on state all pixels within its polygon have their colour inverted. See class poly push button for more details.

Class poly sticky button:

Example:

	-- A triangular sticky button
{class:poly sticky button, bounds:[195, 30, 340, 150], contents:[0, 0, 145, 60, 60, 120, 0, 0]}

A poly sticky button is a transparent polygonal area, similar to a poly push button, that behaves like a single radio button dialog item. Clicking the button places it in the on state (value = true) where it will remain unless reset by a script. In its off state (value = false) the button is transparent (invisible). In its on state all pixels within its polygon have their colour inverted. See class poly push button for more details.

Class poly radio button:

Example:

	-- A triangular radio button
{class:poly radio button, bounds:[195, 30, 340, 150], contents:[0, 0, 145, 60, 60, 120, 0, 0]}

A poly radio button is a transparent polygonal area, similar to a poly push button, that behaves like a radio button dialog item. Clicking the button switches the previously on member of the group off (value = false) and places this button in the on state (value = true).

In its off state the button is transparent (invisible). In its on state all pixels within its polygon have their colour inverted. A contiguous set of adjacent poly radio button dialog items form a group. Poly radio button groups are delimited by any other type of dialog item. See class poly push button for more details.

Class movie controller:

A movie controller dialog item enables the display of any standard QuickTime movie within a dialog. The flags property allows the specification of a number of display options.

The optional flags property is constructed by adding any combination of the following values together (or setting it to 0 if none are required):

Class font spec:

Example:

	-- This is the default system font spec:
set font1 to {name:"", size:0, style:plain, color:[0, 0, 0]}
	-- It is equivalent to this font spec on Roman script systems:
set font2 to {name:"Chicago", size:12, style:plain, color:[0, 0, 0]}
	-- This font spec produces this style of text
set font3 to {name:"Geneva", size:9, style:[bold, underline]}

A font spec can be used to override the default settings for the context (and all sub-contexts) within which it is specified. That is the global default font (the font parameter of dd auto dialog) overrides the system font spec for all DD dialogs, the dialog default font (the font property of a dialog) overrides the global font spec for all text in that dialog, and the font property of a static text overrides the dialog default font for that static text item. Where a partial font spec is used the missing parts are automatically filled in from the next larger context.

Note: Currently the color property is not used by control items which always display text in black.

Note: A later release of DD may include a justification property in font spec objects.

The Global Font Spec Table

This section describes the global font spec table (font table) that is specified via the with fonts parameter of dd install and dd auto dialog. This is the preferred way of specifying fonts in DD v0.7. The font table provides a hierarchical font specification system that is both flexible and consistent (if initially not completely obvious).

The flexibility comes from the ability of any dialog item to use any font spec (in the font table) by simply setting its font property to the required entry's index. The font table is specified as a list of font specs and null objects. A null indicates that that font spec should inherit all its properties. The font table may contain up to 20 such entries (numbered 1 to 20). All font specs are initially defined to have the same default property settings as the system font (as described in the Class font spec section above).

Further, if the first font spec is redefined then font specs 2 - 20 all default to it initially. Thus, as different classes of dialog item default to using different font specs from the font table, they all initially default to using the system font, unless you define font spec 1 to not be null, unless you define their default font spec to not be null, unless you give them an explicit font spec via their font property.

The tree diagram below shows the font spec inheritance hierarchy in a graphical form. Font spec properties that are not redefined are inherited. Any font spec property definitions further down the hierarchy (to the right) override those defined further up the hierarchy (to the left). The rightmost items are the dialog item classes that inherit the font specs to their left by default, and the properties that are drawn using those font specs.

Example 1:

	dd install with fonts [null, {name:"Helvetica", style:bold}, null, null, {name:"Geneva", size:9}]

This will cause the names of all control items to appear in 12pt Helvetica-Bold and all other text to appear in the System font, unless their dialog item definitions explicitly specify the font property to be 2 (12pt Helvetica-Bold) or 5 (9pt Geneva).

Example 2:

	dd install with fonts [{name:"Times"}]

This will cause all text within the subsequently created DD windows to appear in 12pt Times-Roman, regardless of any font spec indexes specified in any dialog item definitions, i.e. it redefines the global font.

The Global Font Spec Hierarchy

Dependencies

This section explains how dependencies (i.e. the enabled property) works. It does not need to be understood completely if you only need to create simple dialog boxes.

Item dependencies allow interactive dialog items to be dynamically enabled or disabled automatically dependent on the state of one or more other items. e.g. The OK push button could be disabled (greyed out) until some text is entered into a text field (as in the password dialog example below). The dependencies of all items are re-evaluated whenever the state of any item changes.

There are four types of dependency: none, initial, single item and multiple items. By default a dialog item has no dependencies i.e. it has no enabled property and it is always active. An expression that evaluates to true or false may be used to set the initial value of an enabled property.

This expression is evaluated only once when the dialog item list is constructed e.g. enabled:(current date) >= date "1/1/2000". A single item (simple) dependency consists of the enabled property being a single integer which gives the index of the dialog item upon which this item depends. (An item's index is determined by the position of the item in the contents property of the dialog record passed to dd auto dialog or dd make dialog.)

Negative values indicate inverse dependencies. i.e. if item 4 is a check box then an item with property enabled:4 would be enabled only when the check box is checked, and an item with property enabled:-4 would be enabled only when the check box is not checked (unchecked).

Values with a magnitude greater than 255 are used to indicate a dependency on a sub-item (such as a radio button or pop up menu item). e.g. a value n = 522 is interpreted as dialog item no. = |n| mod 256 = 10, sub-item no. = |n| div 256 = 2. The following function will calculate the numbers for you:

on SubItem(itemNo, subItem)
	return itemNo + subItem * 256
end SubItem

A multiple item (complex) dependency consists of the enabled property being a list composed of an enumeration name (dOr or dAnd) followed by one or more integers as described for the simple dependency e.g. enabled:[dAnd, 3, -5] enables this item only when dialog item 3 is on and dialog item 5 is off.

Error Codes

Dialog Director may return a number of error codes that are not part of the standard Mac OS/AppleScript repertoire. These error codes are defined in this section.

Dialog Dumper

Dialog Dumper is an applet which is a part of the Dialog Director distribution. Dialog Dumper allows you to automatically convert standard Mac OS application dialog boxes into AppleScripts that can be used in conjunction with Dialog Director to create interactive dialogs.

The advantage of this is that these dialog boxes can be created and edited using Apple's ResEdit application. ResEdit provides a user interface for the interactive editing of dialog layouts via direct manipulation.

This section provides a very brief description of the current features and functions of Dialog Dumper. Many thanks to Christopher R. Green for his help in the development and testing of Dialog Dumper.

What You Get

Dialog Dumper is written entirely in AppleScript and, naturally, uses Dialog Director to provide its user interface. Along, with the applet, the full source code of the script used in the applet is included in the text file "Dialog Dumper.as" and the resources used by Dialog Dumper to initially create its own user interface are in the file "Dialog Dumper.rsrc".

You are free to customise it to your own particular needs. To create the applet the script was saved from the Script Editor as a 'Run Only' application, with 'Stay Open' and 'Never Show Startup Screen' options checked, and the minimum and preferred memory requirements set to 600K. A couple of example dialog resource files are also included.

What You Need to Run

What It Does

Dialog Dumper reads each 'DLOG' resource in turn from a resource file and processes its contents and the contents of an associated 'DITL' resource. It also extracts information from 'CNTL' and 'MENU' resources referenced by dialog items in a 'DITL' resource. It is possible to use Dialog Dumper to convert dialogs taken directly from applications, desk accessories, etc. However, they should be copied into a new resource file before use.

• choice of Auto Dialog or Live Dialog code generation
• optional greyscale dialog look
• optional timeout for Auto Dialogs
• optionally change the default text font
• optionally change the default text size
• optionally change the default text style.

• the name of the resource (prefixed with "d") for the name of the variable containing the dialog record
• or the resource ID prefixed with "dlog" if there is no name;
• the DLOG's boundsRect for the dialog bounds;
• or the boundsRect's width & height for the dialog size if the top-left is (0, 0) or its auto position is set to centre on main screen;
• the DLOG's title for the dialog's name;
• the DLOG's procID for the dialog's style;
• the DLOG's close box option for the dialog's closeable property;
• and the DLOG's DITL ID to retrieve the 'DITL' resource for the dialog's contents.

• push button
• check box
• radio group - by grouping together adjacent radio buttons
• static text
• text field
• icon
• picture
• group box - from user items and control:
• title Æ name
• procID = 160 Æ primary group
• procID = 164 Æ secondary group
• pop up - from control:
• title Æ name
• value != 0 Æ value
• title != "" and max != 0 Æ name width: max
• procID = 400 or 1008 Æ standard pop-up, min Æ menu resource ID used for contents:[...]
• procID = 400 or 1008 and title = "" and refCon != 0 Æ text field: refCon
• procID = 404 or 1012 Æ resource list pop-up, refCon Æ resource type
• list box - from control:
• procID = 352
• value != 0 Æ value
• gauge - from control:
• value != 0 Æ value
• max - min Æ max value.

How to Use It

To use Dialog Dumper simply drop the resource file containing the dialog(s) on the Dialog Dumper application icon (or launch Dialog Dumper and select an appropriate file). You will be presented with the following dialog (or something similar):

See elsewhere in this User Guide for details of the meanings of the settings. Make your settings and then click To Clipboard to write the script to the clipboard, or To File... to write the script to a file of your choosing. If the script is written to a file then any existing file will be completely overwritten. Any settings you make are preserved and re-presented the next time a file is to be processed. Dialog Dumper stays open after processing a file so it does not need to be re-launched each time it is needed. If the Live Mode option is selected then the script generated contains a loop that repeats until a push button in the dialog or the window's close box is clicked.

Introductory Examples

1. Very simple dialog

set dlog to {size:[320, 95], 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."}] 
		}

set dVals to dd auto dialog dlog

This creates a small dialog window in the centre of the main screen containing some static text above OK and Cancel push buttons.

The OK push button is item 1, the Cancel push button is item 2, and the static text is item 3 because that is the order they are defined in dlog's contents list. Clicking the OK button yields the result:

2. Simple password dialog

property dPassword : {size:[260, 95], contents:[
	{class:push button, bounds:[190, 65, 250, 85], name:"OK", enabled:3}, 
	{class:push button, bounds:[110, 65, 170, 85], name:"Cancel"}, 
	{class:password field, bounds:[10, 36, 250, 36 + 16], name bounds:
		[10, 10, 250, 26], name:"Enter Password:", value:""}] 
	, timeout after:60}

set [ok, cancel, thePassword] to dd auto dialog dPassword

if ok then
	display dialog thePassword -- OK was pressed
else if cancel then
	beep -- Cancel was pressed
else
	display dialog "The dialog timeout was reached." -- Timeout
end if

This creates a small dialog window in the centre of the main screen containing a password field below a prompt and below that are two push buttons. The OK button has a default border and is greyed out/disabled until some text is entered into the password field.

If no push button is pressed within 60 seconds the dialog is automatically dismissed as specified by the timeout after:60 property. Note that this example has the dialog record (dPassword) defined as a property as opposed to the variable used in example 1.

This helps speed up execution but only where the dialog record is constant. The dialog window should initially look like this:

{true, false, null, {416, 397, 736, 492}}	-- [ OK button, Cancel button, static text, dialog window's bounds ]

Clicking the Cancel button yields the result:

{false, true, null, {416, 397, 736, 492}}

As you can see, dd auto dialog returns a list of four items, one for each dialog item passed to it via the contents property and one that represents the final bounding rectangle of the dialog window. In this example the third item will always be null because static text items have no value property.

The values of items 1 and 2 allow you to determine which push button was used to dismiss the dialog. The dismissing push button always returns true (whether invoked via the mouse or keyboard), and all other push button's return false. This allows you to write the following sort of code:

set dVals to dd auto dialog dlog

if item 1 of dVals then
	-- OK was pressed
else if item 2 of dVals then
	-- Cancel was pressed
end if

Alternatively you can write the code like this:

set [ok, cancel] to dd auto dialog dlog

if ok then
	-- OK was pressed
else if cancel then
	-- Cancel was pressed
end if

Note that in this example the OK button (being the first push button) defaults to the default button and the second push button defaults to the cancel/escape button. These could be reversed by including default item:2 in the dialog record passed to dd auto dialog.

After typing some text and selecting it the dialog window might appear as below. Note that any character typed will appear as a bullet, and that the OK button is now enabled.

Changing the above script to set the grayscale parameter to true and the initial value of the password field item to "Test":

	...
	{class:password field, bounds:[10, 36, 250, 36 + 16], name bounds:
		[10, 10, 250, 26], name:"Enter Password:", value:"Test"}] 
	...

get dd auto dialog dPassword with grayscale

should produce a dialog window that initially looks like this (if the Appearance Manager is installed):

Contents of 'Examples' Folder

All the example scripts expect that Dialog Director v0.7 and all the standard scripting additions are correctly installed in the "Scripting Additions" folder. Additionally all examples are working and designed to be run from within Script Editor unless otherwise stated.

Known Problems and Limitations

• There is a maximum limit of 255 dialog items per dialog window.
• A maximum of 7 dialogs may be open at a time (per DD environment).
• Strings used by DD are limited to 255 bytes (characters) except for the text field, password field and static text classes which may contain up to 32,000 bytes of text.
• Many dialog item properties (too many to list) are not available via dd get and dd set. More will be made available in future versions.
• When in use DD consumes at least 70K of memory from the application heap in whose layer the dialog(s) appear. This grows with the complexity and number of dialogs. All this memory should be returned to the application upon DD termination.
• Some applications do not take kindly to other applications opening windows in their application layer and then asking them to handle incoming events. They tend to crash. These applications don't like DD's live dialogs (although DD v0.7 should be compatible with more applications than DD v0.6). It should be possible to overcome this limitation by using auto or floating dialogs instead.
• If a live dialog window is left open after the script returns control to the calling application (such as if the script generates an error) then the host application may crash. This only effects some applications and is completely avoidable by writing the script thusly:

dd install -- plus any options try <code to manage my Dialog Director windows> dd uninstall on error dd uninstall end try

• If dd interact with user... is not called frequently enough while a live dialog is active, mouse clicks and key presses may be lost.
• If an application uses DD to create floating windows and then quits without calling dd uninstall then computer may crash.
• Due to the manner in which DD v0.6 handles backward compatibility with DD v0.5.1 properties that have been replaced required properties that are missing produce an error specifying the old property ID rather than the new property name.

Other Scripting Additions

• Resource Utilities Read, write, get & set info for any resources and read write any AppleScript data structures as resources.

• Picture Utilities Read, write, print, join, resize and get info about Quickdraw pictures.
• Display Picture Display a Quickdraw picture in a modal, scrollable window with magnification.
• Make Picture Create a picture from within AppleScript. Supports rectangles, ovals, lines, text, polygons, regions, patterns, pens, colours etc.
• String Width Calculate the width, in pixels, of a text string of given font, size and style.
• Set Info For Set info for a file or folder (counterpart of info for command).
• Font Info Get ascent, descent, leading and height of a given font, size & style.
• Print Utilities Create print jobs and print multiple pages containing text & pictures.