TweetFollow Us on Twitter

DialogKeyFilter
Volume Number:9
Issue Number:7
Column Tag:Pascal Workshop

Related Info: Dialog Manager Event Manager List Manager

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 or source 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   }
{ normal button (not Checkbox/radio).  }
{**************************************}
  var
   IType: integer;
   IHandle: Handle;
   IRect: Rect;
 begin
  GetDItem(Dialog, Item, IType,
                   IHandle, IRect);
  ButtonItem := BAND(IType, 255 -
   itemDisable) = (ctrlItem + btnCtrl);
 end; {ButtonItem}

 function Enabled (Item: integer)
        : boolean;
    {uses Dialog: DialogPtr}
{**************************************}
{ Checks whether the item is enabled.  }
{**************************************}
  var
   IType: integer;
   IHandle: Handle;
   IRect: Rect;
 begin
  GetDItem(Dialog, Item, IType,
                   IHandle, IRect);
  Enabled := BAND(
              IType, itemDisable) = 0;
 end; {Enabled}

 procedure EditCommand (key: Byte);
     {uses Dialog: DialogPtr}
     {sets event: EventRecord}
     {sets itemHit: integer}
     {sets filtered: boolean}
{**************************************}
{ Performs the specified Edit command. }
{**************************************}
 begin
  itemHit := DialogPeek(Dialog)^.
             editField + 1;
  case key of
   KeyX, KeyF2: 
    begin
     DlgCut(Dialog);
     if itemHit > 0 then
      event.message :=
                  convertClipboardFlag;
    end;
   KeyC, KeyF3: 
    begin
     DlgCopy(Dialog);
     if itemHit > 0 then
      event.message :=
                  convertClipboardFlag;
     itemHit := 0;
    end;
   KeyV, KeyF4: 
    begin
     DlgPaste(Dialog);
    end;
  end; {case}
  if itemHit > 0 then
   if Enabled(itemHit) then
    filtered := true;
  if not filtered then
   event.what := nullEvent;
 end; {EditCommand}

 procedure FrameButton (Item: integer);
     {uses Dialog: DialogPtr}
{**************************************}
{ Frames the specified (button) item,  }
{ to designate it as the default.      }
{**************************************}
  var
   IType: integer;
   IHandle: Handle;
   IRect: Rect;
   savePen: PenState;
 begin
  GetDItem(Dialog, Item, IType,
                   IHandle, IRect);
  GetPenState(savePen);
  PenNormal;
  PenSize(3, 3);
  InsetRect(IRect, -4, -4);
  FrameRoundRect(IRect, 16, 16);
  SetPenState(savePen);
 end; {FrameButton}

 function NumItems: integer;
    {uses Dialog: DialogPtr}
{**************************************}
{ Returns no. of items in item list.   }
{**************************************}
  type
   DITLHandle = ^DITLPtr;
   DITLPtr = ^DITL;
   DITL = packed record
     NumItemsLess1: integer;
      {followed by the items, but we...}
      {don’t need them in this function}
    end; {DITL}
 begin
  NumItems := DITLHandle(DialogPeek(
   Dialog)^.items)^^.NumItemsLess1 + 1;
 end; {NumItems}

 procedure SetItemHit (Item: integer);
     {uses Dialog: DialogPtr}
     {sets itemHit: integer}
{**************************************}
{ Sets itemHit to the specified item & }
{ flashes it if it’s an enabled button.}
{**************************************}
  var
   IType: integer;
   IHandle: Handle;
   IRect: Rect;
   Btn: ControlHandle;
   SaveState: Byte;
   finalTicks: longint;
 begin
  itemHit := Item;
  if Enabled(Item) & ButtonItem(Item)
   then begin
    GetDItem(Dialog, Item, IType,
                     IHandle, IRect);
    if IHandle <> nil then
     begin
      Btn := ControlHandle(IHandle);
      SaveState := Btn^^.contrlHilite;
      HiliteControl(Btn, inButton);
      Delay(6, finalTicks);
      HiliteControl(Btn, SaveState);
     end; {IHandle <> nil}
   end; {Enabled button}
  filtered := true;
 end; {SetItemHit}

 function TestItem (Item: integer;
              Ch: char): boolean;
    {uses Dialog: DialogPtr}
{**************************************}
{ Tests the specified dialog item for  }
{ the designated upper case char.      }
{**************************************}
  var
   IType: integer;
   IHandle: Handle;
   IRect: Rect;
   ITitle: str255;
   Posn: integer;
 begin
  TestItem := false;
  GetDItem(Dialog, Item, IType,
                   IHandle, IRect);
  if IType in [ctrlItem + btnCtrl,
               ctrlItem + chkCtrl,
               ctrlItem + radCtrl] then
   begin {it’s a Control item}
    if IHandle <> nil then
     begin
      GetCTitle(
       ControlHandle(IHandle), ITitle);
      if ITitle <> ‘’ then
       begin
        for Posn := 1 to length(ITitle)
        do
         if ITitle[Posn] in [‘A’..’Z’]
          then Leave; {for loop}
        if Posn <= length(ITitle) then
         if ITitle[Posn] = Ch then
          if Enabled(Item) then
           TestItem := true;
       end; {ITitle <> ‘’}
     end; {IHandle <> nil}
   end; {it’s a Control item}
 end; {TestItem}

 procedure SearchForItem (Ch: char);
     {sets itemHit: integer}
{**************************************}
{ Searches item list for Control with  }
{ specified upper case char. in title. }
{**************************************}
  var
   Item: integer;
   Found: boolean;
 begin
  itemHit := 0;
  if Ch in [‘a’..’z’] then
   begin
    Found := false;
    Ch := chr(ord(Ch) - 32);
                {Convert to Upper case}
    for Item := 1 to NumItems do
     if (Item <> defItem) &
        (Item <> Cancel) then
      if TestItem(Item, Ch) then
       begin
        SetItemHit(Item);
        Found := true;
        Leave; {for loop}
       end;
    if not found then
     if TestItem(defItem, Ch) then
      SetItemHit(defItem);
   end; {key in range ‘a’..’z’}
 end; {SearchForItem}

