TweetFollow Us on Twitter

A Select Few

Volume Number: 16 (2000)
Issue Number: 10
Column Tag: Carbon Development

A Select Few...

by Daniel Jalkut

Taking advantage of Apple's standardized Type Selection API

Introduction

A feature frequently overlooked by new Mac OS users is the ability to select items from a list by typing part of its name. Apple calls this functionality "type selection." Seasoned Mac users are accustomed to type selection and navigate rapidly through Finder hierarchies and StandardFile dialogs without ever letting their hands leave the keyboard. When a user discovers this feature, it is probably with some disappointment that they find support for type selection varies widely amongst third-party applications. Every application that uses StandardFile and Navigation Services dialogs gets type selection for free in those portions of their program. For custom application dialogs and views, developers have been required to write their own, custom type selection code. The result is that some applications don't support type selection at all, some support it to varying extents, and almost none support it in a way that mimics every last nuance of Apple's own type selection algorithm. The opportunity to end these inconsistencies is before us, for Apple's Type Selection APIs have made their public debut.

Without fanfare, Apple included their time-tested internal Type Selection APIs in the first public releases of the CarbonLib extension for Mac OS. As of this writing, the latest version is CarbonLib 1.0.4, and it is available from Apple's web site at http://asu.info.apple.com/swupdates.nsf/artnum/n11673. CarbonLib is the library that enables applications ported to Mac OS X's Carbon APIs to continue running on Mac OS 9 and earlier (as early as 8.1) systems. There is no shortage of compelling reasons to port your application to Carbon. Apple's decision to support two platforms with a nearly identical API set provides an irresistibly easy way of adding Mac OS X to the list of your supported platforms, without losing your existing customer base. Access to standardized type selection is by no means the greatest benefit of porting to Carbon, but it has the potential of causing a vast improvement in the user's experience on the Mac.

What's The Big Deal?

You might be wondering why something as seemingly straightforward as selecting list items with the keyboard should require a standardized API. The user hits a key, you select a matching item, and we're done - right? Actually, the apparent simplicity of type selection is a testament to its internal complexity. You may not have even considered much of the functionality Apple's TypeSelect APIs provide unless you have spent a great deal of time focusing only on the dynamics of type selection. Most developers do not have the time to become type selection experts, so they implement something that makes sense to them, yet lacks the subtle elegance of Apple's code. Some of the features of Apple's API are:

International Support

Support for international scripts, which Apple has always promoted, is becoming more and more important as the customer base for Apple outside of the United States continues to grow. As a developer, anything that provides international support for free is a big win for your product, because it is one fewer thing you need to worry about when pushing to make a localized release available. Apple's type selection APIs use script-aware string comparison functions, which in turn guarantee that every selection made by the user causes a match as expected for the appropriate script.

Multi-Character Matching

A major shortcoming of some third-party implementations of type selection is that only the last key pressed is ever used as a criterion for matching against items. If you type characters in a Finder view, you will notice that the active selection changes as the characters you type grow into a more specific match with the item you're seeking. For instance, if there are three icons in a view, "Belize", "Biafra", and "Burundi", typing just "B" will select the first, "Bi" the second, and "Bu" the third. In an implementation that didn't support multi-character matching, the user would be forced to type "B" to locate the first item, and then navigate with arrow keys to the desired item. No amount of typing would select either "Biafra," or "Burundi" without moving a hand from the keyboard to the mouse.

Time-Out and Cancellation

One unexpectedly complicated aspect of a proper type selection implementation is elegantly guessing the train of thought a user has embarked on: knowing when to stop one selection and begin another. This task is impossible to do correctly every time, but Apple comes close with comfortable and consistent behavior that gives the user a great deal of control.

The type selection APIs keep a running tab of the keys that have been pressed, and when no keys have been pressed for a duration of time, that buffer is flushed, with the assumption that the user has finished typing the fragment they were seeking. To accommodate the user who knows they have mistyped, or who has quickly changed their mind, the APIs also respond to the escape key, which forces type selection to clear its buffers and begin matching keys as a new string.

Implementing Type Selection In A List

To demonstrate the use of the type selection APIs, I have included with this article a sample application, "ListSample", which simply displays a list of selectable items in a dialog. The applications responds to keyDown events by passing them to the Type Selection API, "TypeSelectNewKey", which determines whether the key pressed justifies searching for a new match. If it does, another API, "TypeSelectFindItem" is called, which uses the state of the key buffer and a list of items provided by the client to determine the most appropriate selection.

Application Prerequisites

