Batch-Editing Mode

If your code needs to modify the text backing store directly, you should use batch-editing mode; that is, bracket the changes between the NSMutableAttributedString methods beginEditing and endEditing. Although this bracketing is not strictly necessary, it’s good practice, and it’s important for efficiency if you’re making multiple changes in succession. NSTextView uses the beginEditing and endEditing methods to synchronize its editing activity, and you can use the methods directly to control the timing of notifications to delegates, observers, and associated layout managers. When the NSTextStorage object is in batch-editing mode, it refrains from informing its layout managers of any editing changes until it receives the endEditing message.

The “beginning of editing” means that a series of modifications to the text backing store (NSTextStorage for text views and cell values for cells) is about to occur. Bracketing editing between beginEditing and endEditing locks down the text storage to ensure that text modifications are atomic transactions.

The “end of editing” means that the backing store is in a consistent state after modification. In cells (such as NSTextFieldCell objects, which control text editing in text fields), the end of editing coincides with the field editor resigning first responder status, which triggers synchronization of the contents of the field editor and its parent cell.

In addition, the text view sends NSTextDidEndEditingNotification when it completes modifying its backing store, regardless of its first responder status. For example, it sends out this notification when the Replace All button is clicked in the Find window, even if the text view is not the first responder.

Listing 7-1 illustrates a situation in which the NSText method scrollRangeToVisible: forces layout to occur and raises an exception.

Listing 7-1  Forcing layout

[[myTextView textStorage] beginEditing];

[[myTextView textStorage] replaceCharactersInRange:NSMakeRange(0,0)

        withString:@"Hello to you!"];

[myTextView scrollRangeToVisible:NSMakeRange(0,13)]; //BOOM

[[myTextView textStorage] endEditing];

Scrolling a character range into visibility requires layout to be complete through that range so the text view can know where the range is located. But in Listing 7-1, the text storage is in batch-editing mode. It is in an inconsistent state, so the layout manager has no way to do layout at this time. Moving the scrollRangeToVisible: call after endEditing would solve the problem.

There are additional actions that you should take if you implement new user actions in a text view, such as a menu action or key binding method that changes the text. For example, you can modify the selected range of characters using the NSTextView method setSelectedRange:, depending on the type of change performed by the command, using the results of the NSTextView methods rangeForUserTextChange, rangeForUserCharacterAttributeChange, or rangeForUserParagraphAttributeChange. For example, rangeForUserParagraphAttributeChange returns the entire paragraph containing the original selection—that is the range affected if your action modifies paragraph attributes. Also, you should call textView:shouldChangeTextInRange:replacementString: before you make the change and didChangeText afterwards. These actions ensure that the correct text gets changed and the system sends the correct notifications and delegate messages to the text view’s delegate. See Subclassing NSTextView for more information.

Forcing the End of Editing

There may be situations in which you need to force the text system to end editing programmatically so you can take some action dependent on notifications being sent. In such a case, you don’t need to modify the editing mechanism but simply stimulate its normal behavior.

To force the end of editing in a text view, which subsequently sends a textDidEndEditing: message to its delegate, you can observe the window’s NSWindowDidResignKeyNotification notification. Then, in the observer method, send makeFirstResponder: to the window to finish any editing in progress while the window was active. Otherwise, the control that is currently being edited remains the first responder of the window and does not end editing.

Listing 7-2 presents an implementation of the textDidEndEditing: delegate method that ends editing in an NSTableView subclass. By default, when the user is editing a cell in a table view and presses Tab or Return, the field editor ends editing in the current cell and begins editing the next cell. In this case, you want to end editing altogether if the user presses Return. This method distinguishes which key the user pressed; for Tab it does the normal behavior, and for Return it forces the end of editing completely by making the window first responder.

Listing 7-2  Forcing the end of editing

