TweetFollow Us on Twitter

Gearing Up for Asia With the Text Services Manager and TSMTE

Gearing Up for Asia With the Text Services Manager and TSMTE

Tague Griffith

Are you eyeing Asian markets for your application? If so, the smartest thing you can do to gear up is to enlist the aid of the Text Services Manager (TSM), introduced with System 7.1 to help applications communicate with utilities that provide text services. Making your application TSM-aware, an easy matter if you're using TextEdit and TSMTE, will enable it to use the services of utilities designed to handle text input in Chinese, Japanese, and Korean. Your application will also be poised to take advantage of the wide variety of text services that eventually will be supported by the Text Services Manager.

Localizing your application for Asian markets, or for Asian language-speaking customers in the United States, may seem like a daunting task to you, but take heart: the Text Services Manager (TSM) makes one aspect of localization, handling keyboard input, easier than you might imagine. Part of the WorldScript technology in the Macintosh Toolbox, the Text Services Manager enables applications and text service utilities to communicate without knowing anything about each other's internal structures or identities. When you make your application TSM-aware, you make it possible for your Asian language-speaking customers to use your application in concert with a utility program that does the necessary conversion of keyboard input.

This article shows you how to modify your TextEdit-based application to make it TSM-aware -- that is, so that it makes the appropriate calls to the Text Services Manager. It doesn't take a lot of modifications, as you'll see from the sample application (called InlineInputSample) that accompanies this article on this issue's CD and develop's Web site. Our application uses TSMTE, an extension that's shipped with the system), which extends TextEdit to handle the details of TSM awareness with minimal effort on the part of application writers. Using TSMTE should be sufficient for most applications; however, for intensive text-processing applications or applications using a different text-editing engine, you may need to handle all TSM processing yourself.

Before we look at the changes you need to make to your application to make it TSM-aware, I'll briefly explain how keyboard input works for Chinese, Japanese, and Korean. If you'd like to read more about common problems of localization, see "Writing Localizable Applications" in develop Issue 14. For details on the Text Services Manager, consult Chapter 7 of Inside Macintosh: Text.

ASIAN LANGUAGES AND KEYBOARD INPUT

As you can guess, supporting keyboard input for Asian languages isn't the same as handling English, because they're written in different scripts. A script is a writing system that can be used to represent one or more human languages.

English and other European languages are written in the Roman script, which is an alphabetic script. In alphabetic scripts, the various characters of the script are combined in different ways to form words. Alphabetic scripts have a small repertoire of characters compared to other types of writing systems. It's a simple matter to represent all the characters in an alphabetic script on a keyboard. Because there are fewer than 256 characters in such scripts, it takes only one byte to uniquely identify each character, so these scripts are known as 1-byte scripts.

Asian languages are quite different, being written in scripts that include ideographic characters borrowed from ancient China. An ideograph is a symbolic character that usually represents a single concept, action, or thing. Figure 1 shows some examples of Japanese and simplified Chinese ideographs. Because each character represents a single concept, there are -- by necessity -- many, many more characters than in the Roman script. Most literate Chinese speakers know around 5000 ideographs, and a literate Japanese knows around 3000 ideographs. Two bytes are required to uniquely identify each character in an ideographic script, and thus these scripts are known as 2-byte scripts. Chinese, Japanese, and Korean also incorporate alternative script systems based on syllabic or phonetic characters (characters that represent certain sounds).

Figure 1. Some Japanese and Chinese ideographs and their English translations

INPUT METHODS

How is it possible for users of 2-byte script systems to get by with a standard Macintosh keyboard? Obviously, they can't simply press the key corresponding to the one character they want out of 3000 or 5000 characters. Enter the text service utility known as an input method or a front-end processor (FEP). An input method allows users to type phonetic or syllabic characters on a standard keyboard and automatically converts what they type into ideographic representations.

For Chinese speakers, the appropriate input method converts keyboard input from Pinyin (Roman) or Zhuyinfuhao (phonetic, also known colloquially as Bopomofo) to ideographic Hanzi. For Japanese speakers, the input method converts input from phonetic Katakana or Hiragana into ideographic Kanji, as illustrated by the example in Figure 2. The input method for Korean speakers converts phonetic Jamo into nonideographic Hangul (complex clusters of Jamo).

Figure 2. The same sentence as entered in Hiragana and as converted to Kanji

Apple currently ships four 2-byte keyboard input methods: Kotoeri (Japanese), Power Input Method (Korean), Traditional Chinese (as used in Taiwan), and Simplified Chinese (as used in the People's Republic of China). The same input methods are shipped with the Apple Language Kits, and third-party input methods are also available.

Regardless of the language, all input methods have a similar user interface. When more than one script is installed on the Mac OS, as is the case for localized systems since all systems have the Roman script installed, the Keyboard menu becomes available in the menu bar. Each available keyboard layout and input method is listed in the Keyboard menu; the icon for the active keyboard layout or input method appears as the menu's title in the menu bar. Figure 3 shows a Keyboard menu displaying items for Apple's Simplified Chinese and Kotoeri (Japanese) input methods, as well as keyboard layouts from some other script systems. The Simplified Chinese input method is active; it's checked in the menu and its icon appears highlighted in the menu bar. The pencil icon in the menu bar is displayed only when an input method is active (in other words, not when the user is typing in English or another language that doesn't require an input method); it's the title for the menu belonging to that input method. Some input methods use a different icon, but it appears in the same place as the pencil icon.