Before I could implement type selection in ListSample, I first had to ensure that the application had been carbonized and compiled with Apple's latest Universal Headers. If you have already carbonized your application, then you're ready to go. If you haven't, then you will need to do so before you can call any of the Type Selection APIs described in this article.

ListSample Implementation

The easiest way to demonstrate the use of the Type Selection APIs is to explain the three pieces of code in ListSample which interact with the APIs:

  • A TypeSelectRecord is initialized before any type selection can occur.
  • Key down events are passed to Type Selection, and a new match is found if appropriate.
  • A callback routine for finding matches is implemented.

First, initialize a TypeSelectRecord. This is done by calling TypeSelectClear() with an empty TypeSelectRecord as its parameter. In ListSample, this is done in main()

Listing 1: main

Main

Setup the menu bar, initialize TypeSelection, create our sample dialog and run the event loop until we are quit.

main()
{   
   // Setup the menu bar
   SetMenuBar(GetNewMBar(rAppMenuBarID));
   DrawMenuBar();
   
   // Initialize the type selection record
   TypeSelectClear(&gTypeSelectState);
   
   // Prepare the sample dialog
   gTheDialog = SetupSampleDialog();
   if (gTheDialog != NULL)
   {
      // Handle Events!
      while (gQuitApplication == false)
      {
         ApplicationEventLoop();
      }
      DisposeDialog(gTheDialog);
   }
   
   ExitToShell();
   return 0;
}


Next, for each keyDown event that pertains to the list, ask if a new item needs to be matched. This is done by calling TypeSelectNewKey() - if it returns true, then it is time to find a new match for the list by calling TypeSelectFindItem. I have implemented this functionality in the ListSample routine that handles all keyDown events:

Listing 2: HandleKeyDownEvent

HandleKeyDownEvent

Handle key down events not handled by the Dialog Manager. If the key is not a menu-shortcut, then ask the TypeSelection APIs whether the key might change the state of the current selection, and if so, ask it to determine the new selection

void HandleKeyDownEvent(EventRecord* theEvent)
{
   Boolean               eventHandled = false;
   static IndexToStringUPP   myStringGetter = NULL;
   
   // Handle the cmd-key menu case first
   if(theEvent->modifiers & cmdKey)
   {
      long   menuKeyResult;
      
      menuKeyResult = MenuKey(theEvent->message &charCodeMask);
   DoMenuSelection(HiWord(menuKeyResult),
                           LoWord(menuKeyResult));
   }                        
   else if (gTheDialogList != NULL)
   {
      // Only allocate the IndexToStringUPP once
      if (myStringGetter == NULL)
      {
         // This call-back function is used by Type Selection to
         // fetch elements of the list the user is navigating.
         myStringGetter =
                        NewIndexToStringUPP(GetStringFromIndex);      
      }      

      // Ask Type Select APIs whether we need to re-check
      // the selection
      if (TypeSelectNewKey(theEvent, &gTypeSelectState))
      {
         short            listCount;
         short            newListIndex = 0;
         Cell               newSelection;
         
         // How many items are we dealing with?
         listCount = (**gTheDialogList).dataBounds.bottom;
         
         // Ask Type Select for a new index, based
         // on the current state of typing
         newListIndex = TypeSelectFindItem(&gTypeSelectState,
                                       listCount, tsNormalSelectMode,
                                       myStringGetter, NULL);
         
         // Unset any selected items before choosing
         // a new selection
         SetPt(&newSelection, 0, 0);                              
         // Starting at the beginning, get a selected cell
      while (LGetSelect(true, &newSelection, gTheDialogList))
         {
            // Unselect it
            LSetSelect(false, newSelection, gTheDialogList);
         }
         
         // Set the new item to selected
         SetPt(&newSelection, 0, newListIndex - 1);
         LSetSelect(true, newSelection, gTheDialogList);      
         
         // Auto scroll to make sure the selection is visible
         LAutoScroll(gTheDialogList);
         
         // Workaround to List Box control behavior - LsetSelect
         // causes an immediate redraw into the list's port,
         // which in the ListBox control case is an offscreen
         // buffer allocated by the control manager, and doesn't
         // cause an update event to be generated for the parent
         // window, so we need to force a redraw.
         DrawOneDialogItem(gTheDialog, rDialogListBoxItem);         
      }
   }
}



One of the parameters to the TypeSelectFindItem call is a callback routine that you provide to allow TypeSelection to determine the elements of the list it is choosing from. Depending on the circumstances of your implementation, the items you are selecting from might not be a straightforward list. In our case the routine is quite simple. It simply looks up the desired index in the list control we are searching in:

