NSEditor Protocol Reference

(informal protocol)

Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.3 and later.
Companion guide
Declared in
NSKeyValueBinding.h

Overview

The NSEditor informal protocol is implemented by controllers and user interface elements. It provides a means for requesting that the receiver commit or discard any pending edits.

These methods are typically invoked on user interface elements by a controller. They can also be sent to a controller in response to a user’s attempt to save a document or quit an application.

NSController provides an implementation of this protocol, as do the Application Kit user interface elements that support binding.

Tasks

Managing Editing

Instance Methods

commitEditing

Returns whether the receiver was able to commit any pending edits.

- (BOOL)commitEditing
Return Value

YES if the changes were successfully applied to the model, NO otherwise.

Discussion

A commit is denied if the receiver fails to apply the changes to the model object, perhaps due to a validation error.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSKeyValueBinding.h

commitEditingAndReturnError:

Attempt to commit pending edits, returning an error in the case of failure.

- (BOOL)commitEditingAndReturnError:(NSError **)error
Parameters
error

If an error occurs during the commit operation, upon returns contains an NSError object that describes the problem.

Return Value

YES if the commit is successful, otherwise NO.

Discussion

During autosaving, commit editing may fail, due to a pending edit. Rather than interrupt the user with an unexpected alert, this method provides the caller with the option to either present the error or fail silently, leaving the pending edit in place and the user's editing uninterrupted. In your implementation of this method, you should attempt to commit editing, but if there is a failure return NO and in error an error object to be presented or ignored as appropriate.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSKeyValueBinding.h

commitEditingWithDelegate:didCommitSelector:contextInfo:

Attempt to commit any currently edited results of the receiver.

- (void)commitEditingWithDelegate:(id)delegate didCommitSelector:(SEL)didCommitSelector contextInfo:(void *)contextInfo
Discussion

The receiver must have been registered as the editor of an object using objectDidBeginEditing:, and has not yet been unregistered by a subsequent invocation of objectDidEndEditing:. When the committing has either succeeded or failed, send the following message to the specified object. The didCommitSelector method must have the following method signature:

- (void)editor:(id)editor didCommit:(BOOL)didCommit contextInfo:(void *)contextInfo

If an error occurs while attempting to commit, for example if key-value coding validation fails, an implementation of this method should typically send the NSView in which editing is being done a presentError:modalForWindow:delegate:didRecoverSelector:contextInfo: message, specifying the view's containing window.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSKeyValueBinding.h

discardEditing

Causes the receiver to discard any changes, restoring the previous values.

- (void)discardEditing
Availability
  • Available in OS X v10.3 and later.
Declared In
NSKeyValueBinding.h