Struct NSUndoManager

#[repr(C)]
pub struct NSUndoManager { /* private fields */ }

Available on crate feature NSUndoManager only.

Apple’s documentation

Implementations

impl NSUndoManager

pub unsafe fn beginUndoGrouping(&self)

Marks the beginning of an undo group.

All individual undo operations before a subsequent endUndoGrouping message are grouped together and reversed by a later undo message. By default undo groups are begun automatically at the start of the event loop, but you can begin your own undo groups with this method, and nest them within other groups.

This method posts an NSUndoManagerCheckpointNotification unless a top-level undo is in progress. It posts an NSUndoManagerDidOpenUndoGroupNotification if a new group was successfully created.

pub unsafe fn endUndoGrouping(&self)

Marks the end of an undo group.

All individual undo operations back to the matching beginUndoGrouping message are grouped together and reversed by a later undo or undoNestedGroup message. Undo groups can be nested, thus providing functionality similar to nested transactions. Raises an NSInternalInconsistencyException if there’s no beginUndoGrouping message in effect.

This method posts an NSUndoManagerCheckpointNotification and an NSUndoManagerDidCloseUndoGroupNotification just before the group is closed.

pub unsafe fn groupingLevel(&self) -> NSInteger

The number of nested undo groups (or redo groups, if Redo was invoked last) in the current event loop.

An integer indicating the number of nested groups. If 0 is returned, there is no open undo or redo group.

pub unsafe fn disableUndoRegistration(&self)

Disables the recording of undo operations, whether by registerUndoWithTarget:selector:object: or by invocation-based undo.

This method can be invoked multiple times by multiple clients. The enableUndoRegistration method must be invoked an equal number of times to re-enable undo registration.

pub unsafe fn enableUndoRegistration(&self)

Enables the recording of undo operations.

Because undo registration is enabled by default, this is used to balance a prior disableUndoRegistration. Undo registration isn’t actually re-enabled until an enable message balances the last disable message in effect. Raises an NSInternalInconsistencyException if invoked while no disableUndoRegistration() message is in effect.

pub unsafe fn isUndoRegistrationEnabled(&self) -> bool

Whether the recording of undo operations is enabled.

pub unsafe fn groupsByEvent(&self) -> bool

A Boolean value that indicates whether the receiver automatically creates undo groups around each pass of the run loop.

If true, the receiver automatically creates undo groups around each pass of the run loop. The default is true. If you turn automatic grouping off, you must close groups explicitly before invoking either undo or undoNestedGroup.

pub unsafe fn setGroupsByEvent(&self, groups_by_event: bool)

Setter for groupsByEvent.

pub unsafe fn levelsOfUndo(&self) -> NSUInteger

The maximum number of top-level undo groups the receiver holds.

An integer specifying the number of undo groups. A limit of 0 indicates no limit, so old undo groups are never dropped. When ending an undo group results in the number of groups exceeding this limit, the oldest groups are dropped from the stack. The default is 0. If you change the limit to a level below the prior limit, old undo groups are immediately dropped.

pub unsafe fn setLevelsOfUndo(&self, levels_of_undo: NSUInteger)

Setter for levelsOfUndo.

pub unsafe fn runLoopModes(&self) -> Retained<NSArray<NSRunLoopMode>>

Available on crate features NSArray and NSObjCRuntime and NSString only.

The modes governing the types of input handled during a cycle of the run loop.

An array of string constants specifying the current run-loop modes. By default, the sole run-loop mode is NSDefaultRunLoopMode (which excludes data from NSConnection objects). Some examples of other uses are to limit the input to data received during a mouse-tracking session by setting the mode to NSEventTrackingRunLoopMode, or limit it to data received from a modal panel with NSModalPanelRunLoopMode.

pub unsafe fn setRunLoopModes(&self, run_loop_modes: &NSArray<NSRunLoopMode>)

Available on crate features NSArray and NSObjCRuntime and NSString only.

Setter for runLoopModes.

pub unsafe fn undo(&self)

Closes the top-level undo group if necessary and invokes undoNestedGroup.

This method also invokes endUndoGrouping if the nesting level is 1. Raises an NSInternalInconsistencyException if more than one undo group is open (that is, if the last group isn’t at the top level). This method posts an NSUndoManagerCheckpointNotification.

