Struct CLSContext

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

Available on crate features CLSContext and CLSObject only.

Contexts represent activities, documents, and areas within your app.

Contexts have two major components.

(1) Child contexts, used to model your app hierarchy. (2) Activity, holds user generated data that pertains to this context.

See also Apple’s documentation

Implementations

impl CLSContext

Activity.

pub unsafe fn currentActivity(&self) -> Option<Retained<CLSActivity>>

Available on crate feature CLSActivity only.

Returns the current activity.

Activity associated with a context. If no activity was ever created this is nil. See: -[CLSContextcreateNewActivity]; for more details.

pub unsafe fn createNewActivity(&self) -> Retained<CLSActivity>

Available on crate feature CLSActivity only.

Creates a new activity

Creates a new activity and sets it as the current activity.

impl CLSContext

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

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

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

Context identifier path of this context.

The identifier path starts with the main app context object and finishes with the identifier of this context. This is the identifier path that one would use in

 -[CLSDataStore contextsMatchingIdintifierPath:completion:]

to find `this’ context.

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

App-assigned identifier. This identifier should work across users and devices and be unique with regards to its siblings within its parent.

The identifier could be used to embed information later used for deep linking. For example: _hydrogen-element,_or chapter-1.

pub unsafe fn universalLinkURL(&self) -> Option<Retained<NSURL>>

Alternative deep link URL using universal links.

If your app supports universal links, you can supply them here to link the content this context represents.

pub unsafe fn setUniversalLinkURL(&self, universal_link_url: Option<&NSURL>)

Setter for universalLinkURL.

pub unsafe fn type(&self) -> CLSContextType

Type of this context

The type that best describes this context.

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

An optional user-visible name for the context if its type is CLSContextTypeCustom.

This property is relevant only if the type is CLSContextTypeCustom. This string should be localized. If this property is not set for a context of type CLSContextTypeCustom, Schoolwork app will use a default localized string ‘Custom’ as the name of the activity representing this context.

pub unsafe fn setCustomTypeName(&self, custom_type_name: Option<&NSString>)

Setter for customTypeName.

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

Title of this context.

For example: _Level_1 .

pub unsafe fn setTitle(&self, title: &NSString)

Setter for title.

pub unsafe fn displayOrder(&self) -> NSInteger

The displayOrder is by default sorted ascending.

Set the displayOrder if you want your contexts to be displayed in a particular order. The sort key is used as a way to sort sibling contexts in a particular order.

pub unsafe fn setDisplayOrder(&self, display_order: NSInteger)

Setter for displayOrder.

pub unsafe fn topic(&self) -> Option<Retained<CLSContextTopic>>

Topic associated with this context.

See above for valid, predefined topics.

pub unsafe fn setTopic(&self, topic: Option<&CLSContextTopic>)

Setter for topic.

pub unsafe fn isAssignable(&self) -> bool

This property is true if the context can be assigned as an activity.

The default value of this property is true. This should be set to false for a context that is used as a container for other contexts, but by itself, is not an assignable activity.

pub unsafe fn setAssignable(&self, assignable: bool)

Setter for isAssignable.

pub unsafe fn suggestedAge(&self) -> NSRange

Suggested age range of students, expressed in years, for whom this context is suitable. This information is intended to help teachers to choose age-appropriate activities for their students.

The default value is [0, NSIntegerMax - 1]. This is _NSRange(0…Int.max-1)_in _Swift_or _NSMakeRange(0,NSIntegerMax)_in _Objective-C._Set the lower bound to 0 to specify no minimum age limit and set the upper bound to NSIntegerMax - 1 to specify no maximum age limit.

pub unsafe fn setSuggestedAge(&self, suggested_age: NSRange)

Setter for suggestedAge.

pub unsafe fn suggestedCompletionTime(&self) -> NSRange

Suggested time range, expressed in minutes, to complete the activity. This information will help teachers as they choose activities for their students.

The default value is [0, NSIntegerMax - 1]. This is _NSRange(0…Int.max-1)_in _Swift_or _NSMakeRange(0,NSIntegerMax)_in _Objective-C._Set the lower bound value to 0 to specify no minimum time limit and set the upper bound to NSIntegerMax - 1 to specify no maximum time limit.

pub unsafe fn setSuggestedCompletionTime( &self, suggested_completion_time: NSRange, )

Setter for suggestedCompletionTime.

pub unsafe fn progressReportingCapabilities( &self, ) -> Retained<NSSet<CLSProgressReportingCapability>>

Available on crate feature CLSProgressReportingCapability only.

Specifies progress reporting capablities of the app for this context.

This information is intended to help teachers as they choose activities for their students. By default a CLSContext will have one CLSProgressReportingCapability instance of kind CLSProgressReportingCapabilityKindDuration. More progress reporting capabilities can be specified via ‘-addProgressReportingCapabilities:’ to customize this set.

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

An optional user-visible summary describing the context limited to 4000 characters in length.

This may be used to provide information about the types of activities available under a given context or the context itself. This string should be localized.

pub unsafe fn setSummary(&self, summary: Option<&NSString>)

Setter for summary.

pub unsafe fn thumbnail(&self) -> Option<Retained<CGImage>>

Available on crate feature objc2-core-graphics only.

An optional thumbnail image associated with the context.

The size of this image should be equal to or larger than 80x80 pixels and equal to or smaller than 330x330 pixels. Images larger than 330x330 pixels will be scaled down. Images with both dimensions smaller than 80x80 pixels will not be accepted.

pub unsafe fn setThumbnail(&self, thumbnail: Option<&CGImage>)

Available on crate feature objc2-core-graphics only.

Setter for thumbnail.

pub unsafe fn initWithType_identifier_title( this: Allocated<Self>, type: CLSContextType, identifier: &NSString, title: &NSString, ) -> Retained<Self>

Initialize and configure the type of content this context represents.

Parameter identifier: App-assigned identifier for this context. 256 characters max length.

Parameter type: The type of content this context represents.

Parameter title: Title for what this context represents. 256 characters max length.

pub unsafe fn isActive(&self) -> bool

Returns true if self is the active context.

pub unsafe fn becomeActive(&self)

Marks contexts as active.

If a context is already active, it will remain active. If another context is active, the other will resign active before this one becomes active.

pub unsafe fn resignActive(&self)

Resign being active.

This method does nothing if the reciever of the message is not active.

pub unsafe fn setType(&self, type: CLSContextType)

Sets the type.

Use this to update a previously saved context.

pub unsafe fn addProgressReportingCapabilities( &self, capabilities: &NSSet<CLSProgressReportingCapability>, )

Available on crate feature CLSProgressReportingCapability only.

Add or replace additional progress reporting capabilities of the app for this context.

If this parameter contains multiple items with the same value for kind, then one of them will be arbitrarily selected and used. If this parameter contains a capability of kind CLSProgressReportingCapabilityKindDuration, it will be ignored.

Parameter capabilities: Progress reporting capabilities to add or replace existing capabilties.

pub unsafe fn resetProgressReportingCapabilities(&self)

Clears CLSProgressReportingCapability objects added to the receiver.

Removes all capabilities added via ‘-addProgressReportingCapabilities:’. The context will have the default progress reporting capability of kind CLSProgressReportingCapabilityKindDuration.

impl CLSContext

Hierarchy.

pub unsafe fn parent(&self) -> Option<Retained<CLSContext>>

Returns the parent of this context.

pub unsafe fn removeFromParent(&self)

Removes this child context from its parent.

If you remove a context from its parent and do not add it as a child of another context, it will be deleted when you call -save on the dataStore.

pub unsafe fn addChildContext(&self, child: &CLSContext)

Adds a child context.

A context can only have a single parent.

Note: objectID of child context may change after it’s been added.

pub unsafe fn descendantMatchingIdentifierPath_completion( &self, identifier_path: &NSArray<NSString>, completion: &DynBlock<dyn Fn(*mut CLSContext, *mut NSError)>, )

Available on crate feature block2 only.

Returns a descendant of this context matching the context path you provide. Context path must start with an identifier of a child context of the context to which this message is sent.

If there are any missing contexts, they will be filled in by calling the following method on the context’s data store’s delegate:

 -[CLSDataStoreDelegate createContextForIdentifier:parentContext:parentIdentifierPath:]

If the dataStore does not have a delegate and there are missing contexts then an incomplete list of contexts will be passed to the completion handler. Completion block is called on a background thread.

pub unsafe fn navigationChildContexts(&self) -> Retained<NSArray<CLSContext>>

Child contexts that can be navigated to from this context.

Returns all the child contexts added via

 -[CLSContext addNavigationChildContext:]

pub unsafe fn addNavigationChildContext(&self, child: &CLSContext)

Adds a child context to specify the user can navigate to the child from this context.

Used only for presentation purpose. Unlike

 -[CLSContext addChildContext:]

, this method does not affect the identifierPath.

pub unsafe fn removeNavigationChildContext(&self, child: &CLSContext)

Removes the navigation path to the child context from this context.

Used only for presentation purpose. Unlike

 -[CLSContext removeFromParent:]

, this method does not affect the identiferPath.

Methods from Deref<Target = CLSObject>

pub unsafe fn dateCreated(&self) -> Retained<NSDate>

The date this object was created.

pub unsafe fn dateLastModified(&self) -> Retained<NSDate>

The date this object was last modified.

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 CLSContext

fn as_ref(&self) -> &AnyObject

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

impl AsRef<CLSContext> for CLSContext

fn as_ref(&self) -> &Self

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

impl AsRef<CLSObject> for CLSContext

fn as_ref(&self) -> &CLSObject

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

impl AsRef<NSObject> for CLSContext

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for CLSContext

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CLSObject> for CLSContext

fn borrow(&self) -> &CLSObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for CLSContext

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for CLSContext

const NAME: &'static str = "CLSContext"

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

type Super = CLSObject

The superclass of this class.

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

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

Formats the value using the given formatter.

impl Deref for CLSContext

type Target = CLSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for CLSContext

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 CLSContext

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for CLSContext

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 NSSecureCoding for CLSContext

unsafe fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

impl PartialEq for CLSContext

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 CLSContext

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

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

impl DowncastTarget for CLSContext

impl Eq for CLSContext

impl NSCoding for CLSContext