|
| 1 | +use crate::runtime::Class; |
| 2 | +use crate::Message; |
| 3 | + |
| 4 | +/// Marks types that represent specific classes. |
| 5 | +/// |
| 6 | +/// Usually it is enough to generically know that a type is messageable, e.g. |
| 7 | +/// [`rc::Id`][crate::rc::Id] works with any type that implements the |
| 8 | +/// [`Message`] trait. But often, you have an object that you know represents |
| 9 | +/// a specific Objective-C class - this trait allows you to communicate that |
| 10 | +/// to the rest of the type-system. |
| 11 | +/// |
| 12 | +/// This is implemented automatically by the |
| 13 | +/// [`declare_class!`][crate::declare_class] and |
| 14 | +/// [`extern_class!`][crate::extern_class] macros. |
| 15 | +/// |
| 16 | +/// |
| 17 | +/// # Safety |
| 18 | +/// |
| 19 | +/// The class returned by [`Self::class`] must be a subclass of the class that |
| 20 | +/// [`Self::Superclass`] represents. |
| 21 | +/// |
| 22 | +/// In pseudocode: |
| 23 | +/// ```ignore |
| 24 | +/// Self::class().superclass() == <Self::Superclass as ClassType>::class() |
| 25 | +/// ``` |
| 26 | +/// |
| 27 | +/// |
| 28 | +/// # Examples |
| 29 | +/// |
| 30 | +/// Use the trait to access the [`Class`] of different objects. |
| 31 | +/// |
| 32 | +/// ``` |
| 33 | +/// # #[cfg(feature = "gnustep-1-7")] |
| 34 | +/// # unsafe { objc2::__gnustep_hack::get_class_to_force_linkage() }; |
| 35 | +/// use objc2::ClassType; |
| 36 | +/// use objc2::foundation::NSObject; |
| 37 | +/// // Get a class object representing `NSObject` |
| 38 | +/// let cls = <NSObject as ClassType>::class(); // Or just `NSObject::class()` |
| 39 | +/// ``` |
| 40 | +/// |
| 41 | +/// Use the [`extern_class!`][crate::extern_class] macro to implement this |
| 42 | +/// trait for a type. |
| 43 | +/// |
| 44 | +/// ```ignore |
| 45 | +/// use objc2::{extern_class, ClassType}; |
| 46 | +/// |
| 47 | +/// extern_class! { |
| 48 | +/// unsafe struct MyClass: NSObject; |
| 49 | +/// } |
| 50 | +/// |
| 51 | +/// let cls = MyClass::class(); |
| 52 | +/// ``` |
| 53 | +pub unsafe trait ClassType: Message { |
| 54 | + /// The superclass of this class. |
| 55 | + /// |
| 56 | + /// If you have implemented [`Deref`] for your type, it is highly |
| 57 | + /// recommended that this is equal to [`Deref::Target`]. |
| 58 | + /// |
| 59 | + /// This may be [`runtime::Object`] if the class is a root class. |
| 60 | + /// |
| 61 | + /// [`Deref`]: std::ops::Deref |
| 62 | + /// [`Deref::Target`]: std::ops::Deref::Target |
| 63 | + /// [`runtime::Object`]: crate::runtime::Object |
| 64 | + type Superclass: Message; |
| 65 | + |
| 66 | + /// Get a reference to the Objective-C class that this type represents. |
| 67 | + /// |
| 68 | + /// May register the class with the runtime if it wasn't already. |
| 69 | + /// |
| 70 | + /// |
| 71 | + /// # Panics |
| 72 | + /// |
| 73 | + /// This may panic if something went wrong with getting or declaring the |
| 74 | + /// class, e.g. if the program is not properly linked to the framework |
| 75 | + /// that defines the class. |
| 76 | + fn class() -> &'static Class; |
| 77 | +} |
0 commit comments