pub unsafe fn redo(&self)

Performs the operations in the last group on the redo stack, if there are any, recording them on the undo stack as a single group.

Raises an NSInternalInconsistencyException if the method is invoked during an undo operation. This method posts an NSUndoManagerCheckpointNotification and NSUndoManagerWillRedoChangeNotification before it performs the redo operation, and it posts the NSUndoManagerDidRedoChangeNotification after it performs the redo operation.

pub unsafe fn undoNestedGroup(&self)

Performs the undo operations in the last undo group (whether top-level or nested), recording the operations on the redo stack as a single group.

Raises an NSInternalInconsistencyException if any undo operations have been registered since the last enableUndoRegistration message. This method posts an NSUndoManagerCheckpointNotification and NSUndoManagerWillUndoChangeNotification before it performs the undo operation, and it posts an NSUndoManagerDidUndoChangeNotification after it performs the undo operation.

pub unsafe fn canUndo(&self) -> bool

Whether the receiver has any actions to undo.

The return value does not mean you can safely invoke undo or undoNestedGroup — you may have to close open undo groups first.

pub unsafe fn canRedo(&self) -> bool

Whether the receiver has any actions to redo.

Because any undo operation registered clears the redo stack, this method posts an NSUndoManagerCheckpointNotification to allow clients to apply their pending operations before testing the redo stack.

pub unsafe fn undoCount(&self) -> NSUInteger

How many times undo can be invoked before there are no more actions left to be undone

pub unsafe fn redoCount(&self) -> NSUInteger

How many times redo can be invoked before there are no more actions left to be redone

pub unsafe fn isUndoing(&self) -> bool

Whether the receiver is in the process of performing its undo or undoNestedGroup method.

pub unsafe fn isRedoing(&self) -> bool

Whether the receiver is in the process of performing its redo method.

pub unsafe fn removeAllActions(&self)

Clears the undo and redo stacks and re-enables the receiver.

pub unsafe fn removeAllActionsWithTarget(&self, target: &AnyObject)

Clears the undo and redo stacks of all operations involving the specified target as the recipient of the undo message.

Doesn’t re-enable the receiver if it’s disabled.

• Parameter target: The recepient of the undo mesages to be removed.

pub unsafe fn registerUndoWithTarget_selector_object( &self, target: &AnyObject, selector: Sel, object: Option<&AnyObject>, )

Registers the selector of the specified target to implement a single undo operation that the target receives.

• Parameter target: The target of the undo operation. The undo manager maintains an unowned reference to target to prevent retain cycles.
• Parameter selector: The selector for the undo operation.
• Parameter object: The argument sent with the selector. The undo manager maintains a strong reference to object

pub unsafe fn prepareWithInvocationTarget( &self, target: &AnyObject, ) -> Retained<AnyObject>

Prepares the undo manager for invocation-based undo with the given target as the subject of the next undo operation.

For example, when called as:

[[undoManager prepareWithInvocationTarget:target] setFont:oldFont color:oldColor]

When undo is called, the specified target will be called with

[target setFont:oldFont color:oldColor]

• Parameter target: The target of the undo operation. The undo manager maintains a weak reference to target.
• Returns: A proxy object that forwards messages to the undo manager for recording as undo actions.

pub unsafe fn registerUndoWithTarget_handler( &self, target: &AnyObject, undo_handler: &DynBlock<dyn Fn(NonNull<AnyObject>)>, )

Available on crate feature block2 only.

Records a single undo operation for a given target so that when an undo is performed, it executes the specified block.

As with other undo operations, this does not strongly retain target. Care should be taken to avoid introducing retain cycles by other references captured by the block.

• Parameter target: The target of the undo operation.
• Parameter undoHandler: The block to be executed when an operation is undone. The block takes a single argument, the target of the undo operation.

pub unsafe fn setActionIsDiscardable(&self, discardable: bool)

Sets whether the next undo or redo action is discardable.

Specifies that the latest undo action may be safely discarded when a document can not be saved for any reason. An example might be an undo action that changes the viewable area of a document. To find out if an undo group contains only discardable actions, look for the NSUndoManagerGroupIsDiscardableKey in the userInfo dictionary of the NSUndoManagerWillCloseUndoGroupNotification.