begin {DialogKeyFilter}
{**************************************}
{           The main logic.            }
{**************************************}
 filtered:= false;
 defItem:= DialogPeek(Dialog)^.aDefItem;
 if event.what in [keyDown,autoKey] then
  begin
   keyChar := chr(BAND(event.message,
                  charCodeMask));
   keyCode := BSR((BAND(event.message,
                   keyCodeMask)), 8);
   if keyChar in [kEnter, kReturn] then
    SetItemHit(defItem)
   else if keyChar = kEscOrClear then
    SetItemHit(Cancel)
   else if (BAND(event.Modifiers,
         CmdKey) <> 0) & (keyChar = ‘.’)
   then {Command-period}
    SetItemHit(Cancel)
   else {not Enter/Return/Esc/Cmd-.}
    begin
     if DialogPeek(Dialog)^.
             editField + 1 <> 0 then
      {...an editable text field exists}
      if keyCode in [KeyF2,KeyF3,KeyF4]
      then
       EditCommand(keyCode)
      else if BAND(event.Modifiers,
                    CmdKey) <> 0 then
       if keyCode in [KeyX, KeyC, KeyV]
       then
        EditCommand(keyCode)
       else
        SearchForItem(keyChar)
      else
         {Editable text field exists}
         {and Command Key isn’t down}
         {... so we do nothing here.}
     else {no editable text field}
      SearchForItem(keyChar);
    end; {not Enter/Return/Esc/Cmd-.}
  end {keyDown, autoKey}
 else if (event.what = updateEvt) then
  if WindowPtr(event.message) = thePort
  then
   if ButtonItem(defItem) then
    FrameButton(defItem);
 DialogKeyFilter := Filtered;
