DialogKeyFilter
Volume Number: 9
Issue Number: 7
Column Tag: Pascal Workshop
Dab-hand Dialogs from Darkest Africa 
We describe, design, develop and distribute a decent DialogKeyFilter
By Mike O’Hanlon, Cape Town, South Africa
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
About the author
Mike O’Hanlon has been programming the Macintosh on a hobby basis for about 4
years. Anything starting with O’ is likely to be his. O’Tools, O’Heap, O’Files, O’Fonts,
O’Help, O’Clock, O’List and O’Tree are examples. He believes his most useful effort to
date has been O’Structures - a Data Structures library written in Object Pascal. He
thinks C is for the birds. His other preoccupations are his wife, skiing and off-roading
in a Land Rover.
DERELICT DIALOGS
I don’t want to be derogatory, but it’s dawning on this developer that our Dialogs
are looking decidedly disadvantaged. They’re definitely in the Doldrums.
I’m a user interface fanatic, and hopelessly biased towards the Macintosh, so I get
upset when another environment (like Windows) develops a tweak that gives it an edge
over the Mac.
DYNAMIC DEVELOPMENT
In the case of the ubiquitous Modal Dialog, the improvement we should learn from
Microsoft is that of allowing keyboard shortcuts for any enabled buttons, checkboxes
and radio buttons presented in the dialog. The mouse is great, but sometimes the
keyboard is much more convenient. You know the kind of thing: you’ve yanked up a
“Find...” dialog using Command-F; you’ve typed the word you want to find, and you
want to hit Command-W to toggle the “Whole Words” checkbox. With most
applications, you can’t; you have to leave the keyboard and switch to the mouse.
Let’s call these shortcuts Dialog Control keys - to distinguish them from other
types of keyboard shortcut like Menu Command keys, and ‘Type Selection’ of items in a
List box (see Inside Macintosh Vol. VI, page 2-25).
It’s notable that Microsoft’s own applications for the Mac do implement this
feature. The way I see it, Excel and Word are in any event the most popular Macintosh
applications, and in effect this legitimizes such an extension to the Mac user interface.
‘D’ FOR DESKTOP
It’s also in keeping with recent keyboard shortcuts introduced by Apple, such as
Command-D for the ‘DeskTop’ button in the standard file Open... dialog.
The other day, I got down to implementing this in my own applications. Once I got
started, it wasn’t as difficult as I’d thought.
The challenge was to program it in a general purpose fashion and thereby avoid
any App-specific code. I think I have succeeded in this, to the extent that if you use a
resource editor to alter the titles of dialog controls (e.g. to create a foreign language
version of your program), the keyboard shortcuts adapt themselves without any
additional work.
So, to try and ensure that the Mac interface isn’t left behind, here are some
explanatory notes and the code - which I hereby place in the public domain, hoping that
the idea will be adopted by mainstream tool developers such as Symantec (in the THINK
Class Libraries) and Bowers Development (in AppMaker).
DESCRIBING THE IDEA
The original Mac designers cleverly envisaged this kind of thing, and provided a
neat hook for developers in the form of the filterProc parameter to the ModalDialog
toolbox call.
The default system filter simply maps a few basic keys (Return, Enter, Esc etc.)
to certain pre-defined dialog items. What I have done is implemented my ideas for
Dialog Control keys entirely inside a much fuller-function filter procedure which you
can specify in any ModalDialog call. I have called the thing DialogKeyFilter. There’s
nothing else: no additional resources, no global variables, and no heap blocks. I have
kept it as self-contained as possible.
DELICATE DESIGN
The basic principle in the filter is to interpret a key depression as a mouse click
on the lowest numbered dialog item which is an enabled Control, and which has a title
in which the first capitalized (upper case) letter matches the user’s key stroke. The
idea is that the user should be able to use the A key for an “Add” button, the G key for a
“Grid Lines” checkbox, the L key for a “Left Aligned” or “align Left” radio button etc.
(I’ll come to whether or not the Command key is needed in a moment).
DEFAULT DECISION
But we have to be careful in several respects. Firstly, the user interface
guidelines defined by Apple (I.M. Vol. VI, page 2-26) have already allocated two
keyboard equivalents each for the default button (normally OK) and Cancel - namely
Enter/Return and Esc/Command-period. For this reason, and because of possible
confusion with the Copy (Edit menu) command, it makes sense not to associate
Command-C with Cancel. Also, we only allocate an alphabetic Dialog Control key to the
dialog’s default item if there is no other dialog item sharing the same first capitalized
letter. For example, if the default item is ‘OK’, but there is also an ‘Outline’ button,
the ‘O’ key (or Command-O) is interpreted as ‘Outline’, not ‘OK’.
Next, let’s consider the Command key. Should its use be made mandatory, or not?
It depends on whether the dialog contains editable text or List items. If the cursor is
currently in an editable text field, most key depressions must perform their normal
input function. In this case we only interpret the key hit as a Dialog Control key if the
user has the Command key depressed as well. Even then, we must reserve Command-X,
-C and -V for the standard Edit commands.
DIRTY SCRAP
Incidentally, if the user does a Cut or Copy whilst in the dialog, the filter routine
should notify the calling program, so that the latter knows that the scrap is ‘dirty’ and
can act accordingly. The DialogKeyFilter routine provided in the source listing does
this by setting the event.message field to the constant convertClipboardFlag, so that the
developer can test it on return from the ModalDialog call. (The filterProc’s event is a
var parameter). It could alternatively be done by having the filter routine set a global
variable. Neither are very elegant solutions, and this reveals a deficiency in the
filterProc parameter set.
DIALOG LISTS
Now, what happens when a dialog contains one or more List boxes? If a List is
selected (or is the only dialog item which could receive keyboard events) most key
depressions should be interpreted as ‘Type Selection’ in the list. I couldn’t build any
generalized List support into DialogKeyFilter because there’s no way of identifying a
dialog item as a List (it’s just a special case of User item). So, if you have a List in
your dialog box, you’ll have to filter the List first, and then call DialogKeyFilter. (If
there’s any demand, I’ll publish a ListKeyFilter as a follow-up supplement to this
article).
Here’s the full Dialog key-depression logic. The part to be done in a List filter is
in italics:
{1}
KeyDown or AutoKey event:
Enter or Return:
Set item hit to the default item;
Esc. or Command-period:
Set item hit to Cancel; {item 2}
Tab key:
Rotate round Editable text/List items;
Other keys:
Editable text field selected:
F2, F3, or F4 depressed:
It’s an Edit command;
Not F2, F3 or F4:
Command key down:
X, C or V depressed:
It’s an Edit command;
A..Z (but not X, C or V):
Dialog Control key;
Others keys:
Ignore;
Command key not down:
Apply key to the edit field;
List box item selected:
A..Z with Command key:
Dialog Control key;
Otherwise:
Perform ‘Type Selection’;
No Editable text fields or List boxes:
A..Z (Command key optional):
Dialog Control key;
Other keys:
Ignore;
In the logic above, Dialog Control key means we search the dialog item list for a
matching Control. In DialogKeyFilter, I decided not to make the assumption that the
upper case letter will necessarily be the first character in the control’s title. This
allows you to capitalize another letter (such as the first letter of the second word). It
also provides for quirks like Return characters at the start of the item title. (This is a
bit obscure, but you might want to do this to make the control’s title invisible, so that
it can be overlaid with a fancier static text title - eg to show a ‘Bold’ checkbox with a
Bold caption).
MOVABLE & MODELESS
The idea of Dialog Control keys is fully applicable to the new System 7 Movable
Modal dialogs, and the code given works fine with them. It also works fine with
Modeless dialogs, but extension of the idea to Modeless dialogs is arguable: an essential
attribute of the Modeless state is that the majority of Menu commands should remain
available whilst the dialog is up. If Dialog Control keys are allowed in Modeless dialogs
(and assuming that we stick with the Command key as the modifier key), confusion
might arise as to whether a shortcut applies to a dialog control or a menu command.
I believe these shortcuts should be allowed in Modeless dialogs. After all, if the
Modeless dialog is the frontmost window, then it is presumably the focus of the user’s
attention. Nevertheless, if the user hits a Command-key combination which doesn’t
match any dialog item, DialogKeyFilter simply returns false, enabling the command to
be interpreted in the main event loop as a Menu command. Thus, in a frequently
occurring example, Command-Q will still work as Quit even if there is a Modeless
dialog as the front window, provided it doesn’t contain an enabled control with a
capitalized Q. (In that case, he could still Quit from the keyboard using Esc,
Command-Q).
IDEAS DECLINED
Before closing, here are some things that went through my head, but which I
didn’t do. It occurred to me that it might be clever to allocate the Control key instead
of Command as the modifier for use with Dialog Controls. The neat things would have
been:
• dialog items accessed by Dialog Control keys are in fact always Controls;
• the Control key has been looking for a real job ever since it came on the scene;
• confusion with Menu Commands would have been avoided (and there would have
been no argument about shortcuts in Modeless as well as Modal dialogs).
However, many Mac keyboards still don’t have a Control key, and many owners
who do have a Control key like to reserve it for use with a macro recorder like
QuicKeys.
DECIDING INFLUENCES
Two final deciding factors were that it would often have caused awkward shifting
of the modifier finger from Command to Control, and it would have been inconsistent
with MS Word and Excel for the Macintosh. It would also have been inconsistent with
Windows, which uses the ‘Alt’ key for dialog shortcuts. (The PC’s ‘Alt’ key is
normally situated in the same keyboard position as the Mac’s Command key). So on
balance the idea was rejected.
I also toyed with more positive visual cueing of Dialog Control keys, but I
couldn’t come up with anything that was aesthetically pleasing, didn’t chew up too
much dialog real estate and wasn’t a nightmare to implement. So that idea also went out
of the window dialog. Anyway the capitalization should be cue enough, and the user is
given feedback in the normal way (highlighting, checking etc.).
DISCLAIMER
I hope you can see that I’ve given this a fair amount of thought. However, no code
is perfect and I’m sure some of you will be able to suggest improvements. If so, please
write to me at the address given below (unfortunately it’s a bit expensive working
with CompuServe etc. from South Africa). Please also write to me if you can figure
out how to install a filter like this in System 7.0 so that it replaces the default filter
procedure which is used whenever a developer supplies nil as ModalDialog’s
filterProc. Then it would automatically work for all applications which don’t
currently specify a filter routine for dialog boxes. Now that would be clever.
Mike O’Hanlon, Eden House, 49 Eden Road,Claremont, 7700, Cape, South Africa.
SOURCE LISTINGS
function DialogKeyFilter (
Dialog: DialogPtr;
var event: EventRecord;
var itemHit: integer): boolean;
{**************************************}
{ Implements “Dialog Control keys” - }
{ keyboard shortcuts for buttons, }
{ checkboxes and radio buttons. }
{ Author: Mike O’Hanlon. }
{**************************************}
const
kEnter = chr(3); {Enter key}
kReturn = chr(13); {Return key}
kEscOrClear = chr(27); {Esc/Clear}
KeyX = 7; {-X = Cut}
KeyC = 8; {-C = Copy}
KeyV = 9; {-V = Paste}
KeyF2 = $78; {F2 = Cut}
KeyF3 = $63; {F3 = Copy}
KeyF4 = $76; {F4 = Paste}
var
filtered: boolean;
defItem: integer;
keyChar: char;
keyCode: Byte;
function ButtonItem (Item: integer)
: boolean;
{uses Dialog: DialogPtr}
{**************************************}
{ Checks whether specified item is a }
Referenced by (2):