• Parameter discardable: Specifies if the action is discardable. YES if the next undo or redo action can be discarded; NO otherwise.

pub unsafe fn undoActionIsDiscardable(&self) -> bool

Whether the next undo action is discardable.

Specifies that the latest undo action may be safely discarded when a document can not be saved for any reason. These are typically actions that don’t affect persistent state. An example might be an undo action that changes the viewable area of a document.

pub unsafe fn redoActionIsDiscardable(&self) -> bool

Whether the next redo action is discardable.

Specifies that the latest redo action may be safely discarded when a document can not be saved for any reason. These are typically actions that don’t affect persistent state. An example might be an redo action that changes the viewable area of a document.

pub unsafe fn undoActionName(&self) -> Retained<NSString>

Available on crate feature NSString only.

The name identifying the undo action.

The undo action name. Returns an empty string if no action name has been assigned or if there is nothing to undo. For example, if the menu title is “Undo Delete,” the string returned is “Delete.”

pub unsafe fn redoActionName(&self) -> Retained<NSString>

Available on crate feature NSString only.

The name identifying the redo action.

The redo action name. Returns an empty string if no action name has been assigned or if there is nothing to redo. For example, if the menu title is “Redo Delete,” the string returned is “Delete.”

pub unsafe fn setActionName(&self, action_name: &NSString)

Available on crate feature NSString only.

Sets the name of the action associated with the Undo or Redo command.

If actionName is an empty string, the action name currently associated with the menu command is removed. There is no effect if actionName is nil.

• Parameter actionName: The name of the action.

pub unsafe fn undoActionUserInfoValueForKey( &self, key: &NSUndoManagerUserInfoKey, ) -> Option<Retained<AnyObject>>

Available on crate feature NSString only.

Get a value from the undo action’s user info

• Parameter key: Which value should be retrieved

pub unsafe fn redoActionUserInfoValueForKey( &self, key: &NSUndoManagerUserInfoKey, ) -> Option<Retained<AnyObject>>

Available on crate feature NSString only.

Get a value from the redo action’s user info

• Parameter key: Which value should be retrieved

pub unsafe fn setActionUserInfoValue_forKey( &self, info: Option<&AnyObject>, key: &NSUndoManagerUserInfoKey, )

Available on crate feature NSString only.

Set user info for the Undo or Redo command.

• Parameter info: Value to be saved in the user info
• Parameter key: Key at which the object should be saved

pub unsafe fn undoMenuItemTitle(&self) -> Retained<NSString>

Available on crate feature NSString only.

The complete title of the Undo menu command, for example, “Undo Paste.”

Returns “Undo” if no action name has been assigned or nil if there is nothing to undo.

pub unsafe fn redoMenuItemTitle(&self) -> Retained<NSString>

Available on crate feature NSString only.

The complete title of the Redo menu command, for example, “Redo Paste.”

Returns “Redo” if no action name has been assigned or nil if there is nothing to redo.

pub unsafe fn undoMenuTitleForUndoActionName( &self, action_name: &NSString, ) -> Retained<NSString>

Available on crate feature NSString only.

Returns the complete, localized title of the Undo menu command for the action identified by the given name.

Override this method if you want to customize the localization behaviour. This method is invoked by undoMenuItemTitle.

• Parameter actionName: The name of the undo action.
• Returns: The localized title of the undo menu item.

pub unsafe fn redoMenuTitleForUndoActionName( &self, action_name: &NSString, ) -> Retained<NSString>

Available on crate feature NSString only.

Returns the complete, localized title of the Redo menu command for the action identified by the given name.

Override this method if you want to customize the localization behaviour. This method is invoked by redoMenuItemTitle.

• Parameter actionName: The name of the redo action.
• Returns: The localized title of the redo menu item.

impl NSUndoManager

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for NSUndoManager

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for NSUndoManager

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSUndoManager> for NSUndoManager

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for NSUndoManager

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSUndoManager

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for NSUndoManager

const NAME: &'static str = "NSUndoManager"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<NSUndoManager as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for NSUndoManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for NSUndoManager

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for NSUndoManager

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for NSUndoManager

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for NSUndoManager

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for NSUndoManager

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for NSUndoManager

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for NSUndoManager

impl Eq for NSUndoManager