- (void)textDidEndEditing:(NSNotification *)notification {

    if([[[notification userInfo] valueForKey:@"NSTextMovement"] intValue] ==

                        NSReturnTextMovement) {

        NSMutableDictionary *newUserInfo;

        newUserInfo = [[NSMutableDictionary alloc]

                            initWithDictionary:[notification userInfo]];

        [newUserInfo setObject:[NSNumber numberWithInt:NSIllegalTextMovement]

                                forKey:@"NSTextMovement"];

        notification = [NSNotification notificationWithName:[notification name]

                                object:[notification object]

                                userInfo:newUserInfo];

        [super textDidEndEditing:notification];

        [[self window] makeFirstResponder:self];

    } else {

        [super textDidEndEditing:notification];

    }

}

Setting Focus and Selection Programmatically

Usually the user clicks a view object in a window to set the focus, or first responder status, so that subsequent keyboard events go to that object initially. Likewise, the user usually creates a selection by dragging the mouse in a view. However, you can set both the focus and the selection programmatically.

For example, if you have a window that contains a text view, and you want that text view to become the first responder with the insertion point located at the beginning of any text currently in the text view, you need a reference to the window and the text view. If those references are theWindow and theTextView, respectively, you can use the following code to set the focus and the insertion point, which is simply a zero-length selection range:

[theWindow makeFirstResponder: theTextView];

[theTextView setSelectedRange: NSMakeRange(0,0)];

When an object conforming to the NSTextInputClient protocol becomes the first responder in the key window, its NSTextInputContext object becomes active and bound to the active text input sources, such as character palette, keyboards, and input methods.

Whether the selection was set programmatically or by the user, you can get the range of characters currently selected using the selectedRange method. NSTextView indicates its selection by applying a special set of attributes to it. The selectedTextAttributes method returns these attributes, and setSelectedTextAttributes: sets them.

While changing the selection in response to user input, an NSTextView object invokes its own setSelectedRange:affinity:stillSelecting: method. The first parameter is the range to select. The second, called the selection affinity, determines which glyph the insertion point displays near when the two glyphs defining the selected range are not adjacent. It’s typically used where the selected lines wrap to place the insertion point at the end of one line or the beginning of the following line. You can get the selection affinity currently in effect using the selectionAffinity method. The last parameter indicates whether the selection is still in the process of changing; the delegate and any observers aren’t notified of the change in the selection until the method is invoked with NO for this argument.

Another factor affecting selection behavior is the selection granularity: whether characters, words, or whole paragraphs are being selected. This is usually determined by the number of initial mouse clicks; for example, a double click initiates word-level selection. NSTextView decides how much to change the selection during input tracking using its selectionRangeForProposedRange:granularity: method.

An additional aspect of selection, related to input management, is the range of marked text. As the input context interprets keyboard input, it can mark incomplete input in a special way. The text view displays this marked text differently from the selection, using temporary attributes that affect only display, not layout or storage. For example, NSTextView uses marked text to display a combination key, such as Option-E, which places an acute accent character above the character entered next. When the user types Option-E, the text view displays an acute accent in a yellow highlight box, indicating that it is marked text, rather than final input. When the user types the next character, the text view displays it as a single accented character, and the marked text highlight disappears. The markedRange method returns the range of any marked text, and markedTextAttributes returns the attributes used to highlight the marked text. You can change these attributes using setMarkedTextAttributes:.

Updating State

NSTextView automatically updates the Fonts window and ruler as its selection changes. If you add any new font or paragraph attributes to your subclass of NSTextView, you’ll need to override the methods that perform this updating to account for the added information. The updateFontPanel method makes the Fonts window display the font of the first character in the selection. You could override this method to update the display of an accessory view in the Fonts window. Similarly, updateRuler causes the ruler to display the paragraph attributes for the first paragraph in the selection. You can also override this method to customize display of items in the ruler. Be sure to invoke the super implementation in your override to have the basic updating performed as well.

Custom Import Types