end; {DialogKeyFilter}
END OF SOURCE LISTING
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Battle Cars (Games)
Battle Cars 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Welcome to the world of Battle Cars. Battle Cars is a classic arcade top-down racing game with fast mini cars and funny weapons to... | Read more »
How to get started with live.ly
One could be forgiven for thinking that there are already plenty of streaming video apps out there. It's just that the App Store charts would insist that you're mistaken. [Read more] | Read more »
Rodeo Stampede: Guide to all Savannah an...
A "gotta catch 'em all" joke seems appropriate here, even though we're talking animals in Rodeo Stampede and not pocket monsters. By now you've probably had plenty of rides, tamed some animals and built yourself a pretty nice zoo | Read more »
Is there cross-platform play in slither....
So you've sunken plenty of hours into crawling around in slither.io on your iPhone or iPad. You've got your stories of tragedy and triumph, the times you coiled four snakes at one time balanced out by the others when you had a length of more than... | Read more »
Rodeo Stampede guide to running a better...
In Rodeo Stampede, honing your skills so you can jump from animal to animal and outrun the herd as long as possible is only half the fun. Once you've tamed a few animals, you can bring them home with you. [Read more] | Read more »
VoxSyn (Music)
VoxSyn 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: VoxSyn turns your voice into the most flexible vocal sound generator ever. Instantly following even subtle modulations of pitch and... | Read more »
Catch Battleplans on Google Play from Ju...
Real-time strategy title Battleplans is due for release on Google Play on June 30th, following its release for iOS systems last month. With its simple interface and pretty graphics, the crowd-pleaser brings a formerly overlooked genre out for the... | Read more »
iDoyle: The interactive Adventures of Sh...
iDoyle: The interactive Adventures of Sherlock Holmes - A Scandal in Bohemia 1.0 Device: iOS Universal Category: Books Price: $1.99, Version: 1.0 (iTunes) Description: Special Release Price $1.99 (Normally $3.99) | Read more »
Five popular free apps to help you slim...
Thanks to retail and advertising, we're used to thinking one season ahead. Here we are just a week into the summer and we're conditioned to start thinking about the fall. [Read more] | Read more »
How to ride longer and tame more animals...
It's hard to accurately describe Rodeo Stampede to people who haven't seen it yet. It's like if someone took Crossy Roadand Disco Zoo and put them in a blender, yet with a unique game mechanic that's still simple and fun for anyone. [Read more] | Read more »

Price Scanner via MacPrices.net

MacBook Airs on sale for up to $50-$100 off M...
B&H Photo has 13″ and 11″ MacBook Airs on sale for up to $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 1.6GHz/128GB MacBook Air: $849 $50 off list price - 11″ 1.... Read more
Brexit Vote Result Forecast To Slash UK 2016...
Uncertainty and economic volatility can be expected to increase over the next nine months, as the Brexit and concerns over the future of the EU hit IT investment, say Canalys market analysts, with... Read more
13-inch 256GB MacBook Air on sale for $1149,...
Amazon has the 2016 13″ 1.6GHz/256GB MacBook Air (model MMGG2LL/A) on sale for $1149.99 including free shipping. Their price is also $50 off MSRP. Read more
Haven App Launches New Age Of Wirless 911 Eme...
Haven from RapidSOS represents a transformation in access to emergency services from a phone call solely dependent on voice to a robust data connection for voice, text, medical/demographic data.... Read more
Cu Parachute 1.1 Retirement Success PLanning...
Tucson, Arizona based Indie developer Bradley McCarthy has announce the release of Cu (Copper) Parachute 1.1 for iPhone, iPad, and iPod touch devices — a tool with which users can continuously... Read more
Research and Markets Releases iPhone 6s Plus...
A new analysis report from Dublin-based Research and Markets observes that with the iPhone 6s Plus, Apple introduced a new rear camera module. The new device has similar structure and technology than... Read more
Apple refurbished Retina MacBook Pros availab...
Apple has Certified Refurbished 2015 13″ and 15″ Retina MacBook Pros available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free... Read more
Apple refurbished 11-inch MacBook Airs availa...
Apple has Certified Refurbished 11″ MacBook Airs (the latest models), available for up to $170 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... Read more
Apple price trackers, updated continuously
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: - 15″... Read more
12-inch 32GB and 128GB WiFi iPad Pros on sale...
B&H Photo has 12″ 32GB & 128GB WiFi iPad Pros on sale for up to $80 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 12″ Space Gray 32GB WiFi iPad Pro: $749 $50... Read more

Jobs Board

*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* Retail - Multiple Positions, Towson...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.