Figure 3. Input method icons in the Keyboard menu and the menu bar

BOTTOMLINE VS. INLINE INPUT

When the user begins typing, the raw text appears on the screen as entered, either in a floating input window that's usually displayed in the lower portion of the screen or in the application window where the text is intended to appear. The first style of text entry is known as bottomline input, while the second is called inline input (see Figure 4). Applications that aren't TSM-aware can make indirect use of the Text Services Manager's floating window service to enable bottomline input (as explained on page 7-13 of Inside Macintosh: Text), but users generally prefer inline input, which only TSM-aware applications can offer. TSM-aware applications can also offer bottomline input, which users may prefer if the size of the text displayed in the document makes reading the characters difficult.

Bottomline input

Inline input

Figure 4. Bottomline vs. inline input

In the case of inline input, the just-entered text appears in what is known as the active input area or inline hole. Text in the active input area or the floating input window is underlined in gray or highlighted in some other manner, depending on the application.

With either bottomline or inline input, the raw text is converted from its phonetic or syllabic representation to ideographic or complex syllabic characters, and the gray underline (if there is one) turns to black or changes in some other manner determined by the application, when the user gives a signal such as pressing the space bar after entering a sequence of characters. There may be more than one possible reading of a given character sequence, in which case the input method will display a list of candidates in a candidate window, as shown in Figure 5. When the user selects one of the candidate readings, the raw text is converted.

Figure 5. Selecting a conversion option for inline input in a candidate window

The user then confirms the converted text, generally by pressing Return. (In Korean, conversion happens continuously and automatically, and the text is confirmed when the user presses either Return or the space bar.) In the case of bottomline input, the confirmed text is flushed from the input window and sent to the application as key-down events. For inline input, the confirmed text is copied into the application's text buffer (as shown in Figure 5) and the active input area is closed. When the user begins typing again, the underline beneath the confirmed text disappears entirely and a new active input area opens.

Before you start feeling overwhelmed by all this, realize that most of the user interface elements I've just described are handled by the input method or TSMTE and not your application. The input method takes all the keystrokes and processes them; your application simply draws the input method's text buffer in the application window. All you need to do to get the benefit of this kind of text service is to make a few modifications to your application. Once your application is TSM-aware, you can work with any input method regardless of language and thus offer your Asian language-speaking customers the convenience of inline input.

MAKING YOUR APPLICATION TSM-AWARE

Making your application TSM-aware is a matter of adding calls to send information to input methods by way of the Text Services Manager. Most of the popular text-editing engines for the Mac OS other than TextEdit are already TSM-aware. One of these, WASTE (the WorldScript-Aware Styled Text Engine, developed by Marco Piovanelli), makes all but four of the necessary calls: InitTSMAwareApplication, CloseTSMAwareApplication, TSMEvent, and SetTSMCursor. These calls need to be made by the application. Optionally, a WASTE-based application can install pre- and post-TSM-update callback routines. If you use WASTE for your text-editing engine, most of the techniques described in this section apply. The WASTE source code is available online at many popular Macintosh ftp sites; I highly recommend looking at it for examples of how to handle the TSM protocol directly.

Using TSMTE, as our application InlineInputSample does, you can make your TextEdit-based application TSM-aware with a few modifications to your event-handling, cursor-handling, window, and menu code. Most of the changes are quite simple and limited to particular subroutines of the application, as demonstrated by InlineInputSample. Our application is a version of TESample, a program written by Apple's Developer Technical Support group and provided with many development environments as part of the example code (it's also on this issue's CD). The code that makes our version of the program TSM-aware is conditionalized with qInline conditionals so that you can easily pick it out. You might want to take a look at that code as you read this section.

    To see the full capabilities of the InlineInputSample application, you need a Macintosh with System 7.1 or later localized for Chinese, Japanese, or Korean, or with one or more of the Asian language kits installed.*

TESTING FOR THE TEXT SERVICES MANAGER AND TSMTE

Before using the Text Services Manager and TSMTE, we need to check and see if they're available. The Text Services Manager is available on all versions of the system after 7.1. However, TSMTE ships only with localized versions of the system and with the Apple Language Kits for Chinese, Japanese, and Korean. The support for inline input discussed in this article will be active only while you're using one of these languages. Listing 1 shows the code we use to check for availability of the Text Services Manager and TSMTE. If we were writing our own protocol handlers, we would eliminate the gestaltTSMTEAttr test.


Listing 1. Testing for TSM and TSMTE availability

static void CheckForTextServices(void)
{
   long  gestaltResponse;

   gHasTextServices = false;     // unless proven otherwise
   gHasTSMTE = false;            // unless proven otherwise
    
   if (TrapAvailable(_Gestalt)) {
      if ((Gestalt(gestaltTSMgrVersion, &gestaltResponse) == noErr)
            && (gestaltResponse >= 1)) {
         gHasTextServices = true;
         if (Gestalt(gestaltTSMTEAttr, &gestaltResponse) == noErr)
            gHasTSMTE = BTst(gestaltResponse, gestaltTSMTEPresent);
      }
   }
}