Listing 3: GetStringFromIndex

GetStringFromIndex

Callback routine for the type selection routine TypeSelectFindItem(). This routine is called to fetch the items in a list, and determines which of the items is the best choice considering the key strokes that have been pressed.

pascal Boolean
GetStringFromIndex(short theIndex, ScriptCode *whichScript,
                           StringPtr *whichString, void *ignored)
{
#pragma unused (ignored)
   Boolean            returnValue;
   static Str255   thisString;      // static because we return a
                                       // pointer to this string
   
   // Set the script - in this sample, we know that
   // all the list items are in Roman script.
   *whichScript = smRoman;
   
   if (gTheDialogList != NULL)
   {
      Cell   desiredCell;
      short   stringLength = 255;
      
      // Fetch the item from the list, 

      // and get the cell data (a string) into the result

      SetPt(&desiredCell, 0, theIndex - 1);      
      LGetCell(thisString + 1, &stringLength, desiredCell, 
                     gTheDialogList);
      thisString[0] = stringLength;
      *whichString = thisString;
      returnValue = true;

   }
   else
   {
      *whichString = NULL;
      returnValue = false;   
   }
   
   return returnValue;
}

Summary

Type selection is certainly not the top selling point of Carbon. The APIs I have described would have been appreciated if they were publicized years ago in the classic Mac OS arena, but at least they have finally arrived in Carbon. I hope this article has demonstrated that it's not difficult at all to implement this functionality, and that the benefits to the customer are overwhelming. I hope to see all of your applications sporting fancy new type selection capabilities in their next releases. Happy typing!

Acknowledgements

Thanks to Darren Litzinger for reviewing this article.


The type selection APIs consist of only four routines and one callback routine. Here is a short description of their functionality:

TypeSelectClear

Used to initialize a TypeSelectRecord, which is the data structure that holds the state of type selection at any given time. Call this routine at least once, when your application is starting up. After you launch, only call this routine if you want to intentionally void the typing the user has made at a given point.

void         TypeSelectClear(TypeSelectRecord *tsr);

tsr   Points to a TypeSelectRecord, which requires initialization.

TypeSelectNewKey

Every time your application receives a keyDown event that might pertain to selection of a list item, you should pass the event to this routine. It examines the current buffer of characters and the value of the key event it is receiving, and returns true if the new keystroke has warranted the need to update the active list selection.

Boolean   TypeSelectNewKey(const EventRecord *theEvent,
                                    TypeSelectRecord *tsr);

theEvent   A pointer to an event record containing a keyDown event. 

tsr   Points to a TypeSelectRecord previously initialized with TypeSelectClear.

TypeSelectFindItem

When TypeSelectNewKey returns true, use this routine to actually determine the most appropriate list item to receive the new selection. This routine takes as a parameter a callback function that you use to supply the algorithm with the contents of your list.

short       TypeSelectFindItem(const TypeSelectRecord *tsr,
                                    short listSize, TSCode selectMode,
                                    IndexToStringUPP getStringProc,
                                    void *yourDataPtr);

tsr   Points to a TypeSelectRecord previously initialized with TypeSelectClear.

listSize The number of items in the list you are selecting from. If the number of items is unknown, pass 0x7FFF, and be sure that your callback function returns false when a requested index is not found.

selectMode Specify one of "tsPreviousSelectMode", "tsNormalSelectMode", or "tsNextSelectMode" to request the item before the matched item, the matched item itself, or the item after the matched item. The previous and next modes are what the Finder uses to respond to the Tab and Cmd-Tab keys. Typically you will pass tsNormalSelectMode.

getStringProc   Pass a UPP to a routine that will fetch strings by index from
the list of items you are selecting from.

yourDataPtr   Pass any value you would like to have passed back to your callback
function.

TypeSelectCompare

TypeSelectCompare is used to compare specific items from a list, using the exact same comparison that TypeSelect would use in a call to TypeSelectFindItem. This is useful if you have a sorted list, and want to optimize item selection based on knowledge about the sorting in the list. TypeSelectFindItem compares each and every item in a list, so for very long lists pre-sorting and using TypeSelectCompare might result in a performance gain.

short       TypeSelectCompare(const TypeSelectRecord * tsr,
                                    ScriptCode testStringScript,
                                    StringPtr testStringPtr);      

tsr   Points to a TypeSelectRecord previously initialized with TypeSelectClear.

