NSControlTextEditingDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Companion guide
Declared in
NSControl.h
Related sample code

Overview

The NSControlTextEditingDelegate protocol defines the optional methods implemented by delegates of objects that are subclasses of NSControl.

Tasks

Validating a Control’s Value

Responding to Text Formatting

Responding to Text Editing

Working with Text Completion

Working with Key Bindings

Instance Methods

control:didFailToFormatString:errorDescription:

Invoked when the formatter for the cell belonging to the specified control cannot convert a string to an underlying object.

- (BOOL)control:(NSControl *)control didFailToFormatString:(NSString *)string errorDescription:(NSString *)error
Parameters
control

The control whose cell could not convert the string.

string

The string that could not be converted.

error

A localized, user-presentable string that explains why the conversion failed.

Return Value

YES if the value in the string parameter should be accepted as is; otherwise, NO if the value in the parameter should be rejected.

Discussion

Your implementation of this method should evaluate the error or query the user an appropriate value indicating whether the string should be accepted or rejected.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSControl.h

control:didFailToValidatePartialString:errorDescription:

Invoked when the formatter for the cell belonging to control (or selected cell) rejects a partial string a user is typing into the cell.

- (void)control:(NSControl *)control didFailToValidatePartialString:(NSString *)string errorDescription:(NSString *)error
Parameters
control

The control whose cell rejected the string.

string

The string that includes the character that caused the rejection.

error

A localized, user-presentable string that explains why the string was rejected.

Discussion

You can implement this method to display a warning message or perform a similar action when the user enters improperly formatted text.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSControl.h

control:isValidObject:

Invoked when the insertion point leaves a cell belonging to the specified control, but before the value of the cell’s object is displayed.

- (BOOL)control:(NSControl *)control isValidObject:(id)object
Parameters
control

The control whose object value needs to be validated.

object

The object value to validate.

Return Value

YES if you want to allow the control to display the specified value; otherwise, NO to reject the value and return the cursor to the control's cell.

Discussion

This method gives the delegate the opportunity to validate the contents of the control’s cell (or selected cell). In validating, the delegate should check the value in the object parameter and determine if it falls within a permissible range, has required attributes, accords with a given context, and so on. Examples of objects subject to such evaluations are an NSDate object that should not represent a future date or a monetary amount (represented by an NSNumber object) that exceeds a predetermined limit.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSControl.h

control:textShouldBeginEditing:

Invoked when the user tries to enter a character in a cell of a control that allows editing of text (such as a text field or form field).

- (BOOL)control:(NSControl *)control textShouldBeginEditing:(NSText *)fieldEditor
Parameters
control

The control whose content is about to be edited.

fieldEditor

The field editor of the control.

Return Value

YES if the control's field editor should be allowed to start editing the text; otherwise, NO.

Discussion

You can use this method to allow or disallow editing in a control. This message is sent by the control directly to its delegate object.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSControl.h

control:textShouldEndEditing:

Invoked when the insertion point tries to leave a cell of the control that has been edited.

- (BOOL)control:(NSControl *)control textShouldEndEditing:(NSText *)fieldEditor
Parameters
control

The control for which editing is about to end.

fieldEditor

The field editor of the control. You can use this parameter to get the edited text.

Return Value

YES if the insertion point should be allowed to end the editing session; otherwise, NO.

Discussion

This message is sent only by controls that allow editing of text (such as a text field or a form field). This message is sent by the control directly to its delegate object.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSControl.h

control:textView:completions:forPartialWordRange:indexOfSelectedItem:

Invoked to allow you to control the list of proposed text completions generated by text fields and other controls.

- (NSArray *)control:(NSControl *)control textView:(NSTextView *)textView completions:(NSArray *)words forPartialWordRange:(NSRange)charRange indexOfSelectedItem:(NSInteger *)index
Parameters
control

The control whose cell initiated the message. If the control contains multiple cells, the one that initiated the message is usually the selected cell.

textView

The field editor of the control. You can use this parameter to get the typed text.

words

An array of NSString objects containing the potential completions. The completion strings are listed in their order of preference in the array.

charRange

The range of characters the user has already typed.

index

On input, an integer variable with the default value of 0. On output, you can set this value to an index in the returned array indicating which item should be selected initially. Set the value to -1 to indicate there should not be an initial selection.

Return Value

An array of NSString objects containing the list of completions to use in place of the array in the words parameter. The returned array should list the completions in their preferred order

Discussion

Each string you return should be a complete word that the user might be trying to type. The strings must be complete words rather than just the remainder of the word, in case completion requires some slight modification of what the user has already typed—for example, the addition of an accent, or a change in capitalization. You can also use this method to support abbreviations that complete into words that do not start with the characters of the abbreviation. The index argument allows you to return by reference an index specifying which of the completions should be selected initially.

The actual means of presentation of the potential completions is determined by the complete: method of NSTextView.

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSControl.h

control:textView:doCommandBySelector:

Invoked when users press keys with predefined bindings in a cell of the specified control.

- (BOOL)control:(NSControl *)control textView:(NSTextView *)textView doCommandBySelector:(SEL)command
Parameters
control

The control whose cell initiated the message. If the control contains multiple cells, the one that initiated the message is usually the selected cell.

textView

The field editor of the control.

command

The selector that was associated with the binding.

Return Value

YES if the delegate object handles the key binding; otherwise, NO.

Discussion

These bindings are usually implemented as methods (command) defined in the NSResponder class; examples of such key bindings are arrow keys (for directional movement) and the Escape key (for name completion). By implementing this method, the delegate can override the default implementation of command and supply its own behavior.

For example, the default method for completing partially typed pathnames or symbols (usually when users press the Escape key) is complete:. The default implementation of the complete: method (in NSResponder) does nothing. The delegate could evaluate the method in the command parameter and, if it’s complete:, get the current string from the textView parameter and then expand it, or display a list of potential completions, or do whatever else is appropriate.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSControl.h