The selector gestaltTSMgrVersion returns the version number of the Text Services Manager if it's installed. You should test to make sure that the version is greater than or equal to 1, the current version of the Text Services Manager. This will allow your application to work with future TSM versions as well.

INITIALIZING THE APPLICATION

Once we've established that the Text Services Manager and TSMTE are available, we need to extend our Toolbox initialization sequence to initialize the Text Services Manager. This is done by calling InitTSMAwareApplication. We also want to store the current state of the Script Manager's smFontForce variable (the font force flag) and set it to false while our application is running. This flag ensures the correct text-handling behavior in applications that don't use the Script Manager. Since we're using the Script Manager to support text in different languages, we should turn this off, as shown in Listing 2.


Listing 2. Initializing as a TSM-aware application

if (!(gHasTSMTE && InitTSMAwareApplication() == noErr)) {
   // If this happens, just move on without text services.
   gHasTextServices = false;
   gHasTSMTE = false;
}
// Get global font force flag; make sure it's off whenever we run. 
// Do this even if text services don't exist.
gSavedFontForce = GetScriptManagerVariable(smFontForce);
(void) SetScriptManagerVariable(smFontForce, 0);

Of course, since we do this work at initialization, we need to clean up when our application quits. In our termination routine, we restore the value of the font force flag and call CloseTSMAwareApplication. The font force flag also needs to be restored anytime control passes from the application to the system when we're dealing with fonts and such; it particularly should be restored in the case of a suspend event.

EXTENDING THE DOCUMENT STRUCTURE

Now we need to extend our document record to store the additional data structures related to TSM awareness. Our application's original DocumentRecord data structure is extended to include two additional fields, as follows:
typedef struct {
   WindowRecord   docWindow;
   TEHandle       docTE;
   ControlHandle  docVScroll;
   ControlHandle  docHScroll;
   TEClickLoopUPP docClick;
   Boolean        modified;
   TSMTERecHandle docTSMTERecHandle;   // added
   TSMDocumentID  docTSMDoc;           // added
} DocumentRecord, *DocumentPeek;

The TSMTERecHandle is used by TSMTE to maintain the data it uses. The TSMDocumentID identifies a TSM document, which is an opaque data structure used by the Text Services Manager to maintain the current status of the input methods in use. Generally, one TSM document (defined by the TSMDocument data type) is allocated per application window, but some applications may allocate a single global TSM document. Since the TSM document maintains context/state information about the current input method, you should customize allocation of the TSM document for your application's text-handling behavior.

Each TSM document also maintains a reference constant, which can be set by the application. Applications using TSMTE must stuff the TSMTERecHandle into the refCon; if you're creating your own handlers, the refCon can be customized to suit the needs of your application.

CREATING AND DELETING A TSM DOCUMENT

When creating a user document, we need to set up the TSM document and the TSMTERecHandle correctly, as illustrated in Listing 3. We pass four parameters to NewTSMDocument. The first parameter indicates the version of the TSM protocol that we're using; currently, the only defined protocol version is 1. The next parameter, supportedInterfaces, is an array of OSTypes that the Text Services Manager uses to find components that support the service the client is interested in. For our application, we set supportedInterfaces[0] to kTSMTEInterfaceType, indicating that we're using TSMTE support. Other applications providing full TSM support will want to set supportedInterfaces[0] to kTextService. Currently these are the only defined interface types. The final two parameters are a pointer to the TSMDocumentID storage and a pointer to our TSM refCon (in this case the TSMTERecHandle).


Listing 3. Creating a TSM document

if (good && gHasTSMTE) {
   supportedInterfaces[0] = kTSMTEInterfaceType;
   if (NewTSMDocument(1, supportedInterfaces, &doc->docTSMDoc,
            (long) &doc->docTSMTERecHandle) == noErr) {
      TSMTERecPtr tsmteRecPtr = *(doc->docTSMTERecHandle);
      tsmteRecPtr->textH = doc->docTE;
      tsmteRecPtr->preUpdateProc = gTSMTEPreUpdateUPP;
      tsmteRecPtr->postUpdateProc = gTSMTEPostUpdateUPP;
      tsmteRecPtr->updateFlag = kTSMTEAutoScroll;
      tsmteRecPtr->refCon = (long) window;
   } 
   else
      good = false;
}

Once we've allocated the TSM document, we need to set up the TSMTERecHandle. We set the TextEdit record for the handle and install UniversalProcPtrs for the pre- and post-update handlers. These handlers are called before and after TSMTE handles the update event. The pre-update handler in our sample application works around a bug in TSMTE version 1.0, and the post-update handler adjusts the scroll bar to bring the new text into view. We also set the updateFlag and the refCon.

Obviously, since we allocate certain structures when we create our TSM document, we need to deallocate those structures before we destroy the TSM document (that is, when we close the window). Listing 4 shows how to handle deleting a TSM document.


Listing 4. Deleting a TSM document

if (theDocument->docTSMDoc != nil) {
   (void) FixTSMDocument(theDocument->docTSMDoc);
   // DeleteTSMDocument might cause a crash if we don't deactivate
   // first, so...
   (void) DeactivateTSMDocument(theDocument->docTSMDoc);
   (void) DeleteTSMDocument(theDocument->docTSMDoc);
}