NSTextView supports pasteboard operations and the dragging of files and colors into its text. If you customize the ability of your subclass to handle pasteboard operations for new data types, you should override the readablePasteboardTypes and writablePasteboardTypes methods to reflect those types. Similarly, to support new types of data for dragging operations, you should override the acceptableDragTypes method. Your implementation of these methods should invoke the superclass implementation, add the new data types to the array returned from super, and return the modified array.

To read and write custom pasteboard types, you must override the readSelectionFromPasteboard:type: and writeSelectionToPasteboard:type: methods. In your implementation of these methods, you should read the new data types your subclass supports and let the superclass handle any other types.

For dragging operations, if your subclass’s ability to accept your custom dragging types varies over time, you can override updateDragTypeRegistration to register or unregister the custom types according to the text view’s current status. By default this method enables dragging of all acceptable types if the receiver is editable and a rich text view.

Altering Selection Behavior

Your subclass of NSTextView can customize the way selections are made for the various granularities (such as character, word, and paragraph) described inSetting Focus and Selection Programmatically. While tracking user changes to the selection, an NSTextView object repeatedly invokes selectionRangeForProposedRange:granularity: to determine what range to actually select. When finished tracking changes, it sends the delegate a textView:willChangeSelectionFromCharacterRange:toCharacterRange: message. By overriding the NSTextView method or implementing the delegate method, you can alter the way the selection is extended or reduced. For example, in a code editor you can provide a delegate that extends a double click on a brace or parenthesis character to its matching delimiter.

These mechanisms aren’t meant for changing language word definitions (such as what’s selected by a double click). That detail of selection is handled at a lower (and currently private) level of the text system.

Preparing to Change Text

If you create a subclass of NSTextView to add new capabilities that will change the text in response to user actions, you may need to modify the range selected by the user before actually applying the change. For example, if the user is making a change to the ruler, the change must apply to whole paragraphs, so the selection may have to be extended to paragraph boundaries. Three methods calculate the range to which certain kinds of change should apply. The rangeForUserTextChange method returns the range to which any change to characters themselves—insertions and deletions—should apply. The rangeForUserCharacterAttributeChange method returns the range to which a character attribute change, such as a new font or color, should apply. Finally, rangeForUserParagraphAttributeChange returns the range for a paragraph-level change, such as a new or moved tab stop or indent. These methods all return a range whose location is NSNotFound if a change isn’t possible; you should check the returned range and abandon the change in this case.

Text Change Notifications and Delegate Messages

In actually making changes to the text, you must ensure that the changes are properly performed and recorded by different parts of the text system. You do this by bracketing each batch of potential changes with shouldChangeTextInRange:replacementString: and didChangeText messages. These methods ensure that the appropriate delegate messages are sent and notifications posted. The first method asks the delegate for permission to begin editing with a textShouldBeginEditing: message. If the delegate returns NO, shouldChangeTextInRange:replacementString: in turn returns NO, in which case your subclass should disallow the change. If the delegate returns YES, the text view posts an NSTextDidBeginEditingNotification, and shouldChangeTextInRange:replacementString: in turn returns YES. In this case you can make your changes to the text, and follow up by invoking didChangeText. This method concludes the changes by posting an NSTextDidChangeNotification, which results in the delegate receiving a textDidChange: message.

The textShouldBeginEditing: and textDidBeginEditing: messages are sent only once during an editing session. More precisely, they’re sent upon the first user input since the NSTextView became the first responder. Thereafter, these messages—and the NSTextDidBeginEditingNotification—are skipped in the sequence. The textView:shouldChangeTextInRange:replacementString: method, however, must be invoked for each individual change.

Smart Insert and Delete

NSTextView defines several methods to aid in “smart” insertion and deletion of text, so that spacing and punctuation are preserved after a change. Smart insertion and deletion typically applies when the user has selected whole words or other significant units of text. A smart deletion of a word before a comma, for example, also deletes the space that would otherwise be left before the comma (though not placing it on the pasteboard in a Cut operation). A smart insertion of a word between another word and a comma adds a space between the two words to protect that boundary. NSTextView automatically uses smart insertion and deletion by default; you can turn this behavior off using setSmartInsertDeleteEnabled:. Doing so causes only the selected text to be deleted, and inserted text to be added, with no addition of white space.

