Dialog Director - Anleitung

Version 0.7, February 1998
Copyright © 1996-1998 Christopher E. Hyde. All rights reserved.
drjekyll@hylight.demon.co.uk
http://www.hylight.demon.co.uk/

Contents
Welcome
Licence
How You Can Help
About the Author
Release Notes
Installing Dialog Director
Auto Dialogs and Live Dialogs
Event Handlers
dd auto dialog	- create, display and interact with a dialog window
dd calc dialog bounds	- calculate the bounding rectangle of a dialog window
dd count dialogs	- return the number of open dialogs
dd delete	- delete dialog items or close and delete a dialog window
dd get	- retrieve properties from objects
dd install	- create and initialise the Dialog Director environment
dd interact with user	- interact with the front dialog window
dd make	- create one or more dialog items in an open dialog
dd make dialog	- create and display a dialog window
dd set	- set properties of objects
dd uninstall	- clean up and remove the Dialog Director environment
Object Classes
dialog	- data used to create a dialog
dialog item	- a dialog item
push button	- a push button item
check box	- a check box item
radio button	- a single radio button item
radio group	- a group of radio buttons
pop up	- a pop-up menu item
list box	- a scrolling, text list
icon list box	- a scrolling, labeled, icon list
text field	- an optionally labelled editable text item
password field	- an opaque editable text item
static text	- a static text item
group box	- an optionally labelled rectangular frame item
pict	- a static picture item
icon	- a static icon item
dummy	- a dummy dialog item
color picker	- a colour picking item
gauge	- a graphical magnitude/progress indicator
icon push button	- a push button with an icon & a beveled edge
icon toggle button	- a toggle button with an icon & a beveled edge
icon sticky button	- a sticky button with an icon & a beveled edge
icon radio button	- a radio button with an icon & a beveled edge
poly push button	- a clickable polygon area
poly toggle button	- a toggling polygon area
poly sticky button	- a sticky polygon area
poly radio button	- a radio button polygon area
movie controller	- a QuickTime movie controller
font spec	- a text font specification
The Global Font Spec Table
Dependencies
Error Codes
Dialog Dumper
Introductory Examples
Contents of 'Examples' Folder
Known Problems and Limitations
Other Scripting Additions

Welcome

Welcome to Dialog Director v0.7. This is the February 1998 public release of the Dialog Director scripting addition. Dialog Director allows you to create dynamic dialog windows directly from your AppleScript scripts. This provides you with the ability to write applets, droplets and embedded scripts with the power to interact with your users in a friendly and effective manner. Please use Dialog Director and tell me what you think. I intend to enhance and maintain it based on the feedback I receive from you. If you also send me examples of your own scripts then it helps me to understand what you want Dialog Director to do and may give me ideas for future features. The reason that this release is called v0.7 and not v1.0 is because I am still adding features and the API may change (and has already) as a result of your feedback. However, throughout testing it has proved extremely robust and reliable.

Current features include
Dialog item types
Push buttons - with user defined default button, return & escape key mapping, actions Check boxes Radio button groups - - one & two dimensional automatic layout Pop-up menus Scrolling text lists - single column, single & multiple selection, keyboard navigable, disableable Static text items - any font, size, style & colour Edit text items - optional label, forward & backward tabbing, cut, copy & paste, extended keyboard support Password text items - as edit text items but display only bullets Rectangular frames - optional label, 3 styles (and horizontal & vertical lines) Pictures Icons - colour or black & white Editable pop-ups Colour pickers Gauges (progress bars & barber poles) Icon list boxes Icon buttons (push, toggle, sticky & radio) Polygon buttons (push, toggle, sticky & radio) QuickTime movie controller
Other
Dependencies - automatically enable and disable items depending on other items' states Optional dialog time-out Extensive error checking and reporting Returns an easy to read list of item values No need for resource files or use of ResEdit Six different window styles including movable modal Floating windows - windows that float above all applications [experimental] Support for Apple Greyscale(ish) Appearance (AGA) Embedded sub-dialogs Separate make, interact and delete dialog events Get and set values & other properties of dialog items while the dialog is open Multiple, independent dialogs Get and set multiple item values & other properties via a single call Dynamically create and delete multiple dialog items in an active dialog Font spec table - supports any font spec for any item Make a dialog window float above a specific application
Future features
Tristate buttons - on, off, neither Sliders Number text fields Balloon help Keyboard to item mapping Styled text edit And too many other items to list here :-) What would you like Dialog Director to do for you?

Please note that this software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose. Dialog Director is FREE. You may redistribute Dialog Director to anyone as long as you include the complete, unaltered, Dialog Director package and do not charge for it. The "complete package" is defined as meaning the entire and exact contents of the file <http://www.hylight.demon.co.uk/DialogDirector/DialogDirector0.7.sit.hqx>. It includes all scripting additions, all documentation and all examples & utilities, in either compressed or fully uncompressed form. You may, of course, charge for your own software that uses Dialog Director (if you so desire), just not extra for Dialog Director. It also means that you may not sell copies or redistribute parts of the Dialog Director package without obtaining a separate and specific licence from the author. Although not a formal part of the licence I strongly suggest that if you use any URLs to Dialog Director at my website then you should use <http://www.hylight.demon.co.uk/DialogDirector/>. Also I would sincerely appreciate being sent a complementary copy of any compilation CD that includes Dialog Director.

