Customizing the Cocoa Text System
87 | 88 |Version 0.8
89 | by Jacob Rus
90 | Monday, 20 March 2006
Apple’s Cocoa text system is a complicated beast, but also extremely flexible, 93 | and with a bit of work, it can be molded to match many working styles. This 94 | how-to covers the 2 major ways of customizing the text input system: Default 95 | key bindings, and for still more control, input managers.
96 | 97 |I’m writing this guide because nothing like it currently exists. There is 98 | incredible room for flexibility in customizing the Cocoa text environment, but 99 | most users—even power-users—have no idea of the available options. This is 100 | mostly because Apple’s documentation is 1) aimed at developers, and 2) often 101 | incomplete or ambiguous. Most users have no idea that they can look at a file 102 | which describes all of the shortcuts on the system, and that they can easily 103 | add their own shortcuts, or replace existing ones with differing 104 | functionality.
105 | 106 |For instance, one of the most common complaints from new Windows and 107 | Linux/Unix switchers is that many of the shortcuts they are used to, such as 108 | using the Home and End keys to move to the beginning, respectively end, of a 109 | line or document, don’t work as they expect in OS X.
110 | 111 |For new users, almost every text box you use is a Cocoa text box (or close 112 | enough to act the same as far as we’re concerned) — Safari web form boxes, 113 | the text field in iChat for sending new messages, the documents in Pages or 114 | TextEdit, the email composer in Mail, etc. Note: Some text boxes are not 115 | Cocoa however, so the tricks in this article still aren’t completely 116 | universal. Notably, Microsoft Word, Adobe applications, AppleWorks, and the 117 | text fields in Camino and Firefox won’t work with this hint.
118 | 119 |I expect that all users of OS X can get something out of this guide. I’m 120 | starting with the basics, so that new users, unfamiliar with the terminal and 121 | the intricacies of OS X can be brought up to speed. But even the most 122 | experienced users should hopefully learn something from this article; I know 123 | I learned several new nifty things while writing it.
124 | 125 |Disclaimer: it is possible, when mucking around with the text system, to 126 | send applications messages they aren’t expecting. This can cause them to 127 | crash. As long as you stick to standard text selectors, you should be fine, 128 | but I’m not responsible if your program crashes because of a binding you add.
129 | 130 |Terminology
131 | 132 |Before delving too deeply into the intricacies of the Cocoa text system, it 133 | helps to understand some programmer jargon.
134 | 135 |-
136 |
The Insertion Point (sometimes called the caret) 137 | is the blinking vertical line that shows where text typed into a text box 138 | will show up.
139 | A Buffer is the text field currently being edited. This might be a 140 | text box in an online form in Safari, or the main window in TextEdit.
141 | Key Bindings, often called ‘keyboard shortcuts’, 142 | define what happens when any key is typed in an application. For instance, 143 | in a Mac text editor, the ‘a’ key inserts an
a, ‘Opt-e, e’ inserts an 144 |é, and ‘Ctrl-a’ moves the insertion point to the beginning of the 145 | current line.
146 | A String is a chunk of text, literally a ‘string’ of 147 | letters.
148 | A Method is a function that an object (which includes 149 | just about everything in Cocoa) can perform.
150 | A Selector is the name of a method. It is a string. Something like 151 |
"insertTab:", or"save:"
152 | The Mark is an invisible point somewhere in the document, which can 153 | be set, and then returned to. Marking is the way regions of text were 154 | selected in UNIX text editors back in the days before they could be 155 | highlighted in blue with a mouse drag.
156 | To Kill some text is basically the same as using the ‘Cut’ command, 157 | but in OS X uses a separate mechanism, that is localized to the current 158 | buffer. By default ‘Ctrl-k’ kills everything after the insertion point on 159 | the current line.
160 | Yank is the analog of the ‘Paste’ command. By default, ‘Ctrl-y’ 161 | yanks back whatever was most recently killed.
162 |
Many of these terms crop up in the venerable Emacs editor, so reading 165 | about them in the Emacs context can be enlightening: Buffer, 166 | Key Bindings, Mark, Kill
167 | 168 |Existing (Default) Functionality
169 | 170 |Most users of Mac OS X, even long-time Apple geeks, know only a fraction of 171 | the available text system shortcuts. This is a tragedy, as they are consistent 172 | across all applications which use the Cocoa text system, including TextEdit, 173 | Mail, iChat, Safari, and countless third-party applications.
174 | 175 |Simple Text Insertion
176 | 177 |One thing every user knows is that when a plain letter is typed (assuming the 178 | input method in use matches the keyboard), that letter is inserted into a 179 | selected text box. When the shift key is held down, letters are capitalized, 180 | and symbol keys input the second symbol shown on them. For instance ‘Shift-]’ 181 | inputs the ‘}’ character.
182 | 183 |It is possible to see all of the possibilities using the 184 | ‘Keyboard Viewer’ palette:
185 | 186 |
187 | 
In addition, the option key, both alone and in conjunction with the shift key, 190 | will change the characters inserted. So ‘Option-y’ inserts a ‘¥’ currency 191 | mark, and ‘Option-Shift-c’ inserts a capital cedilla: ‘Ç’. We can see 192 | how option affects our input options using the Keyboard Viewer:
193 | 194 |
195 | 
Users with full keyboards have a complete number pad, with an enter key 198 | (instead of return), and symbols used in arithmetic. This number pad is 199 | available to PowerBook and iBook users as well. The numlock key (Fn-F6), 200 | enables the small symbols printed at the lower right corner of powerbook keys 201 | to be input. But even more usefully, those keys can also be used as a number 202 | pad while the Fn key is held down. This is great for typing lots of numeric 203 | data, and also comes in handy when playing games that allow vertical, 204 | horizontal, and diagonal movement via the number pad:
205 | 206 |
Of course, there are a number of standard actions that the above pictures 209 | don’t show. For instance, when you type ‘Command-left’, the insertion 210 | point moves to the beginning of the current line. Also, OS X has a fairly 211 | large number of unix/emacs bindings built in.
212 | 213 |The complete list of these extra commands takes up too much space for this 214 | page, so I’ve made them into a separate document.
215 | 216 |Default key bindings
217 | 218 |OS X has three main files which specify the key bindings used by Cocoa 219 | applications:
220 | 221 |/System/Library/Frameworks/AppKit.framework/Resources/StandardKeyBinding.dict
222 |
223 | /Library/KeyBindings/DefaultKeyBinding.dict
224 |
225 | ~/Library/KeyBindings/DefaultKeyBinding.dict
226 | which contain, respectively, the default ‘built-in’ key bindings, system-wide
229 | custom keybindings, and a user’s personalized key bindings. Don’t edit the
230 | built-in /System/Library/ file, as this could seriously hose your machine.
231 | Note that as usual, personalized bindings override the built-in standards.
If the DefaultKeyBinding.dict file doesn’t exist, don’t worry. Simply making
234 | a KeyBindings folder in ~/Library, and then adding a new text file should
235 | do the trick.
File Format:
238 | 239 |This file is a normal Property List, which can be created
240 | either with a text editor, such as TextWrangler, Smultron,
241 | or TextMate, or with Apple’s Property List Editor, which is installed
242 | with the developer tools. Property lists are pervasive in OS X, and are used
243 | for all sorts of configuration files, and preferences. Any file which has a
244 | .plist or .dict extension is a property list. Every application has an
245 | info.plist file inside of it which tells OS X what types of files that
246 | application can handle. Smart folders (.savedSearch files) are property
247 | lists. The defaults command, which can be run from the terminal, is a quick
248 | way to edit single items in a property list.
There are two types of property lists, old-style NeXT text files, and newer 251 | XML formatted files. I will use the old-style plists in this how-to, because 252 | they are easier to read and understand; they are more compact, with less 253 | distracting markup.
254 | 255 |The NeXT property list format is a file format that can describe, using 256 | plain text, all of the objects used in Cocoa programs. We specifically care 257 | about 3 types: ‘strings’, ‘lists’, and ‘dictionaries’:
258 | 259 |-
260 |
A string is simply a sequence of letters, numbers, and symbols, 261 | such as:
262 | 263 |"this is a string with some $#@! symbols" 264 |
265 | A list is, like it sounds, a list of other objects, such as 266 | lists or strings:
267 | 268 |("a", "list", "can", "contain", "many", "strings") 269 |
270 | A dictionary contains pairs of “keys” and “values”. Basically, 271 | dictionaries provide a way to name a bunch of objects, and refer 272 | to them by name. Note that while dictionary keys must be strings, 273 | the values can be any type of object.
274 | 275 |{"key1" = "value1"; "key2" = "value2"; "key3" = ("a", "list");} 276 |
277 | In addition, comments can be added to old-style property lists 278 | by enclosing some text in
/*and*/
279 |
Every property list has a root dictionary object, which can contain 282 | sub-objects. A simple plist file might look like:
283 | 284 |{
285 | /* ** THIS IS A COMMENT: **
286 | *
287 | * Notice that each line in the dictionary has a 'key' string,
288 | * and a 'value', which can be a string, a list, or another
289 | * dictionary.
290 | */
291 |
292 | "My String" = "Hey there!";
293 |
294 | "My List" = ("first string", "second string", "final string");
295 |
296 | "My Dictionary" = {
297 | "Sub-string A" = "This is a string inside a dictionary";
298 | "Sub-list B" = ("This is a list", "inside a dictionary");
299 | };
300 | }
301 | This property list has three key-value pairs: a string, a list, and a 304 | dictionary.
305 | 306 |The format of DefaultKeyBinding.dict
307 | 308 |The DefaultKeyBindings.dict file is fairly straight-forward. It is a normal
309 | property list, which as keys, uses the requested key bindings, and as values
310 | uses the commands they should execute. For instance, I might want the letter
311 | a to not type ‘a’, but instead insert a tab. If I put the following in my
312 | DefaultKeyBinding.dict, then all Cocoa apps launched afterwards will insert
313 | a tab key instead of an a:
{
316 | /* This will make all a's turn to tabs. Beware. */
317 | "a" = "insertTab:";
318 | }
319 | How to represent bindings
322 | 323 |But of course, if we could only bind things to letter keys, this wouldn’t 324 | really be so useful, now would it? Fortunately, Apple’s engineers made sure 325 | that every key that you could possibly ever type can be put into a binding.
326 | 327 |The way it works is simple. For lower-case and capital letters, simply type
328 | the letter into the string. So "y" represents the ‘y’ key, while "T"
329 | represents ‘Shift-t’. For numbers and symbols, including space, the same
330 | holds. So "!" represents ‘Shift-1’, or however you type ‘!’ on your keyboard
331 | layout. To add modifier keys, add a symbol corresponding to that modifier:
334 |340 | 341 |339 |
"@t"= Command-t
335 |"^t"= Control-t
336 |"~t"= Option-t
337 |"@^T"= Command-Control-Shift-t
338 |"~ "= Option-space
For numbers and symbols, to add the shift key is not as easy as typing a
342 | capital letter, so $ stands for shift. Also, there is a difference between
343 | numbers above the letter keys, and numbers on the keypad. To indicate keypad
344 | keys, use #:
347 |350 | 351 |349 |
"@$#5"= Command-Shift-Numpad 5
348 |"^6"= Control-6
Note: Lots of bindings with the Command key won’t work. This is done by 352 | Apple to ensure that applications can use these shortcuts for themselves, and 353 | not worry about user key bindings. Some will work, however, such as 354 | ‘Command-right arrow’.
355 | 356 |There are still 2 limitations: First, what do we do if we want to bind a
357 | literal ‘@’ or ‘#’ symbol? We escape it! By adding a \\ before the symbol,
358 | we can avoid this. At the moment, the only way I can get ‘\’ itself to bind to
359 | anything is by writing it as ‘\U05C’.
362 |364 | 365 |363 |
"~\\$"= Option-$
Second, if we were limited to symbols and modifiers, we would still cut off 366 | keys like ‘delete’, ‘tab’, and ‘esc’, so any keys that aren’t already covered 367 | can be entered using their unicode values:
368 | 369 |Unicode values for Apple non-letter keys:
370 | 371 || Escape: | \U001B |
| Tab: | \U0009 |
| Backtab: | \U0019 |
| Return: | \U000A |
| Enter: | \U000D |
| Delete: | \U007F |
| Up Arrow: | \UF700 |
| Down Arrow: | \UF701 |
| Left Arrow: | \UF702 |
| Right Arrow: | \UF703 |
| Help: | \UF746 |
| Forward Delete: | \UF728 |
| Home: | \UF729 |
| End: | \UF72B |
| Page Up: | \UF72C |
| Page Down: | \UF72D |
| Clear: | \UF739 |
| F1: | \UF704 |
| F2: | \UF705 |
| F3: | \UF706 |
| … | |
| F35 | \UF726 |
| Not on Apple keyboards: | |
| Menu: | \UF735 |
Notes:
408 | 409 |-
410 |
- ‘Backtab’ is ‘Shift-Tab’ 411 |
- The key labeled ‘Backspace’ on most PC keyboards is the ‘Delete’ key 412 |
- The ‘Num Lock’ key on PC keyboards is ‘Clear’ 413 |
- The keys labeled ‘Print Screen’, ‘Scroll Lock’, and ‘Pause’ are 414 | respectively ‘F13’, ‘F14’, and ‘F15’ 415 |
- The key labeled ‘Insert’ is the ‘Help’ key 416 |
- I’m not sure whether the ‘Menu’ key actually does anything, as I don’t own 417 | a keyboard with that key on it. 418 |
For a complete list, including some keys that aren’t on current apple 421 | keyboards, but can still be used by OS X, see the Registry 422 | of Apple Unicode corporate-zone characters.
423 | 424 |In general, the best way I’ve found to discover key’s escape codes is to use 425 | the free Key Codes application from Peter Maurer. The app brings 426 | up a floating palette which prints a log of all the keys typed.
427 | 428 |More complicated bindings and actions
429 | 430 |Of course, sometimes we wish we had more keys on the keyboard. Even with all 431 | of the modifier keys, it gets hard to keep different functionality separated, 432 | and things get confused. For this reason, it is possible to use 433 | multiple-keystroke bindings. To this end, instead of binding our first 434 | keystroke to a selector, we bind it to a dictionary, containing the second 435 | keystrokes. Emacs, the UNIX-based text editor, has many such 436 | multiple-keystroke bindings. Therefore, as an example of how this can be done, 437 | we will take Emacs bindings, and try to replicate them in Cocoa Text Widgets.
438 | 439 |One Emacs command is ‘Control-x, u’, for ‘undo’. Another is ‘Control-x, 440 | Control-s’ for ‘save’. To add this command to our key bindings, we need to 441 | bind ‘Control-x’ to a dictionary of sub-bindings:
442 | 443 |{
444 | /* Control-x dictionary */
445 | "^x " = {
446 | "u" = "undo:"; /* C-x u => undo */
447 | "^s" = "save:"; /* C-x C-s => save */
448 | };
449 | }
450 | Our ‘Control-x’ parent dictionary can have several multiple-keystroke bindings 453 | associated with it. In this way, we can have whole areas of functionality 454 | given to one ‘parent’ key binding, with the resulting action to be determined 455 | by a letter. We can effectively have 4 or 5 keyboards for our bindings!
456 | 457 |But of course, the number of bindings is not our only limitation so far. We 458 | are also limited by the range of selectors offered by the text box. We often 459 | find ourselves performing complicated actions repeatedly, and would like to 460 | invoke them with single keystroke. Mostly when this happens, Applescript, or 461 | some other programming language is the best solution. On occasion, however, 462 | the text system has enough power and flexibility to do the trick. This is 463 | because, besides single selectors, a binding can also execute a list of 464 | selectors, sequentially.
465 | 466 |As an example, imagine that I often want to change paragraphs of text to all 467 | capital letters, but I’m tired of selecting the whole paragraph with my 468 | keyboard or mouse. I want ‘Control-Option-u to make my paragraph all 469 | uppercase, and then I want it to start a new paragraph by inserting two new 470 | lines at the end of the paragraph.
471 | 472 |This (somewhat contrived) action can be broken into steps: 1. Select paragraph 473 | 2. Make all the letters uppercase 3. Move to the end of the paragraph 4. 474 | Insert two new lines.
475 | 476 |We can make a plist of these directions:
477 | 478 |{
479 | "^~u" = ("selectParagraph:",
480 | "uppercaseWord:",
481 | "moveToEndOfParagraph:"
482 | "insertNewline:",
483 | "insertNewline");
484 | }
485 | So, with the the ability to map multiple-keystroke bindings to sets of actions 488 | that can perform complicated behaviors, what’s left?
489 | 490 |Every time you type a key, the Cocoa text system looks for bindings, and if
491 | none are found for the key, it instead passes the keystroke along as a string
492 | input to the insertText: selector. Well, as luck would have it,
493 | Kevin Ballard, from the ##textmate IRC channel on
494 | freenode (a delightful place to chat, incidentally), found a real
495 | gem, that doesn’t seem to be documented anywhere on Apple’s website, or
496 | anywhere else: It is possible to use the insertText: selector as part of a
497 | binding, and thereby bind an arbitrary string to a keystroke. If we bind a
498 | key to a list, containing "insertText:" as one of its strings, the next
499 | string in the list will be inserted into the text field. Example:
{
502 | /* Realize that actually using this will render your a key
503 | amusingly useless.*/
504 | "a" = ("insertText:", "some fun text", "moveWordBackward:");
505 | }
506 | as a DefaultKeyBinding.dict file will make the ‘a’ key type ‘some fun text’, 509 | and then move the insertion point to the beginning of the word ‘text’, instead 510 | of the simply typing an ‘a’, as usual.
511 | 512 |This is amazingly useful if there are some symbols or strings which must be
513 | entered on a regular basis. For instance, imagine that I sometimes need to
514 | type LaTeX Greek letters, and also sometimes need the associated unicode
515 | symbols (for alpha, beta, etc.). The following DefaultKeyBinding.dict could
516 | reduce this load considerably:
{
519 | /* Greek unicode letters */
520 | "^g" = {
521 | "a" = ("insertText:", "\U03B1");
522 | "b" = ("insertText:", "\U03B2");
523 | "g" = ("insertText:", "\U03B3");
524 | "d" = ("insertText:", "\U03B4"); /*
525 | ... */
526 | }
527 |
528 | /* Greek LaTeX letters */
529 | "^m" = {
530 | "a" = ("insertText:", "\\alpha");
531 | "b" = ("insertText:", "\\beta");
532 | "g" = ("insertText:", "\\gamma");
533 | "d" = ("insertText:", "\\delta"); /*
534 | ... */
535 | }
536 | }
537 | Now, when I type ‘Control-g, a’, ‘α’ will be inserted instead, and when 540 | I type ‘Control-m, g’, ‘\gamma’ will be inserted, etc.
541 | 542 |It seems like this behavior is just an exception, as I haven’t found any other 543 | selectors which take an argument, but it’s a glorious exception, for which I 544 | can envision some truly creative uses.
545 | 546 |For instance, if I want to drive some friends bonkers, I could set
547 | DefaultKeyBinding.dict up to ROT13 all of my letters, to enable
548 | “typing in code”. Or I could set it up to allow typing in leetspeak
549 | (“1337”).
Most obviously perhaps, I could bind common phrases or code snippets to simple 552 | keystrokes. This would allow systemwide text shortcuts without the need for 553 | third-party applications (though the third party applications out there, 554 | notably Peter Maurer’s Textpander, do a lot more than key 555 | bindings allow).
556 | 557 |One binding that I made, and it’s one of my favorites, allows me to type 558 | html and xml tags with ease. I have Control-shift-h make a starting and tag 559 | pair out of the word I’ve just finished typing, and put the cursor in the 560 | middle of them. Here’s the code:
561 | 562 |{
563 | /* This command will let Ctrl-Shift-H turn the previous word
564 | * into an HTML/XML opening and closing tag pair. */
565 | "^H" = ( "setMark:",
566 | "moveWordBackward:",
567 | "deleteToMark:",
568 | "insertText:", "<",
569 | "yank:",
570 | "insertText:", ">",
571 | "setMark:",
572 | "insertText:", "</",
573 | "yank:",
574 | "insertText:", ">",
575 | "swapWithMark:");
576 | }
577 | Finally, the possibilities for pranks on coworkers, significant others, etc. 580 | is considerable. For instance, we can set the keyboard up to malfunction on a 581 | couple of letters, maybe a ‘z’ could say “you didn’t 582 | *really* want to type that, did you?”:
583 | 584 |{
585 | "z" = ("setMark:",
586 | "insertText:",
587 | "you didn't *really* want to type that, did you?",
588 | "selectToMark:",
589 | "speakText:");
590 | }
591 | Moving right along, now that we have the idea of how to form our bindings, we 594 | can get to figuring out exactly which selectors are available to us.
595 | 596 |Usable selectors
597 | 598 |It is hard to figure out exactly which selectors a text box, and more 599 | generally, an application, will respond to. There are a huge number of 600 | options, but they are not all documented in one place. This is partly because 601 | if one object in an application doesn’t respond to a particular message, it 602 | will pass the message along to its parent object.
603 | 604 |Still, we can find a large number of useful selectors by searching through the 605 | documentation we can find, and testing what the selectors do. The biggest 606 | source of selectors that we might want to use is in the NSResponder class — 607 | see its documentation. Specifically, we care about the 608 | ‘Action methods’ section. Also, the documentation for 609 | NSText has some selectors we can use, and many other classes provide useful 610 | selectors as well, such as NSDocumentController and NSWindow.
611 | 612 |Because there are so many usable selectors, I’m putting them in a separate 613 | page. Here’s a link.
614 | 615 |Examples
616 | 617 |I’ve put together some examples of how this could be used. To use one of
618 | these, simply rename the file to DefaultKeyBinding.dict and plop it in the
619 | ~/Library/KeyBindings folder. One of the most common uses of custom key
620 | bindings is emulating another operating system or environment, such as Windows
621 | or Emacs or BBEdit:
-
624 |
- Emacs emulation key bindings with esc as meta key 625 |
- Emacs emulation key bindings with opt as meta key 626 |
- BBEdit emulation key bindings (far 627 | from complete) 628 |
- Windows emulation key bindings 629 | (I’m still working on this one, if someone has a list of windows 630 | default key behaviors, email me: jacobolus [at] gmail.com) 631 |
Beyond that, it’s possible make key bindings as pranks. That’s always fun:
634 | 635 |-
636 |
- Leet bindings 637 |
- Greek bindings 638 |
Text System Defaults
641 | 642 |Besides making our own key bindings, there are a few other nifty changes we
643 | can apply to the Cocoa text system, using the “defaults” system. Apple’s
644 | developer site tells about them. Some of
645 | these defaults are for unimplemented features, and are therefore worthless to
646 | us. There are three defaults however which are of interest to us here. They
647 | can be set using the defaults terminal command. I will show them applying
648 | globally with the -g flag, but it is possible to set them on an application
649 | by application basis, by for instance specifying com.apple.textedit instead
650 | of -g.
-
653 |
654 | 655 |NSTextKillRingSizeThis default sets the size of the kill ring. It can be set as follows:
656 | 657 |
659 | 660 |defaults write -g NSTextKillRingSize -string 4 658 |This changes the size of the “kill ring” which large deleted blocks of 661 | text get copied to. In this case, I have set it to keep track of the 4 662 | most recent such blocks. This means that this text can be cycled through, 663 | and won’t be lost as soon as more text is killed. An extra binding is 664 | useful in dealing with a kill ring:
yankAndSelect:, which cycles through 665 | the kill ring.
666 |
667 | 668 |NSRepeatCountBindingThis one is one of the coolest features of the text system. In emacs, 669 | pressing “Control-u”, and then a number, 94 say, and then any other 670 | command, will repeat that command 94 times. It is possible to set OS X to 671 | do the same thing with “Control-u” as follows:
672 | 673 |
675 | 676 |defaults write -g NSRepeatCountBinding -string "^u" 674 |Of course, any other binding could be set instead of “Control-u”.
677 |
678 | 679 |NSQuotedKeystrokeBindingThis default is normally linked to Control-q. It causes the next 680 | keystroke typed to be passed through the system, without activating any 681 | bindings. For example, if the “Option-v” is bound to scroll up in the 682 | key bindings file, a square root sign — √ — can still be entered by 683 | typing “Control-q, Option-v”.
684 |
Input Managers
687 | 688 |NeXT and Apple realized, when they created Cocoa, that many actions could not 689 | be foreseen by their framework developers. The key binding system is great if 690 | we want to stick within the usual sorts of operations on English text, such as 691 | transposing two letters, skipping the end of a paragraph, or upper-casing a 692 | word, and we can combine these simple actions, but sometimes to do what we 693 | want requires more.
694 | 695 |An input manager is a piece of code which is loaded into every running Cocoa 696 | application. The purpose of an input manager is to extend the text system in 697 | ways not thought of by the application’s original programmers.
698 | 699 |We’ve all been hearing of late about how input managers can be used for 700 | nefarious purposes, but as long as they stick to modifying the text system, 701 | they mostly stay out of trouble, and they can be incredibly useful. Two input 702 | managers in particular are quite popular:
703 | 704 |-
705 |
First, Mike Ferris’s TextExtras extends the Cocoa 706 | text system in ways that programmers, particularly, will find 707 | useful. I haven’t spent too much time playing with TextExtras, 708 | especially since TextMate, my editor of choice, 709 | doesn’t quite use the same Cocoa controls as other Cocoa-based 710 | editors like SubEthaEdit and Smultron. But 711 | TextExtras adds quite a bit to the Cocoa text system, including 712 | indent wrapping, auto-indentation, showing and selecting matching 713 | braces, improved completion, and, perhaps most of all, customized 714 | piping of text through shell commands. This allows all sorts of 715 | snazzy behavior (note that editors like TextWrangler and 716 | TextMate have their own implementations of this feature).
717 | Second, one of my favorite text-system extensions is 718 | Michael McCracken’s Incremental Search Input Manager 719 | (ISIM). Here’s a link to a zip-file of the universal binary.
720 | 721 |ISIM is an input manager that provides three new selectors for binding in 722 | our
731 | 732 |DefaultKeyBinding.dictfile:ISIM_incrementalSearch:, 723 |ISIM_reverseIncrementalSearch:, andabort:(that last one may 724 | work for other things, I’m not sure). The idea is pretty simple, but 725 | incredibly useful. Basically, when the selector is invoked, a little 726 | window pops up at the bottom of the current text box. When you type 727 | into this little window, ISIM searches through the current document 728 | searching for text that matches, and selects the first occurrence of 729 | such text. Repeatedly invoking the selector flips through any other 730 | occurrences in the document. A picture can say this better than I can:
733 | 734 |
The relevant part of my key bindings file looks like this:
735 | 736 |/* Incremental search */ 737 | "^s" = "ISIM_incrementalSearch:"; 738 | "^r" = "ISIM_reverseIncrementalSearch:"; 739 | "^$g" = "abort:"; 740 |
741 | Finally, for those who can’t get enough customization in a straight 742 | NSTextView, using the techniques described already, Gus Mueller made an 743 | input manager, described in two blog posts, which 744 | allows the contents of any Cocoa text field to BBEdit. Type the relvant 745 | key, and your text will pop up in a new BBEdit document. Save, and the 746 | text in the original text field is updated. It’s awesome. According to the 747 | second post, modifying it to work with any editor which uses the ODBEditor 748 | suite (used mainly by FTP programs to open remote files in a local text 749 | editor) would be easy—it’s open source.
750 | 751 |TextMate, my editor of choice, comes with a similar input manager, I 752 | believe inspired by the first one. And the great thing about TextMate’s 753 | version is that it works in Mail (I’m not sure, but I think Gus’s 754 | doesn’t). If there’s a text editor you like, it’s extremely nice to be 755 | able to edit Safari form fields, emails, and other text using that editor.
756 |
Even Lower-Level Hacking: Keyboard Layouts
759 | 760 |First, we haven’t seen any way to remap modifier keys so far. This can be 761 | easily accomplished using the Keyboard and Mouse preference pane. Click the 762 | ‘modifier keys’ button at the bottom of the view, and a nice sheet pops up. 763 | Mine, which I’ve set to put the keys on a Model M keyboard in the 764 | right places, with ‘Control’ where it belongs next to the ‘A’ key, looks like 765 | this:
766 | 767 |
For even finer control over the keyboard, it is possible to create 770 | customized keyboard layouts. These allow any unicode glyphs 771 | to be mapped to the keys on the keyboard, so alternate language scripts can be 772 | entered, etc. This will work across the OS, not just in Cocoa text editors, 773 | but is also a much lower-level change, which means that messing it up could be 774 | much worse. I haven’t actually ever used any layouts other than U.S. on my 775 | PowerBook, so I don’t know how easy this is. There is a pretty nice GUI 776 | editor for this from SIL called Ukelele. It has great 777 | documentation, and should be all that is needed to make custom keyboard 778 | layouts.
779 | 780 |Finally, for the truly adventurous, it is apparently possible to go even 781 | lower-level than Ukelele, and patch the ADB codes which are registered 782 | by Apple’s USB keyboard drivers. I’m not sure exactly which versions of OS 783 | X this works with, and any hacking at this level requires a serious 784 | disclaimer, as a wrong move here could really mess up your system. But here 785 | are two links at snark.de which discuss such arcane 786 | trickery. Good luck to any who try this. This same guy (Heiko Hellweg) also 787 | made his own keyboard layout, and patched Apple’s keyboard drivers 788 | to give himself a meta key:
789 | 790 |791 |804 | 805 |“I got myself the Tiger-Version of the ADB Keyboard Driver 792 | (AppleADBKeyboard-238.3.4) and hacked away in XCode. My current setup uses 793 | the obnoxious enter key (between the cursor keys and the right command 794 | key) as the alt modifier (you can do that without a compiler by just 795 | fiddling with info.plist) and turns the original alt-key on the left 796 | onto a META key that sends escape in front of every other key as long as 797 | it is pressed (for this one, i needed to replace 798 |
800 | 801 |/System/Library/Extensions/AppleADBKeyboard.kextwith an actual 799 | modified binary).“Now i can actually type ahead blindly without thinking twice. Contact me, 802 | if you are interested in using this too.”
803 |
Needless to say, I wouldn’t advise trying this, unless you know what you are 806 | doing.
807 | 808 |Useful Links
809 | 810 |TODO: Much of this list of links is still incomplete
811 | 812 |Text Editors
813 | 814 |Free Cocoa text editors for OS X:
815 | 816 |-
817 |
- TextEdit — Comes on every Mac 818 |
- Smultron — Clean, simple, Open-source text editor. 819 | Named after some sort of Scandinavian strawberry. Can’t beat free! 820 |
Commercial Cocoa text editors:
823 | 824 |-
825 |
- TextMate — most awesome text editor ever. I really can’t 826 | recommend this one enough. If you type lots of text, whether it’s 827 | C or Python code, LaTeX, John Gruber’s 828 | Markdown, or anything else, TextMate is amazing. It uses a 829 | different text box than the usual Cocoa one, so not all of the 830 | things discussed here will work, for instance, tying multiple commands 831 | to one binding, or using multiple keystroke commands. Still, TextMate 832 | allows far more customization than NSText widgets in general, so 833 | custom system bindings aren’t as necessary. 834 |
- SubEthaEdit — Nifty collaborative editor, which allows 835 | people halfway around the world from each-other to work on the same 836 | text file at once. This editor kicks all kinds of ass when it comes 837 | to collaborative note taking, or pair programming. It’s not too shabby 838 | for solo programming either. 839 |
Non-Cocoa text editors for OS X:
842 | 843 |-
844 |
- TextWrangler — Excellent (free!) editor from Bare Bones.
845 | Not Cocoa, so the keybindings described in this how-to won’t work, 846 | but a great Mac citizen nonetheless, with lots of scriptability, 847 | and excellent documentation.
848 | - BBEdit — Bare Bones’s flagship editor. $200, or 849 | $130 as an “upgrade” from the free TextWrangler, or $50 for 850 | educational users. Steep pricing, but does most everything you’d 851 | ever expect a text editor to do, and more. I think I still like 852 | TextMate better, but Mac users have sworn by BBEdit for almost as 853 | long as I’ve been alive. 854 |
Apple Developer Documentation
857 | 858 |Apple has some documentation for the key bindings, but all in all it is far 859 | from adequate, especially for regular users, as opposed to competent 860 | Objective-C hackers.
861 | 862 |-
863 |
- About Key Bindings — A brief note. 864 |
- Text System Defaults and Key Bindings 865 | — A longer explanation of some of the possibilities with key 866 | bindings, which also shares some cool text system defaults, 867 | editable from the command line. 868 |
- The NSResponder class — The NSResponder 869 | class is chock full of useful selectors to try to bind keys to. 870 |
- Text Input Management — This extensive 871 | article is far beyond the scope of this guide, and also only 872 | somewhat relevant. It details the nitty gritty of the Cocoa 873 | Text system, including information on how to create your own 874 | input managers. 875 |
- Introduction to Property Lists — Apple’s 876 | documentation of the property list format, covering both old-style 877 | and XML formats. 878 |
- Registry of Apple use of Unicode corporate-zone characters. 879 | — not at Apple.com, but this text document tells the unicode values 880 | of all the control keys we want to put in our bindings. 881 |
Third-party documentation
884 | 885 |-
886 |
- Llew Mason’s pretty good explanation of key bindings in OS X 887 |
- A page at Cocoa Dev about them 888 |
- A page by ‘misaka’ at deepsky.com 889 |
- Shane Celis’ description at gnufoo.org 890 |
- An example key bindings file 891 |
- Michael C Thornburgh has some Vi-ish keybindings at his site, 892 | armory.com, in xml plist format. 893 |
- David Pogue’s comparison of keyboard shortcuts on Windows and on 894 | the Mac. 895 |
Key Bindings Editors
898 | 899 |-
900 |
- Gerd Knops’s Key Bindings Editor is a Cocoa application which 901 | allows the viewing and editing of key bindings files. It knows where the 902 | system, XCode, and TextMate key bindings are, and allows html and plain 903 | text export. 904 |
- Mikael Langer’s TextMacro does some stuff which is no 905 | longer needed… it’s an input manager which allows arbitrary text to be 906 | input with key bindings, and is supposed to provide for multiple sets of 907 | key bindings which can be swapped out. It is implemented as a preference 908 | pane. 909 |
Input Managers
912 | 913 |-
914 |
- Incremental Search Input Manager 915 |
- TextExtras 916 |
- XML Tag Input Manager — Annard Brouwer’s free input manager 917 | for selecting XML/HTML tags; it lets your mouse get in on the text system 918 | action. 919 |
Tangentially-related MacOSXHints hints
922 | 923 |-
924 |
- Prewrap Lines in Mail.app discusses TextExtras, and 925 | gives an example of an application. 926 |
- Find and replace special characters in Cocoa apps
927 | — A hint by Bill Bumgarner about
NSQuotedKeystrokeBinding, 928 | which is Control-q by default.
929 | - Enabling meta-key Emacs shortcuts in Cocoa apps — this one 930 | isn’t really so tangential: it shows users how to get emacs emulation by 931 | putting installing a custom keybinding file (the emacs emulation is not 932 | nearly as complete as ours above ;-) ). 933 |