If your subclass of NSTextView defines any methods that insert or delete text, you can make them smart by taking advantage of two NSTextView methods. The smartDeleteRangeForProposedRange: method expands a proposed deletion range to include any white space that should also be deleted. If you need to save the deleted text, however, it’s typically best to save only the text from the original range. For smart insertion, smartInsertForString:replacingRange:beforeString:afterString: returns by reference two strings that you can insert before and after a given string to preserve spacing and punctuation. See the method descriptions for more information.

Implementing Text Input Support

Custom Cocoa views can provide varying levels of support for the text input system. There are essentially three levels of support to choose from:

1. Override the keyDown: method.

2. Override keyDown: and use handleEvent: to support key bindings.

3. Also implement the full NSTextInputClient protocol.

In the first level of support, the keyDown: method recognizes a limited set of events and ignores others. This level of support is typical of games. (When overriding keyDown:, you must also override acceptsFirstResponder to make your custom view respond to key events, as described in “Event Handling Basics” in Cocoa Event Handling Guide.)

In the second level of support, you can override keyDown: and use the handleEvent: method to receive key-binding support without implementing the NSTextInputClient protocol. Because the NSView method inputContext does not instantiate NSTextInputContext automatically if the view does not conform to NSTextInputClient, the custom view must instantiate it manually. You then implement the standard key-binding methods that your view wants to support, such as moveForward: or deleteForward:. (The full list of key-binding methods can be found in NSResponder.h.)

If you are writing your own text view from scratch, you should use the third level of support and implement the NSTextInputClient protocol in addition to overriding keyDown: and using handleEvent:. NSTextView and its subclasses are the only classes provided in Cocoa that implement NSTextInputClient, and if your application needs more complex behavior than NSTextView can provide, as a word processor might, you may need to implement a text view from the ground up. To do this, you must subclass NSView and implement the NSTextInputClient protocol. (A class implementing this protocol—by inheriting from NSTextView or by implementing the protocol directly—is called a text view.)

If you are implementing the NSTextInputClient protocol, your view needs to manage marked text and communicate with the text input context to support the text input system. These tasks are described in the next two sections.

Managing Marked Text

One of the primary things that a text view must do to cooperate with an input context is to maintain a (possibly empty) range of marked text within its text storage. The text view should highlight text in this range in a distinctive way, and it should allow selection within the marked text. A text view must also maintain an insertion point, which is usually at the end of the marked text, but the user can place it within the marked text. The text view also maintains a (possibly empty) selection range within its text storage, and if there is any marked text, the selection must be entirely within the marked text.

A common example of marked text appears when a user enters a character with multiple keystrokes, such as “é”, in an NSTextView object. To enter this character, the user needs to type Option-E followed by the E key. After pressing Option-E, the accent mark appears in a highlighted box, indicating that the text is marked (not final). After the final E is pressed, the “é” character appears and the highlight disappears.

Communicating with the Text Input Context

A text view and a text input context must cooperate so that the input context can implement its user interface. The NSTextInputContext class represents the interface to the text input system, that is, a state or context unique to its client object such as the key binding state, input method communication session, and so on. Most of the NSTextInputClient protocol methods are called by an input context to manipulate text within the text view for the input context’s user-interface purposes.

Each NSTextInputClient-compliant object (typically an NSView subclass) has its own NSTextInputContext instance. The default implementation of the NSView method inputContext manages an NSTextInputContext instance automatically if the view subclass conforms to the NSTextInputClient protocol.

A text view must inform the current input manager when a mouse or keyboard event happens by sending the handleEvent: message to the current input context. When its marked text range is no longer needed, the text view sends a discardMarkedText message to the current input context.

