Changing Default Behavior

It’s straightforward to change the default behavior of the field editor by implementing delegate methods. For example, the delegate can change the behavior that occurs when the user presses Return while editing a text view. By default, that action ends editing and selects the next control in the key view loop. If, for example, you want pressing Return to end editing but not select the next control, you can implement the textDidEndEditing: delegate method in the text field. The field editor automatically calls this method, if the delegate implements it, and passes NSTextDidEndEditingNotification. The implementation can examine this notification to discover the event that ended editing and respond appropriately.

Getting Newlines into an NSTextField Object

Users can easily put newline characters into a text field by pressing Option-Return or Option-Enter. However, there may be situations in which you want to allow users to enter newlines without taking any special action, and you can do so by implementing a delegate method.

The easiest approach is to call setFieldEditor:NO on the window's field editor. But, of course, this approach changes the behavior of the field editor for all controls. It looks promising to use the NSControl delegate message control:textShouldBeginEditing:, which is sent to a text view’s delegate when the user enters a character into the text field. Because it passes references to both the text view and the field editor, you could test to see if the text view is one into which you want to enter newlines, then simply send setFieldEditor:NO to the field editor. However, this method is not called until after the user has entered one character into the text field, and if that character is a newline, it is rejected.

A better method is to implement another NSControl delegate method, control:textView:doCommandBySelector:, that enables the text field’s delegate to check whether the user is attempting to insert a newline character and, if so, force to field editor to insert it. The implementation could appear as shown in Listing 1.

Listing 1  Forcing the field editor to enter a newline character

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

                                    doCommandBySelector:(SEL)commandSelector {

     BOOL retval = NO;

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

         retval = YES;

         [fieldEditor insertNewlineIgnoringFieldEditor:nil];

     }

     return retval;

}

This method returns YES to indicate that it handles this particular command and NO for other commands that it doesn’t handle. This approach has the advantage that it doesn’t change the setup of the field editor but handles just the special case of interest. Because the delegate message includes a reference to the control being edited, you could add a check to restrict the behavior to a particular class, such as NSTextField, or an individual subclass.

Why Use a Custom Field Editor?

It’s not necessary to use a custom field editor if you simply need to validate, interpret, format, or even edit the contents of text fields as the user types. You can attach an NSFormatter, such as NSNumberFormatter, NSDateFormatter, or a custom formatter, for that purpose. See Data Formatting Guide for more information about using formatters. Delegation and notification also provide many opportunities for you to intervene, as described previously in Using Delegation and Notification With the Field Editor.

A secure text field is an example of truly specialized handling of data that goes beyond what can be reasonably handled by formatters or delegates. A secure text field must accept text data entered by the user and validate the entries, which are easily done with a regular text field and a formatter. But it must display some bogus characters to keep the real data secret while it preserves the real data for an authentication process or other purpose. Moreover, a secure text field must keep its data safe from unauthorized access by disabling features, such as copy and cut, and possibly encrypting the data. To implement these specialized requirements, it is easiest to deploy a custom field editor. In fact, Cocoa implements a custom field editor in the NSSecureTextField class.

As another example, you must use a custom field editor to support drag and drop in a text field that has keyboard focus. You can add support for drag and drop in a subclass of NSTextField itself, and it works fine as long as the text field is not currently being edited. During editing, however, the field editor becomes the first responder, so it is the target of a drop in the text field. Therefore, to handle drag and drop while the text field is being edited, you must implement support in a subclass of the field editor. This procedure is described in Handling Drops in a Text Field.

Any situation requiring unusual processing of data entered into a text field, or other individualized behavior not available through the standard Cocoa mechanisms, is a good candidate for a custom field editor.

How to Substitute a Custom Field Editor

You can substitute your custom field editor in place of the window’s default version by implementing the NSWindow delegate method windowWillReturnFieldEditor:toObject:. You implement this method in the window’s delegate, which could be, for example, the window controller object. The window sends this message to its delegate with itself and the object requesting the field editor as arguments. So, you can test the object and make substitution of your custom field editor dependent on the result. The window continues to use its default field editor for other controls.

For example, the implementation shown in Listing 2 tests whether or not the requesting object is an NSTextField, and, if it is, returns a custom field editor.

Listing 2  Substituting a custom field editor

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

{

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

    {

        if (!myCustomFieldEditor) {

        myCustomFieldEditor = [[CustomFieldEditor alloc] init];

        [myCustomFieldEditor setFieldEditor:YES];

        }

        return myCustomFieldEditor;

    }

    return nil;

}

If the requesting object is not a text field or subclass, the delegate method returns nil and the window uses its default field editor. This arrangement has the advantage that it does not instantiate the custom field editor unless it is needed. The custom field editor should be released in an appropriate place, such as the dealloc method of the window delegate object (if the field editor was never instantiated, the release message has no effect and is harmless).

In OS X v10.6 and later, another way of providing a custom field editor is to override the NSCell method fieldEditorForView:. This method, rather than the window delegate method, is more suitable for custom cell subclasses.

You can find more information about subclassing NSTextView in Subclassing NSTextView.