MacDevCenter.com: Mac Modding Shortcuts

Published on MacDevCenter (http://www.macdevcenter.com/)
See this if you're having trouble printing code examples

O'Reilly Book Excerpts: Modding Mac OS X

Mac Modding Shortcuts

by Erica Sadun

Adding Application Keyboard Shortcuts

The Keyboard Shortcuts preferences pane lets you associate a custom shortcut for any menu item in any or all of the applications on your Mac. This feature lets you add a new menu shortcut or override the original keyboard shortcut for a menu item. You can also add shortcuts to individual applications or globally to all applications, as described in the following section.

All application shortcuts in this chapter are case-sensitive. Always take care to match the case, spelling, spacing, and punctuation when defining a shortcut. Non-English-language readers: please note that you will need to adapt the instructions in this chapter to match the exact text on your system. For example, French-language readers do not use Secure Empty Trash. The menu item title is Vider la Corberille en mode sécurisé.

TOOLS YOU NEED

For working through the examples in this section, you’ll need the following applications:

System Preferences (/Applications)
Calculator (/Applications)
Terminal (/Applications/Utilities)
Character Palette (from the Finder)
Terminal (/Applications/Utilities)
TextEdit (/Applications)
Your favorite web browser, such as Safari (/Applications) or Microsoft’s Internet Explorer (/Applications)

Adding a Shortcut to an Application

Apple’s infinitely hackable Calculator (/Applications) offers no keyboard shortcut for turning speech recognition on or off. As Figure 8-5 shows, the two-item Speech menu has no keyboard shortcuts at all. In the following steps, you’ll use the Keyboard Shortcuts preferences to add a shortcut for the Speak Total menu option.

Figure 8-5. The default look for Calculator's Speech menu.

Quit Calculator with Apple-Q if it is running. You cannot correctly assign shortcuts when an application is active.
Open the Keyboard Shortcuts preferences pane.
Locate the small plus button (+) at the bottom-right of the Keyboard Shortcuts pane; it’s just above the “Turn on full keyboard access” checkbox. Click the + button; a dialog scrolls down out of the titlebar, as shown in Figure 8-6.
Select Calculator from the Application pop-up list.

Figure 8-6. Clicking the + button opens this dialog on top of the Keyboard Shortcuts pane.
Enter “Speak Total” into the poorly named Menu Title field. (This field actually holds the name of the menu item to be referred to, not the title of the entire menu.) Make sure to use the exact spelling, case, spacing, and punctuation to match the name of the menu item correctly. Do not add extra spaces at the end of the name.
Tab down to the Keyboard Shortcut field and type Option-T. Note that the same caveats about selecting legal shortcuts apply here as well as to the built-in shortcuts described earlier in this section. For example, Keyboard Shortcuts won’t let you set your shortcut to Apple-T, T, or Shift-T.
Click Add, as shown in Figure 8-7. The new keyboard shortcut appears as a new section under Application Keyboard Shortcuts, below All Applications.

Figure 8-7. Specifying the Application, Menu Title (really, the menu item), and Keyboard Shortcut.
Launch Calculator, open the Speech menu, and confirm that the new shortcut appears and works as expected. Figure 8-8 shows the updated menu after making the change.
In order to examine how your changes have affected the default settings for Calculator, it helps to search through your preferences. You can best do this by using the defaults utility, which runs from the command line. Start by launching the Terminal application (/Applications/Utilities).

Enter defaults read com.apple.calculator. This command requests a list of the defaults (preferences) from the com.apple.calculator property list file, which stores all the preferences used by Calculator. The new keyboard shortcut appears, associated with the NSUserKeyEquivalents key (highlighted in bold in the output).

Figure 8-8. The modified Speech menu. Speak Total now has a keyboard shortcut.

$ defaults read com.apple.calculator
    {
    NSUserKeyEquivalents = {“Speak Total” = “~T”; };
    "NSWindow Frame Calc_History_Window" = "419 344283 0 0 1024 
    746
    ";
    "NSWindow Frame Calc_Main_Window" = "113 459283 0 0 1024 746 
    ";
    PaperTapeVisibleDefaultsKey = 0;
    PrecisionDefaultsKey = 13;
    SpeaksButtonPressedDefaultsKey = 0;
    SpeaksTotalDefaultsKey = 0;
    ViewDefaultsKey = Basic;
    "dv com.apple.soundmgr._DV Sound Output Settings" = <7d000000
    >;
    }

Any item that returns from the defaults command will also appear in the actual preferences plist file associated with that domain. When opened in TextEdit, you’ll find the same updated preference. To see them, launch TextEdit and open ~/Library/Preferences/com.apple.calculator. plist.

<?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC “-//Apple Computer//DTD PLIST 1.0//EN”
    “http://www.apple.com/DTDs/PropertyList-1.0.dtd”>
    <plist version=”1.0”>
    <dict>
    <key>NSUserKeyEquivalents</key>
    <dict>
    <key>Speak Total</key>
    <string>~T</string>
    </dict>
    <key>NSWindow Frame Calc_History_Window</key>
    <string>419 344283 0 0 1024 746 </string>
    <key>NSWindow Frame Calc_Main_Window</key>
    <string>113 459283 0 0 1024 746 </string>
    <key>PaperTapeVisibleDefaultsKey</key>
    <false/>
    <key>PrecisionDefaultsKey</key>
    <integer>13</integer>
    <key>SpeaksButtonPressedDefaultsKey</key>
    <false/>
    <key>SpeaksTotalDefaultsKey</key>
    <false/>
    <key>ViewDefaultsKey</key>
    <string>Basic</string>
    <key>dv com.apple.soundmgr._DV Sound Output Settings</key>
    <data>
    fQAAAA==
    </data>
    </dict>
    </plist>

Editing Application Shortcuts

Use the following tricks to edit the application shortcuts in your Keyboard Shortcuts preferences pane:

To remove a shortcut: Select a shortcut or shortcuts and click the minus (–) button.
To rename the shortcut menu item: Click the menu item of any application shortcut; a text field appears. Edit the name as needed.
To change the shortcut: Click the keyboard equivalent in the shortcut column. When the text field appears, type a new equivalent.

Adding Shortcuts with Nonstandard Characters

As you may have noticed, some Mac OS X applications use an ellipsis (…) as part of their menu items. When you see an ellipsis tacked onto a menu item, it means that the item will open up another window in which you’ll have more work to do. Many of Calculator’s menus, for example, contain items that end with an ellipsis. Unfortunately, there are two ways that programmers can add an ellipsis to a menu item, and you have to take this into account when you define your keyboard shortcuts. Some programmers actually type in three dots, a triple repetition of the period (.) character. Other programmers use the Unicode ellipsis character, which is a single character that adds all three dots (...). It can be very hard to differentiate these visually, unless you know what you’re looking for.

Curiously enough (and rather conveniently, from the viewpoint of this technical author), Calculator 3.1 uses both approaches. If you launch Calculator and carefully look at the File and Convert menus, you’ll discover that the File menu uses three dots and the Convert menu uses an ellipsis, as shown in Figure 8-9. The dots are slightly heavier and spaced a little further apart than the ellipsis character. Convert menu uses the ellipsis character.

File menu uses 3 dots Figure 8-9. Version 3.1 of Apple's Calculator application uses both dots and the ellipsis character in its menus.

In the following steps, you’ll use the Keyboard Shortcuts preferences pane to set shortcuts for both types of ellipsis.

If you started up Calculator to check out the differences between the ellipses in the File and Convert menus, you’ll need to quit (c-Q) before going forward with this example.

WARNING
You should never modify an application that’s currently running. The application won’t recognize the changes until it relaunches, and it may overwrite the changes you’ve made by exporting its current set of preferences when the application quits.
Launch System Preferences by clicking on its icon in the Dock or by choosing a ? System Preferences.
Click on the icon for the International preferences panel; the International icon looks like the flag for the United Nations.
Click on the tab for the Input Menu; it is the rightmost of the three buttons near the top of the International pane.
Locate the Character Palette option and place a checkmark next to it. (The “Show input menu in menu bar” option at the bottom of the window automatically checks itself when the Character Palette is in use.) Checking this option lets you access the Character Palette from a Finder menu. The Input Menu, headed by the flag of your current localization settings, appears in the menu bar, as shown in Figure 8-10. You’ll need the Character Palette to type the Unicode ellipsis characters in as your keyboard shortcut.

Figure 8-10. Use the International preferences Input Menu pane to provide quick access to the Character Palette.
Choose View ? Show All Preferences (c-L) to return to System Preferences’ main display, which shows all of the available preferences panels.
Click on the icon for the Keyboard & Mouse preferences panel. When the Keyboard pane appears, click on the tab for the Keyboard Shortcuts pane.
Below the list of keyboard shortcuts, click on the plus sign (+) button; the Keyboard Shortcut specification dialog appears.
Click on the Application pop-up menu and select the Calculator application.
Enter “Page Setup…” in the Menu Title text field. There are three periods that follow “Setup” to form its ellipsis.
In the Keyboard Shortcut text field, hold down the Option key and press P to assign Option-P as the keyboard shortcut for “Page Setup…”.
Click on the Add button, as shown in Figure 8-11. The new shortcut appears in Application Keyboard Shortcuts under Calculator.

Figure 8-11. Adding a shortcut using three period characters.
Click on the + button again; a new Keyboard Shortcut dialog opens.
Select Calculator from the Application pop-up. (In all likelihood, after setting the Page Setup shortcut, the Application pop-up will default to Calculator.)
Type “Area” in the Menu Title text field. Leave the cursor where it is, to preserve the focus in the text field; we’re going to use the Character Palette to add the Unicode version of the ellipsis character after “Area”.
Click on the Input Menu in the menu bar, and select the Character Palette; the palette opens in a separate window.

Mac OS X’s Character Palette lets you add the full range of Unicode characters to your applications and documents. The Character Palette is indispensable when it comes to working with foreign languages and special fonts. To learn more, search for “typing special characters and symbols” in Mac Help. Choose Help -> Mac Help (Command-?) from the Finder.

In the Character Palette, choose Roman from the View pop-up at the top of the palette.
Beneath the View pop-up menu, you’ll see two tabbed panes: “by Category” and “Favorites.” Click on the “by Category” tab.
On the left side of the “by Category” view, select the Punctuation category. To the right of the category list appear the Unicode characters for various punctuation marks. In the top row, click on the ellipsis character (…). At the bottom of the Character Palette, you’ll see the ellipsis displayed in an array of fonts; don’t worry about this right now, but keep it in mind for when you might want or need a character in a different font.
At the bottom of the Character Palette, click on the Insert button, as shown in Figure 8-12. Mac OS X adds the ellipsis to the Menu Title text field. Close the Character Palette or move it out of the way.

Figure 8-12. The ellipsis character appears in the Punctuation set of the Roman character palette.
Tab down to the Keyboard Shortcut text field. Hold down the Option key and press A to assign Option-A as the keyboard shortcut.
Click the Add button. The new shortcut joins the list, as shown in Figure 8-13.

Figure 8-13. The shortcuts defined by these steps.
Return to the Applications folder and launch Calculator by double-clicking on its icon.
In Calculator, open the File and Convert menus to confirm that your keyboard shortcuts have been added correctly, as shown in Figure 8-14. Recall that the shortcuts will not appear unless the menu item text exactly matches the text you typed in the Keyboard Shortcuts preferences pane. Enter the shortcuts (Option-A and Option-P) to test that they work as expected.
Quit Calculator (c-Q).
Open a new Terminal window. You’ll use this new window to test how your actions affected the Calculator defaults.
Enter defaults read com.apple.calculator | grep UserKey. This command searches for Calculator’s keyboard shortcuts:
```
$ defaults read com.apple.calculator | grep UserKey
    NSUserKeyEquivalents = {"Area\\U2026" = "~A"; "Page Setup..."
= "~P"; "Speak Total" = "~T"; };
```
Figure 8-14. The updated Calculator replaces the File -> Save Tape As menu shortcut with Shift-Command-S and adds Option-A as the Convert -> Area shortcut.

As you can see, the Page Setup shortcut simply uses the three typed dots. In contrast, the Area shortcut uses the Unicode ellipsis character U2026. This code is found on the second page of the Unicode standard code charts (http://www.unicode.org/charts/charindex2.html; the list starts at http://www.unicode.org/charts/ charindex.html), as shown in Figure 8-15. Unicode escape sequences allow you to add and edit exotic equivalents via your keyboard without using Mac OS X’s Character Palette.

Figure 8-15. The Unicode site allows you to look up the Unicode equivalent for many common symbols.

You won’t see this spelled-out Unicode shortcut if you open Calculator’s plist file (~/Library/ Preferences/com.apple.calculator.plist) in TextEdit or Property List Editor, because TextEdit can read and display Unicode natively. As Figure 8-16 shows, the ellipsis looks like an ellipsis in TextEdit.

Figure 8-16. TextEdit is fully Unicode compliant and displays special symbols directly.
Return to the Keyboard Shortcuts preferences window.
Select the Calculator heading above the new shortcuts.
Click the minus (–) button to remove Calculator and its shortcuts from the Application Keyboard Shortcuts list. Be careful; you cannot undo this action.

WARNING
You might be tempted to define a keyboard shortcut in System Preferences and then modify the shortcut by editing the resulting application preferences file. Do NOT. System Preferences will overwrite your changes every time you log in, reverting the shortcuts to the ones stored in its database.

Adding Global Application Shortcuts

Keyboard shortcuts can apply to individual applications or across the board to every application on the system. When you choose a particular application, as you did in the previous example, the shortcut affects only the domain that you specify; you selected Calculator, and the shortcuts were then mapped to that application only. The Keyboard Shortcut preferences also allow you to define shortcuts for All Applications. When you do this, the keyboard shortcut is added to the global domain (also called the NSGlobalDomain), defining a shortcut that affects all matching menu items in all applications. The following example shows you how to create a global shortcut.

Launch the System Preferences application by clicking on its icon in the Dock or by choosing a ? System Preferences.
Click on the Keyboard & Mouse preferences panel and then go to the Keyboard Shortcuts pane.
Look at System Preferences’ Edit menu, and confirm that the Clear option doesn’t have a keyboard shortcut.

Figure 8-17. Adding a global keyboard shortcut.

Back in the Keyboard Shortcuts pane, click on the plus-sign (+) button to add a new shortcut.
Set the Application pop-up menu to All Applications.
Enter “Clear” in the Menu Title text field, and then assign Control-X (^X) as the shortcut in the Keyboard Shortcut field.
Click Add (Figure 8-17). The new Clear shortcut appears under Application Keyboard Shortcuts ? All Applications.
Close the System Preferences window (c-W), and then launch System Preferences again by clicking on its icon in the Dock or choosing a ? System Preferences.
Look at the System Preferences Edit menu; you’ll see that the Clear option now includes the ^-X keyboard shortcut. Launch another Mac OS X application (such as Excel) and look at the Edit menu to confirm that the keyboard shortcut for the Clear option was applied globally.
Launch Terminal and start a new shell. Enter the following defaults command. This command reads all the preferences from the global domain and searches for any keys that include UserKey.
```
$ defaults read NSGlobalDomain | grep UserKey 
    NSUserKeyEquivalents = {Clear = "^X"; };
```
Instead of typing out NSGlobalDomain, you can use the defaults -g flag; for example, try using defaults read -g | grep UserKey.
Return to System Preferences and to the Keyboard Shortcuts preferences pane.
Select the Clear shortcut and click on the minus (–) button to remove the shortcut.

Erica Sadun has written, co-written, and contributed to almost two dozen books about technology, particularly in the areas of programming, digital video, and digital photography.

Return to MacDevCenter.com.