In addition, a text view must tell the input context when position information for a character range changes, such as when the text view scrolls, by sending the invalidateCharacterCoordinates message to the input context. The input context can then update information previously queried via methods like firstRectForCharacterRange:actualRange: when, for example, it wants to show a selection pop-up menu for marked text (as with a Japanese input method). There is an optional method, drawsVerticallyForCharacterAtIndex:, that can inform the text input system whether the protocol-conforming client renders the character at the given index vertically.

The input context generally uses all of the methods in the NSTextInputClient protocol. You can also register to receive a notification from the input context when the keyboard layout changes.

For more information, refer to NSText Class Reference, NSTextView Class Reference, NSView Class Reference, NSTextInputContext Class Reference, and NSTextInputClient Protocol Reference.

How the Field Editor Works

The text system automatically instantiates the field editor from the NSTextView class when the user begins editing text of an NSControl object such as a text field. While it is editing, the system inserts the field editor into the responder chain as first responder, so it receives keystroke events in place of the text field or other control object. When the focus shifts to another text field, the field editor attaches itself to that field instead. The field editor designates the current text field as its delegate, which enables the text field to control changes to its contents. This mechanism can be confusing if you’re not familiar with the workings of the field editor, because the NSWindow method firstResponder returns the field editor, which is not visible, rather than the onscreen object that currently has keyboard focus.

Among its other duties, the field editor maintains the selection for the text fields it edits. Therefore, a text field that's not being edited does not have a selection (unless you cache it).

A field editor is defined by its treatment of certain characters during text input, which is different from an ordinary text view. An ordinary text view inserts a newline when the user presses Return or Enter, it inserts a tab character when the user presses Tab, and it ignores a Shift-Tab. In contrast, a field editor interprets these characters as cues to end editing and resign first responder status, shifting focus to the next object in the key-view loop (or in the case of Shift-Tab, the previous key view).

The end of editing triggers synchronization of the contents of the field editor and the NSTextFieldCell object that controls editing in the text field. At that point Cocoa detaches the field editor from the text field and reveals the text field at the top of the view hierarchy.

Using Delegation and Notification with the Field Editor

One of the ways you can control the editing behavior of text fields is by interacting with the field editor through delegation and notification. Because the field editor automatically designates any text field it is editing as its delegate, you can often encapsulate special editing behavior for a text field with the text field itself.

- (BOOL)control:(NSControl *)control textView:(NSTextView *)fieldEditor

                                    doCommandBySelector:(SEL)commandSelector {

     BOOL retval = NO;

     if (commandSelector == @selector(insertNewline:)) {

         retval = YES;

         [fieldEditor insertNewlineIgnoringFieldEditor:nil];

     }

     return retval;

}

Using a Custom Field Editor

To customize behavior in ways that go beyond what the delegate can do, you need to define a subclass of NSTextView that incorporates your specialized behavior and substitute it for the window’s default field editor.

- (id)windowWillReturnFieldEditor:(NSWindow *)sender toObject:(id)anObject

{

    if ([anObject isKindOfClass:[CustomTextField class]])

    {

        if (!myCustomFieldEditor) {

        myCustomFieldEditor = [[CustomFieldEditor alloc] init];

        [myCustomFieldEditor setFieldEditor:YES];

        }

        return myCustomFieldEditor;

    }

    return nil;

}

Field Editor–Related Methods

This section lists the AppKit methods most directly related to the field editor. You can peruse these tables to understand where Cocoa provides opportunities for you to interact with the field editor. Refer to Application Kit Framework Reference for details. The NSWindow methods related to the field editor are listed in Table 7-1.

The NSTextFieldCell method related to the field editor is listed in Table 7-2.

The NSCell methods related to the field editor are listed in Table 7-3.

The NSControl methods related to the field editor are listed in Table 7-4. The NSControl delegate methods listed in Table 7-4 are control-specific versions of the delegate methods and notifications defined by NSText. The field editor, derived from NSText, initiates sending the delegate messages and notifications through its editing actions.

The NSResponder methods related to the field editor are listed in Table 7-5.

The NSText and NSTextDelegate methods related to the field editor are listed in Table 7-6.