Struct NSWritingToolsCoordinator

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

Available on crate feature NSWritingToolsCoordinator only.

An object that manages interactions between Writing Tools and your custom text view.

Add a NSWritingToolsCoordinator object to a custom view when you want to add Writing Tools support to that view. The coordinator manages interactions between your view and the Writing Tools UI and back-end capabilities. When creating a coordinator, you supply a delegate object to respond to requests from the system and provide needed information. Your delegate delivers your view’s text to Writing Tools, incorporates suggested changes back into your text storage, and supports the animations that Writing Tools creates to show the state of an operation.

Create the NSWritingToolsCoordinator object when setting up your UI, and initialize it with a custom object that adopts the NSWritingToolsCoordinator/Delegate protocol. Add the coordinator to the NSView/writingToolsCoordinator property of your view. When a coordinator is present on a view, the system adds UI elements to initiate Writing Tools operations.

When defining the delegate, choose an object from your app that has access to your view and its text storage. You can adopt the NSWritingToolsCoordinator/Delegate protocol in the view itself, or in another type that your view uses to manage content. During the interactions with Writing Tools, the delegate gets and sets the contents of the view’s text storage and supports Writing Tools behaviors.

Note: You don’t need to create an NSWritingToolsCoordinator object if you display text using a <doc ://com.apple.documentation/documentation/uikit/uitextview>, NSTextField, NSTextView, <doc ://com.apple.documentation/documentation/swiftui/textfield>, or <doc ://com.apple.documentation/documentation/swiftui/texteditor> view. Those views already include the required support to handle Writing Tools interactions.

See also Apple’s documentation

Implementations

impl NSWritingToolsCoordinator

pub unsafe fn isWritingToolsAvailable(mtm: MainThreadMarker) -> bool

A Boolean value that indicates whether Writing Tools features are currently available.

The value of this property is true when Writing Tools features are available, and false when they aren’t. Writing Tools support might be unavailable because of device constraints or because the system isn’t ready to process Writing Tools requests.

pub unsafe fn initWithDelegate( this: Allocated<Self>, delegate: Option<&ProtocolObject<dyn NSWritingToolsCoordinatorDelegate>>, ) -> Retained<Self>

Creates a writing tools coordinator and assigns the specified delegate object to it.

• Parameters:
• delegate: An object capable of handling Writing Tools interactions for your view. The delegate must be able to modify your view’s text storage and refresh the view’s layout and appearance.

Create the coordinator object during your view’s initialization, and assign the object to your view. Assign the coordinator to the NSView/writingToolsCoordinator property of your view.

pub unsafe fn delegate( &self, ) -> Option<Retained<ProtocolObject<dyn NSWritingToolsCoordinatorDelegate>>>

The object that handles Writing Tools interactions for your view.

Specify this object at initialization time when creating your NSWritingToolsCoordinator object. The object must adopt the NSWritingToolsCoordinator/Delegate protocol, and be capable of modifying your view’s text storage and refreshing the view’s layout and appearance.

pub unsafe fn view(&self) -> Option<Retained<NSView>>

Available on crate features NSResponder and NSView only.

The view that currently uses the writing tools coordinator.

Use this property to refer to the view that currently owns the coordinator object. The system updates this property automatically when you assign the coordinator to the NSView/writingToolsCoordinator property of your view. The value of this property is nil if there is no associated view.

pub unsafe fn effectContainerView(&self) -> Option<Retained<NSView>>

Available on crate features NSResponder and NSView only.

The view that Writing Tools uses to display visual effects during the text-rewriting process.

Writing Tools uses the view in this property to host the visual effects it creates when making interactive changes to your view’s content. These visual effects let people know the state of the text and provide feedback about what’s happening to it. Set this property to a subview that sits visually above, and covers, all of the text in your custom text view. If you don’t assign a value to this property, the coordinator places its own effect view in front of the subviews in your custom view. The default value of this property is nil.

