Struct UIWritingToolsCoordinatorContext

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

Available on crate feature UIWritingToolsCoordinatorContext only.

A data object that you use to share your custom view’s text with Writing Tools.

At the start of every Writing Tools operation, you create one or more UIWritingToolsCoordinator.Context objects with a copy of the text you want Writing Tools to evaluate. Each Writing Tools operation starts with a call to the UIWritingToolsCoordinator/Delegate/writingToolsCoordinator(_:requestsContextsFor:completion:) method of your UIWritingToolsCoordinator/Delegate object. Use the parameters of that method to determine how much of your view’s text to provide. For some operations, Writing Tools asks for all of your view’s text, but in others it asks for only a portion of the text. When Writing Tools finishes its evaluation, it reports changes back to your delegate relative to the context objects you provided.

When Writing Tools asks for your view’s text, create one or more UIWritingToolsCoordinator.Context objects with the requested content. If your view contains only one text storage object, create only one context object for the request. However, if you use multiple text storage objects to manage different parts of your view’s content, you might need to create multiple context objects. The actual number depends on how much of your text Writing Tools asks for. For example, when Writing Tools asks for all of your view’s content, you return one context object for each text storage object in your view. However, if Writing Tools asks for the current selection, and one text storage object contains all of the selected text, you create only one context object for the content.

Writing Tools uses your context objects as the starting point for its evaluations, and as a reference point for any changes. Because Writing Tools doesn’t know anything about your view or its content, it makes suggestions only relative to your context objects. It’s your responsibility to take those suggestions and incorporate them back into your view’s text storage. In some cases, you might need to store additional information to update your storage correctly. For example, you might need to store, and update as needed, the offset from the start of your document to the start of the text in your context object.

When Writing Tools asks for the currently selected text in your view, include some of the surrounding text in your context object as well. Supply a string that includes the selection and any text up to the nearest paragraph boundary. When creating your context object, specify a range value that represents the portion of that string that corresponds to the text selection. Providing some additional text in your context object can help Writing Tools improve its evaluation of your content. Writing Tools uses the resolvedRange property of your context object to indicate what text it considered.

If your context object includes text that you don’t want Writing Tools to evaluate, add the excludeFromWritingTools attribute to the corresponding characters of your <doc ://com.apple.documentation/documentation/foundation/nsattributedstring> object. You might add this attribute if the text string includes a code listing or readonly content that you don’t want Writing Tools to change.

See also Apple’s documentation

Implementations

impl UIWritingToolsCoordinatorContext

pub unsafe fn initWithAttributedString_range( this: Allocated<Self>, attributed_string: &NSAttributedString, range: NSRange, ) -> Retained<Self>

Creates a context object with the specified attributed string and range information.

• Parameters:
• attributedString: A string that contains some or all of the content from your view’s text storage. This initializer makes a copy of the string you provide, so you can discard the original when you’re done.
• range: The portion of attributedString you want Writing Tools to evaluate. If you want Writing Tools to evaluate the entire string you provided, specify a range with a location of 0 and a length equal to your string’s length. If you want Writing Tools to evaluate only part of the string, provide the appropriate range in this parameter. Writing Tools suggests changes only to the range of text you specify, but it can consider text outside that range during the evaluation process.

When Writing Tools asks for your view’s current selection, it’s best to create a string that includes text before and after that selection. During the evaluation process, Writing Tools can use the additional text you provided to improve the results it delivers. If you do provide additional text, set the range parameter to the portion of attributedString with the current selection. Don’t use the range parameter to specify the location of the text in your view’s text storage.

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

pub unsafe fn attributedString(&self) -> Retained<NSAttributedString>

The portion of your view’s text to evaluate.

The UIWritingToolsCoordinator/Context object initializes the value of this property at creation time and doesn’t change it during the course of an operation. Instead, it suggests changes to the text in the indicated range and reports those changes to your UIWritingToolsCoordinator/Delegate object. Use the methods of your delegate object to integrate those changes back into your view’s text storage.

It’s your responsibility to track the location of this text in your view’s text storage object. When Writing Tools reports changes, it provides range values relative to this string. If you initialize this property with a subset of your view’s content, you must adjust any ranges that Writing Tools provides to get the correct location in your text storage.

pub unsafe fn range(&self) -> NSRange

The unique identifier of the context object.

The UIWritingToolsCoordinator/Context object initializes the value of this property at creation time. Use this value to identify the context object within your app.

pub unsafe fn identifier(&self) -> Retained<NSUUID>

The unique identifier of the context object.

The UIWritingToolsCoordinator/Context object initializes the value of this property at creation time. Use this value to identify the context object within your app.

pub unsafe fn resolvedRange(&self) -> NSRange

The actual range of text that Writing Tools might change, which can be different than the range of text you supplied.

After analyzing the text in your context object, Writing Tools sets this property to the portion of attributedString it might modify. Initially, this property has a location of <doc ://com.apple.documentation/documentation/foundation/nsnotfound> and a length of 0, but Writing Tools updates those values before making any changes to the text.

While the Writing Tools operation is active, make sure Writing Tools has exclusive access to the text in this range. Your UIWritingToolsCoordinator/Delegate object can make changes to the text as part of incorporating Writing Tools results, but don’t allow changes to come from other sources. For example, don’t let someone edit the text in this range directly until Writing Tools finishes.

impl UIWritingToolsCoordinatorContext

Methods declared on superclass NSObject.

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

Available on crate feature UIIndirectScribbleInteraction 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 UIIndirectScribbleInteraction 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 UIIndirectScribbleInteraction 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 UIWritingToolsCoordinatorContext

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for UIWritingToolsCoordinatorContext

fn as_ref(&self) -> &NSObject

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

impl AsRef<UIWritingToolsCoordinatorContext> for UIWritingToolsCoordinatorContext

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for UIWritingToolsCoordinatorContext

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for UIWritingToolsCoordinatorContext

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for UIWritingToolsCoordinatorContext

const NAME: &'static str = "UIWritingToolsCoordinatorContext"

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

type Super = NSObject

The superclass of this class.

type ThreadKind = <<UIWritingToolsCoordinatorContext 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 UIWritingToolsCoordinatorContext

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

Formats the value using the given formatter.

impl Deref for UIWritingToolsCoordinatorContext

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for UIWritingToolsCoordinatorContext

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 UIWritingToolsCoordinatorContext

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for UIWritingToolsCoordinatorContext

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 UIWritingToolsCoordinatorContext

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 UIWritingToolsCoordinatorContext

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

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

impl DowncastTarget for UIWritingToolsCoordinatorContext

impl Eq for UIWritingToolsCoordinatorContext

impl Send for UIWritingToolsCoordinatorContext

impl Sync for UIWritingToolsCoordinatorContext