Mac Developer Library

Developer

AppKit Framework Reference NSControlTextEditingDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSControlTextEditingDelegate

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

Inheritance


Not Applicable

Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.6 and later.
  • Invoked when the insertion point leaves a cell belonging to the specified control, but before the value of the cell’s object is displayed.

    Declaration

    Swift

    optional func control(_ control: NSControl, isValidObject object: AnyObject) -> Bool

    Objective-C

    - (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

    YEStrue if you want to allow the control to display the specified value; otherwise, NOfalse 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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

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

    Declaration

    Swift

    optional func control(_ control: NSControl, didFailToValidatePartialString string: String, errorDescription error: String?)

    Objective-C

    - (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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

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

    Declaration

    Swift

    optional func control(_ control: NSControl, didFailToFormatString string: String, errorDescription error: String?) -> Bool

    Objective-C

    - (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

    YEStrue if the value in the string parameter should be accepted as is; otherwise, NOfalse 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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • 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).

    Declaration

    Swift

    optional func control(_ control: NSControl, textShouldBeginEditing fieldEditor: NSText) -> Bool

    Objective-C

    - (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

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

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

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

    Declaration

    Swift

    optional func control(_ control: NSControl, textShouldEndEditing fieldEditor: NSText) -> Bool

    Objective-C

    - (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

    YEStrue if the insertion point should be allowed to end the editing session; otherwise, NOfalse.

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

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

    Declaration

    Swift

    optional func control(_ control: NSControl, textView textView: NSTextView, completions words: [AnyObject], forPartialWordRange charRange: NSRange, indexOfSelectedItem index: UnsafeMutablePointer<Int>) -> [AnyObject]

    Objective-C

    - (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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.

    See Also

    – complete: (NSTextView)

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

    Declaration

    Swift

    optional func control(_ control: NSControl, textView textView: NSTextView, doCommandBySelector command: Selector) -> Bool

    Objective-C

    - (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

    YEStrue if the delegate object handles the key binding; otherwise, NOfalse.

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.