If you display your view’s text using multiple text containers, implement the NSWritingToolsCoordinator/Delegate/writingToolsCoordinator(_:singleContainerSubrangesOf:in:) method to request multiple previews.

pub unsafe fn setEffectContainerView( &self, effect_container_view: Option<&NSView>, )

Available on crate features NSResponder and NSView only.

This is a weak property. Setter for effectContainerView.

pub unsafe fn decorationContainerView(&self) -> Option<Retained<NSView>>

Available on crate features NSResponder and NSView only.

The view that Writing Tools uses to display background decorations such as proofreading marks.

Writing Tools uses the view in this property to host proofreading marks and other visual elements that show any suggested changes. Set this property to a subview situated visibly below the text in your custom text view. It’s also satisfactory to place this view visually in front of the text. Make sure the size of the view is big enough to cover all of the affected text. If you don’t assign a value to this property, the coordinator places its own decoration view behind the subviews in your custom view. The default value of this property is nil.

If you display your view’s text using multiple text containers, implement the NSWritingToolsCoordinator/Delegate/writingToolsCoordinator(_:singleContainerSubrangesOf:in:) and NSWritingToolsCoordinator/Delegate/writingToolsCoordinator(_:decorationContainerViewFor:in:) methods to provide separate decoration views for each container.

pub unsafe fn setDecorationContainerView( &self, decoration_container_view: Option<&NSView>, )

Available on crate features NSResponder and NSView only.

This is a weak property. Setter for decorationContainerView.

pub unsafe fn state(&self) -> NSWritingToolsCoordinatorState

The current level of Writing Tools activity in your view.

Use this property to determine when Writing Tools is actively making changes to your view. During the course of Writing Tools interactions, the system reports state changes to the delegate’s NSWritingToolsCoordinator/Delegate/writingToolsCoordinator(_:willChangeTo:completion:) method and updates this property accordingly.

pub unsafe fn stopWritingTools(&self)

Stops the current Writing Tools operation and dismisses the system UI.

Call this method to abort the current Writing Tools operation. This method dismisses the system’s Writing Tools UI and stops any in-flight interactions with your view. This method does not undo any changes that Writing Tools already made to your view’s content.

pub unsafe fn preferredBehavior(&self) -> NSWritingToolsBehavior

Available on crate feature NSTextCheckingClient only.

The level of Writing Tools support you want the system to provide for your view.

Use this property to request an inline or panel-based experience, or to disable Writing Tools for your view altogether. The default value of this property is NSWritingToolsBehavior/default.

pub unsafe fn setPreferredBehavior( &self, preferred_behavior: NSWritingToolsBehavior, )

Available on crate feature NSTextCheckingClient only.

Setter for preferredBehavior.

pub unsafe fn behavior(&self) -> NSWritingToolsBehavior

Available on crate feature NSTextCheckingClient only.

The actual level of Writing Tools support the system provides for your view.

The system chooses this value based on the device capabilities, and takes the value in the preferredBehavior property into consideration when making the choice. The value in this property is never the default option, and is instead one of the specific options such as NSWritingToolsBehavior/none, NSWritingToolsBehavior/limited, or NSWritingToolsBehavior/complete.

pub unsafe fn preferredResultOptions(&self) -> NSWritingToolsResultOptions

Available on crate feature NSTextCheckingClient only.

The type of content you allow Writing Tools to generate for your custom text view.

Writing Tools can create plain text or rich text, and it can format text using lists or tables as needed. If your view doesn’t support specific types of content, specify the types you do support in this property. The default value of this property is NSWritingToolsResult/default, which lets the system determine the type of content to generate.

pub unsafe fn setPreferredResultOptions( &self, preferred_result_options: NSWritingToolsResultOptions, )

Available on crate feature NSTextCheckingClient only.

Setter for preferredResultOptions.

pub unsafe fn resultOptions(&self) -> NSWritingToolsResultOptions

Available on crate feature NSTextCheckingClient only.

The type of content the system generates for your custom text view.