How You Can Help

I want Dialog Director to be compatible with as many different machines, Mac OS versions, and languages as possible. I would be happy to see it become a standard part of everyone's AppleScript setup. Together with your help I can make Dialog Director even better. Send your comments, ideas, questions, problems and example scripts to me at the above address. I hope to include the best of these in future releases of Dialog Director along with more extensive documentation and an FAQ (Frequently Asked Questions document).

About the Author

Hello, my name is Christopher E. Hyde. I am the creator of Dialog Director. I have over 10 years of commercial Macintosh software development experience and have been programing professionally for more than 17 years. I spend most of my time doing bespoke (custom) Macintosh software development using C++ and MacApp, PowerPlant, etc. I have designed and developed shrink wrapped applications as well as vertical market applications. I specialise in RAD, Human Computer Interaction (User Interface design and User Requirements), code optimisation, debugging existing code bases and making the impossible actually happen. [However, I don't do dishes, and I don't do windoze ;-).] So, if you are looking for someone to develop your next killer application ... I'm your man! Just for your information: Dialog Director contains approximately 15,000 lines of code written in C++ (with a little assembly language). It is designed and written to a professional quality employing best practise in OOP, defensive programming and macro & micro-optimisation techniques.

Release Notes

This section briefly lists the changes between the different releases of Dialog Director.