testStringScript   Indicates the script of the string that is being compared.

testStringPtr   Points to the string that is being compared.

MyIndexToStringProc

This routine is defined by your code, and serves as an access point for TypeSelection to determine the items of the list that you are selecting from. When called, you will need to fetch and return a string from your list that is indexed by the given item number. You must return both a pointer to the string and the script code for that item.

Boolean   MyIndexToStringProc(short item, 
                                    ScriptCode *itemsScript,
                                    StringPtr *itemsStringPtr,
                                    void *yourDataPtr);

item   The index of the list item being requested.

itemsScript   You return the script of the requested string here.

itemsStringPtr   You return a pointer to the requested string here.

yourDataPtr   A reference pointer for whatever you choose.

Daniel Jalkut is a software engineer in the Mac OS X Carbon API group at Apple Computer. In his spare time, Daniel works on his guitar playing and book reading. You can contact him at jalkut@red-sweater.com, or view his home page at http://www.red-sweater.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Macs Fan Control 1.5.14 - Monitor and co...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
VueScan 9.7.96 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
FileMaker Pro 19.6.1 - Quickly build cus...
FileMaker Pro is the tool you use to create a custom app. You also use FileMaker Pro to access your app on a computer. Start by importing data from a spreadsheet or using a built-in Starter app to... Read more
Duet 3.1.0.0 - Use your iPad as an exter...
Duet is the first app that allows you to use your iDevice as an extra display for your Mac using the Lightning or 30-pin cable. Note: This app requires a iOS companion app. Release notes were... Read more
Firefox 107.0.1 - Fast, safe Web browser...
Firefox offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals and casual... Read more
War Thunder 2.21.1.91 - Multiplayer war...
In War Thunder, aircraft, attack helicopters, ground forces and naval ships collaborate in realistic competitive battles. You can choose from over 1,500 vehicles and an extensive variety of combat... Read more
Numbers 12.2.1 - Apple's spreadshee...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
DEVONthink Pro 3.8.7 - Knowledge base, i...
DEVONthink is DEVONtechnologies' document and information management solution. It supports a large variety of file formats and stores them in a database enhanced by artificial intelligence (AI). Many... Read more
Drive Genius 6.2.3 - $79.00
Drive Genius features a comprehensive Malware Scan. Automate your malware protection. Protect your investment from any threat. The Malware Scan is part of the automated DrivePulse utility. DrivePulse... Read more
VLC Media Player 3.0.18 - Popular multim...
VLC Media Player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, MP3, OGG, ...) as well as DVDs, VCDs, and various streaming protocols. It... Read more

Latest Forum Discussions

See All