This property contains the set of options that Writing Tools outputs for your view. Writing Tools takes the value in the NSWritingToolsCoordinator/preferredResultOptions property into consideration when determining this value.

pub unsafe fn updateRange_withText_reason_forContextWithIdentifier( &self, range: NSRange, replacement_text: &NSAttributedString, reason: NSWritingToolsCoordinatorTextUpdateReason, context_id: &NSUUID, )

Informs the coordinator about changes your app made to the text in the specified context object.

• Parameters:
• range: The range of text to replace. This range is relative to the starting location of the specified context object’s text in your view’s text storage. If you initialized the context object with the entire contents of your view’s text storage, specify the range of text you’re replacing in your text storage. However, if you initialized the context object with only a portion of your view’s text, specify a range that is relative to the starting location of the context object’s text.
• replacementText: The text that replaces the previous content in range. Specify an empty string to delete the text in the specified range.
• reason: The reason you updated the text.
• contextID: The unique identifier of the context object that contains the text you modified.

If you make any changes to the text Writing Tools is evaluating, call this method to report those changes to your view’s coordinator object. You might make changes in response to an undo command or when someone types into the same part of your view’s text. Calling this method keeps the coordinator object informed of any changes, and ensures it delivers accurate information to its delegate. In response, the coordinator refreshes previews and other information related to your view. If the scope of the update is significantly large, the coordinator can optionally cancel the Writing Tools session altogether.

Use this method to report changes that precisely intersect your context object’s text. The first time you call this method for a context object, report changes only to the original attributed string in that object. If you call this method more than once, report changes to the newly modified version of that string. Don’t use this method to report changes to text that comes before or after the context object. If you make changes before your context object, report those changes separately using the updateForReflowedTextInContextWithIdentifier(_:) method.

Warning: Failure to call this method for a change can cause Writing Tools to deliver inaccurate information to your delegate and lead to data loss.

pub unsafe fn updateForReflowedTextInContextWithIdentifier( &self, context_id: &NSUUID, )

Informs the coordinator that a change occurred to the view or its text that requires a layout update.

• Parameters:
• contextID: The unique identifier of the context object affected by the change. Pass the identifier for the context object that comes after the changes.

Use this method to inform Writing Tools when the geometry of your view changes, or when the text that precedes one of your context objects changes. Changes to the view’s geometry or text can affect the flow of any remaining text, and require a layout update. Writing Tools uses this method to refresh any layout-dependent information it’s currently tracking. For example, it uses it to refresh the location of proofreading marks it’s displaying in your view.

If a text change affects the text inside a context object, call the updateRange(_:with:reason:forContextWithIdentifier:) method to report that change instead.

impl NSWritingToolsCoordinator

Methods declared on superclass NSObject.

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

pub unsafe fn new(mtm: MainThreadMarker) -> 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

Available on crate feature NSAccessibilityConstants only.

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.

Available on crate feature NSAccessibilityConstants only.

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,

Available on crate feature NSAccessibilityConstants only.

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 NSWritingToolsCoordinator

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for NSWritingToolsCoordinator

fn as_ref(&self) -> &NSObject

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

impl AsRef<NSWritingToolsCoordinator> for NSWritingToolsCoordinator

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for NSWritingToolsCoordinator

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSWritingToolsCoordinator

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for NSWritingToolsCoordinator

const NAME: &'static str = "NSWritingToolsCoordinator"

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

type Super = NSObject

The superclass of this class.

type ThreadKind = dyn MainThreadOnly

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 NSWritingToolsCoordinator

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

Formats the value using the given formatter.

impl Deref for NSWritingToolsCoordinator

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for NSWritingToolsCoordinator

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 NSWritingToolsCoordinator

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for NSWritingToolsCoordinator

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 NSWritingToolsCoordinator

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 NSWritingToolsCoordinator

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

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

impl DowncastTarget for NSWritingToolsCoordinator

impl Eq for NSWritingToolsCoordinator