Dialog Director v0.7 (Feb '98)

Fixed update problem with dd set in text field & password field items.
Fixed dd set value of <radio group> to match dd get value.
Fixed a few memory leaks and problems under error conditions.
Renamed document window window style to standard window.
Renamed modal window style to standard dialog.
Renamed movable modal window style to movable dialog.
Renamed palette window style to standard palette.
Replaced default property of class dialog with default item.
Replaced the font parameter of dd auto dialog & dd install with with fonts. This defines a list of font specs.
Replaced the floating parameter of dd auto dialog & dd install with float above. This allows the specifying of a single application (e.g. application "Finder") or all applications (every application).
Improved look for greyscale pop up items.
Improved look for indeterminate mode gauge items (barber pole).
Improved look for labeled group box items.
Added support for up to 32K bytes of text in text field, password field and static text items.
Added new icon button dialog items (icon push button, icon toggle button, icon sticky button, icon radio button).
Added new polygon button dialog items (poly push button, poly toggle button, poly sticky button, poly radio button).
Added new generic control dialog item.
Added new movie controller dialog item.
Added new icon list box dialog item.
Added new radio button dialog item.
Improved code optimisation - its faster.
Improved memory utilisation - lower minimum memory requirements.
Changed dd delete event. Delete one or more dialog items from a live dialog window.
Changed dd get event. Get a list of values of a property from a range of dialog items.
Changed dd set event. Set the value of a property of a range of dialog items from a list.
Changed value property. It is now compatible with script debugger.
Changed behaviour of default item property. 0 Æ no default or cancel button, -1 Æ first push button.
Added set/get bounds property of dialog window.
Added set selection property of text & password fields.
Added set font property for all dialog items.
Added set max value property of gauge items.
Added set contents property of pop up items.
Added new dd make dialog items event. Dynamically add one or more dialog items to a dialog window.
Added new closeable property to class dialog.
Added new float above option to dd install and dd auto dialog events.
Added new action property to class list box. Return this value if list is double-clicked.
Added new column widths property to class list box. Aligns text containing multiple tabs.
Added support to text field for <command> + 'A' selecting all.
Added support for named action handlers via applet's script or given script:<script>.
Changed setting of value property of a list box to scroll first selected item into view.
Added reporting of problem dialog item index in dd auto dialog, dd make and dd make dialog.
Changed DD's window kind. This should make it compatible with more applications.
Added back default button outline in floating windows including Appearance Manager support.

Dialog Director v0.6 (Apr '97)

Fixed grey background problem in text field & password field items.
Fixed typing return in text fields.
Improved redraw speed by pruning unnecessary object redrawing.
Added <command> + '.' to cancel button mapping.
Removed colour synonym for color (due to reports of strange behaviour in QuarkExpress).
Renamed do dialog event to dd auto dialog.
Renamed calc window bounds event to dd calc dialog bounds.
Added new dd install event. Create and initialise the Dialog Director environment.
Added new dd make dialog event. Create and display a dialog window.
Added new dd interact with user event. Interact with the front dialog window.
Added new dd get event. Get a property from a dialog item.
Added new dd set event. Set a property of a dialog item.
Added new dd delete event. Close and delete a dialog window.
Added new dd uninstall event. Clean up and remove Dialog Director environment.
Added new dd count dialogs event. Return the number of open dialogs.
Changed the items property of dialog to contents.
Changed label property of push button to name.
Changed label property of check box to name.
Changed the items property of radio group to contents.
Changed label property of pop up to name.
Completely rewrote pop up class. No longer uses System pop-up control.
Added support to pop up for optional type-in text field.
Added support to pop up for Apple Greyscale(ish) Appearance (AGA).
Changed label width property of pop up to name width.
Changed the items property of pop up to contents.
Added support to list box for initial multiple selections.
Changed the items property of list box to contents.
Changed label property of text field to name.
Changed label bounds property of text field to name bounds.
Changed label property of password field to name.
Changed label bounds property of password field to name bounds.
Changed label property of static text to contents.
Changed label property of group box to name.
Changed data property of pict to contents.
Changed data property of icon to contents.
Added support to radio group for dependencies.
Changed depends on property of all dialog items to enabled.
Added support to for initially disabled items.
Added new color picker class.
Added new gauge class.

Note: The 'label' property was replaced with 'name' (except in the static text class where it was replaced with 'contents') and the 'data' & 'the items' properties were replaced with 'contents'. DD v0.6 has extra code to support backward compatibility with DD v0.5.1. All scripts compiled with DD v0.5.1 should continue to function with DD v0.6. However, future versions of DD may not be compatible with 'replaced' properties. It is therefore advisable to update and recompile all your scripts with DD v0.6

Dialog Director v0.5.1 (6 Dec '96)

Fixed tabbing direction. (Tab & Shift-Tab were transposed in v0.5 :-).
Fixed documentation and example inconsistencies. Specifically condense Æ condensed and centered Æ center. (All the right characters ... but not necessarily in the right order :-).
Removed default button outline in floating windows.
Changed item drawing order to be the same as the item list order.
Fixed minor sub-window update-on-close problem.
Added full support for pict and icon data properties.
Added support for primary, secondary & tertiary style separator lines.
Added standard notification when in background and trying to opening a window (actually in 0.5 but forgot to mention it).
Changed grey/colour drawing to take place on > 2 bit deep displays only. (Previously some were > 2, some > 1).
Added support for typing carriage returns in text multi-line fields.
Added 'last item of the result' is the final bounds rectangle of the window.
Added calc window bounds event handler, to calculate the initial window bounds.
Added support for dialog items with dependencies on specific list box items.
Fixed an annoying TextEdit 'feature' if ¨ or Æ is pressed when a selection exists.
Improved the dictionary (I hope :-).
Added some more examples.
Included Resource Utilities v1.0b1 osax and examples (no documentation yet).

Dialog Director v0.5 (25 Nov '96)

This release includes a few fixes, many new features, some changes and a couple of experimental items which are marked and should be used with caution.
Changed all property and class 4 character codes (in an attempt to avoid future terminology conflicts).
Added action property to push button class. An action may be a dialog record or a script handler [experimental]. The value of an actioned push button is the result of the action.
Added font spec class with name, size, style and color properties.
Added floating parameter to do dialog [experimental]. This makes all your DD windows float above all other applications (see do dialog below). (I said it was impossible ... I didn't say I couldn't do it ;-)
Added font parameter to do dialog.
Added greyscale parameter to do dialog, support for Apple Greyscale Appearance (AGA).
Added style, name and font properties to dialog class.
Changed pop up class to return a string when the items is a resource type such as 'FONT'.
Changed the nothing's that were returned by do dialog to null's. (I previously did not know that a 'null' in a script is not actually a null object but the type of the null object!)
Replaced text font, text size & text style properties with font property in static text class.
Added justification property to static text class.
Replaced frame class with group box class.
Added style property (primary group, secondary group & tertiary group) to group box class.
Added support for enabling and disabling list boxes.
Resolved failure of Event Manager to deliver null events when update events are pending.
Increased maximum number of pop up menus from 10 to 16. This can now be increased even further by the user (see Class pop up below).
Does not open window until application is in front (blinks Application Menu icon), or if user interaction has been disabled (returns error).
Addressed all (four) reported problems. There were two terminology conflicts (I suppose that I shouldn't have assumed that keyAEPropData was a property called data) and the above mentioned pop-up menu limit and Event Manager problems.

Dialog Director v0.4 (27 Oct '96)

This was the first public release of Dialog Director.

Installing Dialog Director

To install Dialog Director all you have to do is copy the "Dialog Director" scripting addition file into the "Scripting Additions" folder. If your computer is running Mac OS 8 or later then this is in your System folder. If your computer is running Mac OS 7.6.1 or earlier then this is in the "Extensions" folder in your System folder. If you intend to make use of DD's floating windows then you may also want to install the "TSM Fix 1.03" System extension. This fixes some problems in Mac OS where it may miss clicks in floating windows. To install, just drop the "TSM Fix 1.03" extension file on your System folder. Note: TSM Fix is by Matt Slot and may be redistributed independently of Dialog Director. Now you are ready to run the sample scripts and write your own.

Auto Dialogs and Live Dialogs

Welcome

Current features include

Dialog item types

Other

Future features

Licence