‘Genshin Impact’ Version 3.3 Pre-Install...
Following the reveal of the release date and more for Genshin Impact (Free) version 3.3 ‘All Senses Clear, All Existence Void’, HoYoverse showcased the Genius Invokation TCG that arrives this week in the update. | Read more »
TouchArcade Game of the Week: ‘Sling Min...
The world of PC games has always blown my mind because there’s just SO MUCH stuff out there that it’s not uncommon at all for there to be a game that’s well-liked and well-reviewed, and seemingly quite popular with a solid fanbase, and have it be... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for December 2nd, 2022. So, today turned out a little quieter than the usual Friday. It was so quiet, in fact, that I decided to pen a few reviews. The Knight Witch, Railbound, and Donut... | Read more »
Blue Archive reveals its latest event st...
Nexon has announced the new update for Blue Archive, under the name of An Unconcealed Heart. Featuring a battle between two academies, the story will follow a group struggling to gain recognition, and will bring three new students to recruit. [... | Read more »
Dead Cells+ Is Out Now on Apple Arcade a...
Following the major update for Dead Cells on iOS and Android a few days ago, Playdigious has brought Dead Cells+ () to Apple Arcade. As an App Store Great, Dead Cells+ includes all prior paid DLC and content updates. It also has exclusive mobile... | Read more »
SwitchArcade Round-Up: ‘Romancing SaGa’,...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for December 1st, 2022. Wow, December. We’re already at the last month of the year? Phew. I have a lot of work to finish in the next few weeks. As for today, we’ve got a little news, a... | Read more »
‘Railbound’ Update Now Available Adding...
One of our favorite puzzlers released this year is Railbound from Afterburn Games, which hit in early September and earned our Game of the Week recognition for being an absolutely ace logic puzzler. The goal is to place rail pieces down in order to... | Read more »
The Seven Deadly Sins: Grand Cross celeb...
Netmarble Corporation has pulled out all the stops to celebrate the 3 and a half year anniversary of The Seven Deadly Sins: Grand Cross. The Grand Cross 3.5th Year Anniversary the Ultimate One, a rather wordy title, brings with it a brand new... | Read more »
‘Skullgirls Mobile’ Major Update 5.2 Out...
Developer Hidden Variable pushed out a major update for Skullgirls Mobile (Free) a few hours ago. The version 5.2 update brings in Black Dahlia (before the console and PC game), Retakes, XP Treats, free gifts, and more. Since launch, Skullgirls... | Read more »
Out Now: ‘Disgaea 4’, ‘Romancing SaGa: M...
Each and every day new mobile games are hitting the App Store, and so each week we put together a big old list of all the best new releases of the past seven days. Back in the day the App Store would showcase the same games for a week, and then... | Read more »

Price Scanner via MacPrices.net

Holiday Sale: Apple AirPods Pro for only $199...
Amazon has new 2022 AirPods Pro in stock and on sale for $199.99 shipped as part of their Holiday sale. Their price is $50 off Apple’s MSRP, equaling their Black Friday price, and it’s the lowest... Read more
New Holiday Sale: Apple retailers are offerin...
Several Apple retailers lowered prices on 10.9″ iPad Airs overnight to lows of $100 off MSRP starting at $499. Their prices are the lowest available for iPad Airs anywhere this Holiday season right... Read more
New Holiday sale at Amazon: Take $50 off Appl...
Amazon has Apple’s new 10th-generation iPads in stock and on sale, for the first time, for $50 off MSRP starting at only $399. Their discount applies to all models and all colors. With the discount,... Read more
Holiday Sale: Get an 8.3″ Apple iPad mini for...
Sams Club has 10.9″ 64GB iPad minis on Holiday sale for $80-$100 off MSRP through December 7, 2022. With their discount, prices start at $399 — the cheapest price for a new iPad mini from any of the... Read more
Sams Club Holiday December Event sale: Apple...
Apple AirPods Max headphones are on sale at Sams Club for $110 off MSRP ($439) as part of their December Event sale, ending on December 7, 2022, valid for all colors. Sale price for online orders... Read more
Apple’s 10.2″ 64GB 9th-generation iPads are o...
Sams Club has 9th-generation 64GB iPads on Holiday sale for $60 off MSRP through December 7, 2022. With their discount, prices start at $259 — the cheapest price for a new iPad from any of the Apple... Read more
11″ 128GB WiFi M2 iPad Pro on sale for $749,...
B&H Photo has the new 11″ 128GB WiFi M2-powered iPad Pro (in Space Gray or Silver) on Holiday sale for $749 including free 1-2 day shipping to most US addresses. Their price is $50 off MSRP and... Read more
Find the best Holiday sale price on an iPad u...
We’ve updated our iPad Price Trackers with the latest information on the new 10th-generation iPads, M2-powered iPad Pros, M1 iPad Airs, iPad minis, and 9th generation iPads from Apple’s authorized... Read more
Apple retailers are offering $100-$150 Holida...
Apple retailers have posted their most-recent Holiday sale prices on 13″ MacBook Airs. Take up to $150 off MSRP on M2-powered Airs with these sales with prices starting at only $1099. Free shipping... Read more
Holiday Sale: Apple’s 14″ MacBook Pros with M...
B&H Photo is offering $200-$300 discounts on Apple’s 14″ MacBook Pros with M1 Pro CPUs as part of their Holiday 2022 sale, with prices starting at $1799. Free 1-2 day shipping is available to... Read more

Jobs Board

Support Technician II - *Apple* Support - O...
…problems and acting as a liaison between customers and resolving groups. As an Apple Technical Specialist, you will be supporting many of our popular Apple Read more
*Apple* Electronic Repair Technician - PlanI...
…a highly motivated individual to join our Production Department as an Apple Electronic Repair Technician. The computer repair technician will diagnose, assemble, Read more
Lead Developer - *Apple* tvOS - Rumble (Uni...
…earnings, and positive sentiment About the role: We are looking for a Lead Apple tvOS Developer to join our application engineering team to expand our video centric Read more
Tier 1 Endpoint Engineer - *Apple* - Red Ri...
…Desk on site, at our Client's location, with a focus on support to Apple products. This position will handle technical support requests directly from customers and Read more
Product Manager II - *Apple* - DISH (United...
…you will be doing We seek an ambitious, data-driven thinker to assist the Apple Product Development team as our new Retail Wireless division continues to grow and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.