The FixTSMDocument call causes the Text Services Manager to confirm the text in the active input area and enter it into the user document. In a real application you'd then give the user the opportunity to save the user document before deleting the TSM document and closing the window, but we skip that step here. After "fixing" the document, we call DeactivateTSMDocument and then DeleteTSMDocument. We need to deactivate the document before deleting it because in certain circumstances DeleteTSMDocument may crash if we call it on an active document.

MODIFYING THE EVENT LOOP

Making your application TSM-aware with TSMTE requires very little modification to your existing event loop code. First we need to give the Text Services Manager an opportunity to handle events that might actually be for an input method and not our application. This is accomplished by calling TSMEvent and passing in the EventRecord returned from either WaitNextEvent or GetNextEvent. In our sample application, we wrap the call to TSMEvent in the IntlTSMEvent subroutine, as shown in Listing 5, to work around a bug that could cause the port to be set to the wrong window. Listing 6 shows how we modified the application's event loop to call TSMEvent before handling an event.


Listing 5. The IntlTSMEvent subroutine

static Boolean IntlTSMEvent(EventRecord *event)
{
   short        oldFont;
   ScriptCode   keyboardScript;
    
   // Make sure we have a port and it's not the Window Manager port.
   if (qd.thePort != nil && FrontWindow() != nil) {
      oldFont = qd.thePort->txFont;
      keyboardScript = GetScriptManagerVariable(smKeyScript);
      if (FontToScript(oldFont) != keyboardScript)
         TextFont(GetScriptVariable(keyboardScript,
             smScriptAppFond));
   }
   return TSMEvent(event);
}

Listing 6. The application's event loop

void EventLoop(void)
{
   RgnHandle   cursorRgn;
   Boolean     gotEvent, handledByTSM;
   EventRecord event;
   Point       mouse;

   cursorRgn = NewRgn();
   while (!gQuitting) {
      // Set global font force flag so other apps don't get confused.
      (void) SetScriptManagerVariable(smFontForce, gSavedFontForce);
        
      if (gHasWaitNextEvent) {
         GetGlobalMouse(&mouse);
         AdjustCursor(mouse, cursorRgn);
         gotEvent = WaitNextEvent(everyEvent, &event, GetSleep(),
                     cursorRgn);
      }
      else {
         SystemTask();
         gotEvent = GetNextEvent(everyEvent, &event);
      }

      // Clear font force flag again so it doesn't upset our
      // operations.
      gSavedFontForce = GetScriptManagerVariable(smFontForce);
      (void) SetScriptManagerVariable(smFontForce, 0);
        
      if (gHasTextServices) {
         handledByTSM = IntlTSMEvent(&event);
         if (!handledByTSM && gotEvent) {
            AdjustCursor(event.where, cursorRgn);
            DoEvent(&event);
         }
         else
            DoIdle();
      }
      else {
         if (gotEvent) {
            AdjustCursor(event.where, cursorRgn);
            DoEvent(&event);
         }
         else
            DoIdle();
      }
   }
}

Next, input methods must be given a chance to handle mouse events for the pencil menu. Whenever the user presses the mouse button in the menu bar, we need to pass the menu selection to the Text Services Manager and see if it's a system menu before we try to handle it as an application menu. We modify the subroutine for handling mouse-down events as shown in Listing 7.


Listing 7. Checking the menu selection in the mouse-down event handling

case inMenuBar:       // Process a mouse-down in menu bar (if any).
   AdjustMenus();
   menuResult = MenuSelect(event->where);
   if (!(gHasTextServices && TSMMenuSelect(menuResult)))
      DoMenuCommand(menuResult);
   HiliteMenu(0);     // Needed even if TSM or Script Manager handles
                      // the menu.
   break;

After calling our subroutine to adjust the menus so that the invalid items are dimmed, we pass the menu selection to the Text Services Manager. We call TSMMenuSelect with the menu result as a parameter. If the selection is in the pencil menu, the Text Services Manager will handle it for your application and return true; otherwise, it will return false and your application should handle the selection normally. Regardless of the results of TSMMenuSelect, your application needs to call HiliteMenu(0) to finish handling the selection.

The next step in handling a menu selection is to confirm the text in the active input area with a call to FixTSMDocument before performing the menu action. This is recommended in the current Macintosh Human Interface Guidelines. But this guideline is somewhat contested, so if you don't think it makes sense for your application, you might consider a more selective policy for automatically confirming inline input. Whatever you decide, remember to be consistent and try it out on real users.

Now that we've finished modifying our menu-handling code, we'll move on to modifying our window event handler, as shown in Listing 8. We need to make sure that the active TSM document is changed when necessary. Assuming that we're allocating one TSM document per user document or window, we also need to handle window activate and deactivate events differently. When we receive a deactivate event, we need to call DeactivateTSMDocument on the TSM document associated with that window. Similarly, we need to call ActivateTSMDocument when we receive an activate event for our window.


Listing 8. Handling window events

void DoActivate(WindowPtr window, Boolean becomingActive)
{
   RgnHandle      tempRgn, clipRgn;
   Rect           growRect;
   DocumentPeek   doc;
    
   if (IsDocumentWindow(window)) {
      doc = (DocumentPeek) window;
      if (becomingActive) {
         ...    // TextEdit-handling code
         if (doc->docTSMDoc != nil)
            (void) ActivateTSMDocument(doc->docTSMDoc);
      }
      else {
         if (doc->docTSMDoc != nil)
            (void) DeactivateTSMDocument(doc->docTSMDoc);
         ...    // TextEdit-handling code
      }
   }
}

If you use your own scheme for allocating TSM documents, be sure to call ActivateTSMDocument and DeactivateTSMDocument when appropriate. If you don't activate TSM documents correctly, the system can get confused and revert to Roman, in which case the user may click on a run of 2-byte text and not get inline input. If you're debugging your program and this happens, check to see what the current keyboard script is by calling

keyScript = GetScriptMgrVariable(keyScript);
If the keyboard script is smRoman, the problem could be related to activating and deactivating TSM documents.

We finish up our event loop modifications by ensuring that our application handles mouse-moved events in a way that works with the Text Services Manager and input methods. Input methods need to track mouse-moved events within the content area of your application, because when the user moves the cursor over an active input area, the input method needs to change the cursor's shape. This is demonstrated in the first half of Listing 9. Before attempting to change the cursor's appearance, your application should call SetTSMCursor, which returns a Boolean indicating whether the input method has already changed the cursor's appearance.


Listing 9. Allowing the input method to change the cursor

// Before we commit to anything, let's check whether some text
// service has a different idea.
if (!(gHasTextServices && SetTSMCursor(mouse))) {
   // Change the cursor and the region parameter.
   if (PtInRgn(mouse, iBeamRgn)) {
      SetCursor(*GetCursor(iBeamCursor));
      CopyRgn(iBeamRgn, region);
   }
   else {
      SetCursor(&qd.arrow);
      CopyRgn(arrowRgn, region);
   }
}
// No matter how nice the region, with text services it can't be
// bigger than a point. Yes, this defeats the purpose of all the
// calculations.
if (gHasTextServices)
   SetRectRgn(region, mouse.h, mouse.v, mouse.h, mouse.v);

Now we need to set up the correct mouseRgn parameter to WaitNextEvent. To work correctly with input methods, our application should create a mouseRgn that's no larger than a point, as shown in the second half of Listing 9. If we don't set up this region correctly, the input method may not be able to interact with our users as they would expect. Yes, being forced to use a point-sized region sort of defeats the purpose of a mouseRgn. We're working on extending the Text Services Manager so that you can obtain the region that the input method is interested in, but for now you'll just have to live with this limitation.

ADDING FONT-KEYBOARD SYNCHRONIZATION

Both TextEdit and WASTE automatically perform font-keyboard synchronization, meaning that they adjust the Keyboard menu so that the current keyboard layout or input method reflects the user's font selection. For instance, if the user selects Chicago or Courier (Roman fonts) from the Font menu, the application sets the current keyboard to a Roman keyboard layout (U.S., German, Italian, or whatever the default Roman keyboard is, according to the localizer). Similarly, if the user selects Osaka or HonMincho (Japanese fonts), the keyboard is synchronized with the font selection.

If you're not using TextEdit or WASTE, you can add the code in Listing 10 to provide font-keyboard synchronization. Using Toolbox routines, we determine the script of the font from the font ID. Then we call KeyScript, which changes the Keyboard menu settings to the default keyboard and input method combination for the new script.


Listing 10. Synchronizing the keyboard with the font selection

case mFont:
   GetMenuItemText(GetMenuHandle(mFont), menuItem, theFontName);
   GetFNum(theFontName, &theFontID);
   theTextStyle.tsFont = theFontID;
   TESetStyle(doFont, &theTextStyle, true, te);
   if ((*te)->selEnd - (*te)->selStart > 0)
      theDocument->modified = true;
   AdjustScrollbars(window, false);
   theScript = FontToScript(theFontID);
   KeyScript(theScript);
   break;

Font-keyboard synchronization is another one of those contested international human interface issues. Japanese users tend to be very divided on the issue, since this feature makes it difficult to set Roman characters to the Osaka font (the workaround is to select the Roman mode within the input method after selecting the Osaka font); however, users working in most other 2-byte languages like font-keyboard synchronization. Again, the best idea is to try out this interface feature on several real users and get their impressions.

OTHER USER INTERFACE ISSUES

When you make your application TSM-aware, you may need to work around a couple of other user interface issues. One of them is implementing passwords. When the user is typing a password, you don't want an input method to come up, so you should change the current keyboard layout to the Roman default. This is accomplished similarly to font-keyboard synchronization, using the following code:
KeyScript(smRoman);                   // Switch to Roman. 
KeyScript(smKeyDisableKybdSwitch);    // Lock out keyboard switching.
... // Do your password stuff here.
KeyScript(smKeyEnableKeyboards);
KeyScript(smKeySwapScript);

If you're writing game software, in play mode the user can't or shouldn't be manipulating input with an input method. In this case, you should also change the current keyboard layout to Roman, and you might want to lock out keyboard switching. In certain other modes (such as the high score list), users do need the services of an input method, so you should restore the original keyboard layout.

Also, even though most users prefer inline input, some actually don't like it, or they prefer the bottomline style of input in certain situations. For example, it's difficult to distinguish Kanji characters at point sizes smaller than 12, so when the user is working on a document in a small font, looking at the raw input in a larger font in the floating input window may be desirable. You should provide a preference mechanism so that the user can select either inline or bottomline input. This is implemented by calling the TSM function UseInputWindow and then passing it the document ID and a Boolean indicating whether the user wants inline input.

TESTING YOUR APPLICATION

Once you've made your application TSM-aware, you'll want to test it with a variety of input methods, since not all of them interpret the TSM protocol in quite the same way. If you're fortunate enough to have testers who speak Chinese, Japanese, or Korean, you've got it made. But if you don't have anyone around who speaks these languages, it's still possible to test your application in English with an input method. For some suggestions on how non-Asian language speakers can successfully test your code, see "Testing Two-Byte Script Support."


    TESTING TWO-BYTE SCRIPT SUPPORT

    BY GREG ANDERSON

    I know what you're thinking: "Great, now I can add support for 2-byte scripts to my application. But I can't read Japanese or Chinese characters, so how am I supposed to test my code to make sure it does the right thing with 2-byte characters?"

    Good news: You don't have to learn Japanese or Chinese. Instead, you can test your code using the 2-byte Roman input mode provided by Kotoeri. That's right -- I said "2-byte Roman."

    Most of the characters in the ASCII character set are replicated in one section of the Japanese 2-byte character set; you'll find the numbers and letters around $8250 to $829A. The 2-byte Roman characters look like their 1-byte counterparts, except that they're always monospaced and they take about twice as much space horizontally as the 1-byte characters do. These characters are very useful for testing 2-byte script support, because they look the same as the characters you use every day but they behave like other 2-byte characters such as Chinese and Japanese ideographs.

    Entering the 2-byte Roman characters is easy. After you've installed the Japanese Language Kit, choose Kotoeri from the Keyboard menu (shown earlier in Figure 3) and click the button labeled with the wide uppercase A in the operations palette, which will then look like this:

    Then just type Roman characters the same way you normally would. For example, if you want a Q, hold down the Shift key and press the Q key on the keyboard. You're now ready to edit 2-byte Roman characters in your application to make sure it handles them correctly. Here are some things to check:

    • Is the insertion point drawn in the right place, or are you using a Roman font to measure Japanese text?

    • If the insertion point is positioned after a 2-byte character and you press the Delete key, is the entire character deleted, or do you leave the first byte dangling in your document?

    • If you add a 2-byte uppercase B (which has an encoded value of $8261) to your document and use your Find command to search for a 1-byte lowercase a (which has an encoded value of $61), does your application find the 2-byte B? (It shouldn't, and it won't if you're using CharacterByteType correctly.)

    If these things work for you, you're well on your way to supporting 2-byte scripts in your application.


THE TSM PROTOCOL

Although TSMTE should provide enough support for most application developers who want to make their TextEdit-based applications TSM-aware, some developers may want or need to handle all the details themselves. This section provides a very brief overview of the TSM 1.0 protocol for the benefit of the latter.

The TSM protocol is based on the exchange of Apple events between the application and the input method, allowing them to share information about the active input area. The protocol consists of a suite of three required events (Position To Offset, Offset To Position, and Update Active Input Area) and an optional fourth event (Get Text).

THE POSITION TO OFFSET EVENT

The Position To Offset event is used to convert a global position into a meaningful offset in the document's text buffer. This event is sent from the input method to the application when the input method handles an event that occurs within the context of the application content. (Remember that you need to call TSMEvent to give the Text Services Manager a chance to handle mouse and keyboard events.)

The application must respond to this event by extracting a point on the screen from the Apple event and converting that point to an offset in the text of the particular document. In the TSM protocol, offsets are defined as long integers. The application returns the offset as a key in the reply event.

THE OFFSET TO POSITION EVENT

The Offset To Position event is sent by the input method when it needs to determine the global position of a particular document offset. When responding to this event, the application must return a global point corresponding to this offset. Optionally, the application can also return information about the typographical style and orientation (vertical vs. horizontal) of the text. Each of these elements is returned as a key in the reply event.

THE UPDATE ACTIVE INPUT AREA EVENT

The Update Active Input Area event is used by the input method to ask the application to update the active input area. The event contains an offset range array that breaks the updated text into particular ranges. The offset range is accompanied by a highlight range, which indicates how the application should highlight the particular range of text.

THE GET TEXT EVENT

Get Text is an optional event used only by Kotoeri, the Japanese input method, and some third-party Japanese input methods. It's documented in a March 1994 technical note by Takayuki Mizuno, available only in Japanese and roughly entitled "Kotoeri's Private Apple Event, Get Text." It's an extension to the TSM protocol developed by Apple as a way for an input method to retrieve text that has already been confirmed. Since most localized Japanese applications support this event, your users will probably expect it from your application as well.

TSMTE provides support for the Get Text event, so if you use the techniques in this article your application will be able to take advantage of this extension. The Get Text event is defined in Table 1. Listing 11 demonstrates how to handle the event directly.


Table 1. Definition of the Get Text event

Event classkTextServiceClass
Event IDkGetText (= 'gtxt')
Requested actionReturns the current selection as the return parameter
Keyword Descriptor type Data
Required parameters
keyDocumentRefcontypeLongIntegerStandard refCon parameter
keyAEServerInstancetypeComponentInstanceStandard component instance parameter
Optional parameters
keyAEBufferSize (= 'buff')typeLongInteger Maximum number of bytes the input method can receive
Return parameters
keyAETheDatatypeText The text specified by the current selection. The maximum byte length is specified by the keyAEBufferSize parameter. Any portion of the text that exceeds the buffer length shouldn't be returned.


Listing 11. Handling the Get Text event

pascal OSErr HandleGetText(const AppleEvent *theAppleEvent, 
                        const AppleEvent *reply, long handlerRefcon)
{
#pragma unused (handlerRefcon)

   OSErr               err;
   ComponentInstance   serverInstance;
   TSMTERecHandle      docRefcon;
   Handle              text;
   Size                textLen;
    
   // Identify event and get document refCon and server instance.
   err = IdentifyTSMCallback(theAppleEvent, &docRefcon, 
                              &serverInstance);
   if (err) return err;
    
   // Get selected text from document.
   HLock((Handle) docRefcon);
   err = DoGetText(*docRefcon, serverInstance, &text, &textLen);
   HUnlock((Handle) docRefcon);
   if (err) return err;
   // Add selected text as return parameter.
   HLock(text);
   err = AEPutParamPtr(reply, keyAETheData, typeText, (Ptr) *text,
                        textLen);
   DisposeHandle(text);

   return err;
}
OSErr DoGetText(TSMTERecPtr tsmteRecPtr, ComponentInstance 
                  serverInstance, Handle *text, Size *textLen)
                  
{
#pragma unused (serverInstance)

   TEHandle hTE;
   short      selStart, selEnd;
    
   hTE = tsmteRecPtr->textH;
   selStart = (*hTE)->selStart;
   selEnd  = (*hTE)->selEnd;
   *textLen = selEnd - selStart;
   *text = NewHandleClear(*textLen);
   HLock((Handle) *text);
   BlockMove((Ptr) (*((*hTE)->hText) + selStart), (Ptr) (**text),
               *textLen);
   HUnlock((Handle) *text);
   return noErr;
}

TSM NOW AND FOREVER

Although the changes required to make your TextEdit-based application TSM-aware are small, they dramatically overhaul the experience available to Asian language-speaking users. Try compiling our sample application both with and without the inline support flag set so that you can see the difference it makes to users. Even if you don't have plans to ship your application localized for Chinese, Japanese, or Korean, making it TSM-aware will please your users who have an Apple Language Kit installed and want to use your application with their non-English data.

Besides having an immediate payoff, the work you do to make your application TSM-aware will have a future payoff as well. While version 1.0 of the Text Services Manager offers support solely for keyboard input methods, future versions will be part of the framework for supporting handwriting and speech/dictation input methods as well as more general text services such as interactive spelling checkers and intelligent document scanners. By making your application TSM-aware now, you'll be poised to take advantage of the wide variety of services that will be available with TSM 2.0.


    RELATED READING

    • "Writing Localizable Applications" by Joseph Ternasky and Bryan K. "Beaker" Ressler, develop Issue 14.

    • Guide to Macintosh Software Localization by Apple Computer, Inc. (Addison-Wesley, 1992).

    • Inside Macintosh: Text by Apple Computer, Inc. (Addison-Wesley, 1993), Chapter 7, "Text Services Manager."

    • Technotes TE 27, "Inline Input for TextEdit With TSMTE," and OV 20, "Internationalization Checklist."

    • Understanding Japanese Information Processing by Ken Lunde (O'Reilly & Associates, 1993).

    • Writing Systems of the World by Akira Nakanishi (English edition, Charles E. Tuttle, 1980).

    • IDRIS scripts, http://idris.com/scripts/Scripts.html.


TAGUE GRIFFITH (tague@apple.com) has appeared on stage with several famous rock bands and would like to marry a rock star when he grows up. In his spare time, Tague works in Apple's Text and International Engineering group. If anyone out there knows Courtney Love's e-mail address, please send it to Tague.*

Thanks to our technical reviewers David Bice, Deborah Grits, Osman Güracar, John Harvey, and Yasuo Kida.*

 
AAPL
$98.38
Apple Inc.
-0.64
MSFT
$43.89
Microsoft Corpora
-0.09
GOOG
$585.61
Google Inc.
-4.99

MacTech Search:
Community Search:

Software Updates via MacUpdate

Drive Genius 3.2.4 - Powerful system uti...
Drive Genius is an OS X utility designed to provide unsurpassed storage management. Featuring an easy-to-use interface, Drive Genius is packed with powerful tools such as a drive optimizer, a... Read more
Vitamin-R 2.15 - Personal productivity t...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
Toast Titanium 12.0 - The ultimate media...
Toast Titanium goes way beyond the very basic burning in the Mac OS and iLife software, and sets the standard for burning CDs, DVDs, and now Blu-ray discs on the Mac. Create superior sounding audio... Read more
OS X Yosemite Wallpaper 1.0 - Desktop im...
OS X Yosemite Wallpaper is the gorgeous new background image for Apple's upcoming OS X 10.10 Yosemite. This wallpaper is available for all screen resolutions with a source file that measures 5,418... Read more
Acorn 4.4 - Bitmap image editor. (Demo)
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Bartender 1.2.20 - Organize your menu ba...
Bartender lets you organize your menu bar apps. Features: Lets you tidy your menu bar apps how you want. See your menu bar apps when you want. Hide the apps you need to run, but do not need to... Read more
TotalFinder 1.6.2 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Tab-based... Read more
Vienna 3.0.0 RC 2 :be5265e: - RSS and At...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
VLC Media Player 2.1.5 - Popular multime...
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
Default Folder X 4.6.7 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click... Read more

Latest Forum Discussions

See All

Note Review
Note Review By Jennifer Allen on July 29th, 2014 Our Rating: :: TOO SIMPLEiPhone App - Designed for the iPhone, compatible with the iPad Note is a note taking app that’s a little too short on features to be worth its asking price... | Read more »
Chainsaw Warrior Goes on Sale & Ther...
Chainsaw Warrior Goes on Sale & There’s a Chance to Win a Copy of the Original Board Game Posted by Jennifer Allen on July 29th, 2014 [ permalink | Read more »
It Came From Canada: Tiny Tower Vegas
If you go to a casino, you might make a lot of money. If you run a casino, you’re guaranteed to make a lot of money. The choice seems pretty obvious. So while waiting for your shady real estate deals to move forward, get prepared with Tiny Tower... | Read more »
Z Hunter Review
Z Hunter Review By Lee Hamlet on July 29th, 2014 Our Rating: :: RIGHT ON TARGETUniversal App - Designed for iPhone and iPad While it might not necessarily break new ground, Z Hunter has enough tricks up its sleeve to ensure that... | Read more »
Huge Update Comes To Duet, Adding 48 New...
Huge Update Comes To Duet, Adding 48 New Stages Posted by Jennifer Allen on July 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Sharknado: The Video Game Available Now....
Sharknado: The Video Game Available Now. Seriously. Posted by Rob Rich on July 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Frog Orbs 2 Review
Frog Orbs 2 Review By Nadia Oxford on July 29th, 2014 Our Rating: :: THIS MAGIC IS A TAD MONOTONOUS Universal App - Designed for iPhone and iPad Frog Orbs 2 is repetitive, but younger players should enjoy it nonetheless.   | Read more »
Puzzix Review
Puzzix Review By Jennifer Allen on July 29th, 2014 Our Rating: :: NICE IDEAUniversal App - Designed for iPhone and iPad A little like Tetris, Puzzix is all about piecing together blocks and watching them vanish. It could do with... | Read more »
Cannonball eMail is Now Live – Works Wit...
Cannonball eMail is Now Live – Works With Gmail, Yahoo, Outlook, Hotmail, and AOL Posted by Jessica Fisher on July 29th, 2014 [ permalink ] | Read more »
To The End Review
To The End Review By Lee Hamlet on July 29th, 2014 Our Rating: :: A VICIOUS CYCLEUniversal App - Designed for iPhone and iPad To The End will test players’ patience, timing, and dedication as they try to navigate all 13 levels in... | Read more »

Price Scanner via MacPrices.net

Updated MacBook Pro Price Trackers
We’ve updated our MacBook Pro Price Trackers with the latest information on prices, bundles, and availability on the new 2014 models from Apple’s authorized internet/catalog resellers as well as... Read more
Apple updates MacBook Pros with slightly fast...
Apple updated 13″ and 15″ Retina MacBook Pros today with slightly faster Haswell processors. 13″ models now ship with 8GB of RAM standard, while 15″ MacBook Pros ship with 16GB across the board. Most... Read more
Apple drops price on 13″ 2.5GHz MacBook Pro b...
The Apple Store has dropped their price for the 13″ 2.5GHz MacBook Pro by $100 to $1099 including free shipping. Read more
Apple drops prices on refurbished 2013 MacBoo...
The Apple Store has dropped prices on Apple Certified Refurbished 13″ and 15″ 2013 MacBook Pros, with model now available starting at $929. Apple’s one-year warranty is standard, and shipping is free... Read more
iOS 8 and OS X 10.10 To Support DuckDuckGo As...
Writing for Quartz, Dan Frommer reports that Apple’s forthcoming iOS 8 and OS X 10.10 operating systems version updates will allow users to select DuckDuckGo as their default search engine. He notes... Read more
U.K. Hospital Using iPods and iPads To Record...
British news journal GazetteLive’s. Ian McNeal notes that the old “an apple a day keeps the doctor away” proverb is being turned on its head at http://southtees.nhs.uk/hospitals/james-cook/ James... Read more
13-inch 2.5GHz MacBook Pro on sale for $1099,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $1099.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $100 off MSRP. Price is... Read more
Roundup of Apple refurbished MacBook Pros, th...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available for up to $400 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. Their prices... Read more
Record Mac Shipments In Q2/14 Confound Analys...
A Seeking Alpha Trefis commentary notes that Apple’s fiscal Q3 2014 results released July 22, beat market predictions on earnings, although revenues were slightly lower than anticipated. Apple’s Mac’... Read more
Intel To Launch Core M Silicon For Use In Not...
Digitimes’ Monica Chen and Joseph Tsai, report that Intel will launch 14nm-based Core M series processors specifically for use in fanless notebook/tablet 2-in-1 models in Q4 2014, with many models to... Read more

Jobs Board

Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.