Struct SBApplication 

pub struct SBApplication { /* private fields */ }

Available on crate features SBApplication and SBObject only.

The SBApplication class provides a mechanism enabling an Objective-C program to send Apple events to a scriptable application and receive Apple events in response. It thereby makes it possible for that program to control the application and exchange data with it. Scripting Bridge works by bridging data types between Apple event descriptors and Cocoa objects.

Although SBApplication includes methods that manually send and process Apple events, you should never have to call these methods directly. Instead, subclasses of SBApplication implement application-specific methods that handle the sending of Apple events automatically.

For example, if you wanted to get the current iTunes track, you can simply use the currentTrack method of the dynamically defined subclass for the iTunes application—which handles the details of sending the Apple event for you—rather than figuring out the more complicated, low-level alternative:

[iTunes propertyWithCode:'pTrk'];

If you do need to send Apple events manually, consider using the NSAppleEventDescriptor class.

Subclassing Notes

You rarely instantiate SBApplication objects directly. Instead, you get the shared instance of a application-specific subclass typically by calling one of the applicationWith... class methods, using a bundle identifier, process identifier, or URL to identify the application.

See also Apple’s documentation

Implementations

impl SBApplication

pub unsafe fn initWithBundleIdentifier( this: Allocated<Self>, ident: &NSString, ) -> Option<Retained<SBApplication>>

Returns an instance of an SBApplication subclass that represents the target application identified by the given bundle identifier.

If you must initialize an SBApplication object explictly, you should use this initializer if possible; unlike SBApplication/initWithProcessIdentifier: and SBApplication/initWithURL:, this method is not dependent on changeable factors such as the target application’s path or process ID. Even so, you should rarely have to initialize an SBApplication object yourself; instead, you should initialize an application-specific subclass such as iTunesApplication.

Note that this method does not check whether an application with the given bundle identifier actually exists.

• Parameters:

• ident: A bundle identifier specifying an application that is OSA-compliant.

• Returns: An initialized shared instance of an SBApplication subclass that represents a target application with the bundle identifier of ident. Returns nil if no such application can be found or if the application does not have a scripting interface.

pub unsafe fn initWithURL( this: Allocated<Self>, url: &NSURL, ) -> Option<Retained<SBApplication>>

Returns an instance of an SBApplication subclass that represents the target application identified by the given URL.

This approach to initializing SBApplication objects should be used only if you know for certain the URL of the target application. In most cases, it is better to use SBApplication/applicationWithBundleIdentifier: which dynamically locates the target application at runtime. Even so, you should rarely have to initialize an SBApplication yourself.

This method currently supports file URLs (file:) and remote application URLs (eppc:). It checks whether a file exists at the specified path, but it does not check whether an application identified via eppc: exists.

• Parameters:

• url: A Universal Resource Locator (URL) specifying an application that is OSA-compliant.

• Returns: An initialized SBApplication that you can use to communicate with the target application specified by the process ID. Returns nil if an application could not be found or if the application does not have a scripting interface.

pub unsafe fn initWithProcessIdentifier( this: Allocated<Self>, pid: pid_t, ) -> Option<Retained<SBApplication>>

Available on crate feature libc only.

Returns an instance of an SBApplication subclass that represents the target application identified by the given process identifier.

You should avoid using this method unless you know nothing about an external application but its PID. In most cases, it is better to use SBApplication/initWithBundleIdentifier:, which will dynamically locate the external application’s path at runtime, or SBApplication/initWithURL:, which is not dependent on the external application being open at the time the method is called.

• Parameters:

• pid: A BSD process ID specifying an application that is OSA-compliant. Often you can get the process ID of a process using the <doc ://com.apple.documentation/documentation/foundation/nstask/1412022-processidentifier> method of NSTask.

• Returns: An initialized SBApplication that you can use to communicate with the target application specified by the process ID. Returns nil if no such application can be found or if the application does not have a scripting interface.

pub unsafe fn applicationWithBundleIdentifier( ident: &NSString, ) -> Option<Retained<SBApplication>>

Returns the shared instance representing the target application specified by its bundle identifier.

For applications that declare themselves to have a dynamic scripting interface, this method will launch the application if it is not already running.

• Parameters:

• ident: A bundle identifier specifying an application that is OSA-compliant.

• Returns: An instance of a SBApplication subclass that represents the target application whose bundle identifier is ident. Returns nil if no such application can be found or if the application does not have a scripting interface.

pub unsafe fn applicationWithURL(url: &NSURL) -> Option<Retained<SBApplication>>

Returns the shared instance representing a target application specified by the given URL.

For applications that declare themselves to have a dynamic scripting interface, this method will launch the application if it is not already running. This approach to initializing SBApplication objects should be used only if you know for certain the URL of the target application. In most cases, it is better to use SBApplication/applicationWithBundleIdentifier: which dynamically locates the target application at runtime.

This method currently supports file URLs (file:) and remote application URLs (eppc:). It checks whether a file exists at the specified path, but it does not check whether an application identified via eppc: exists.

• Parameters:

• url: The Universal Resource Locator (URL) locating an OSA-compliant application.

• Returns: An SBApplication subclass from which to generate a shared instance of the target application whose URL is url. Returns nil if no such application can be found or if the application does not have a scripting interface.

pub unsafe fn applicationWithProcessIdentifier( pid: pid_t, ) -> Option<Retained<SBApplication>>

Available on crate feature libc only.

Returns the shared instance representing a target application specified by its process identifier.

You should avoid using this method unless you know nothing about a target application but its process ID. In most cases, it is better to use SBApplication/applicationWithBundleIdentifier:, which will dynamically locate the application’s path at runtime, or SBApplication/applicationWithURL:, which is not dependent on the target application being open at the time the method is called.

• Parameters:

• pid: The BSD process ID of a OSA-compliant application. Often you can get the process ID of a process using the <doc ://com.apple.documentation/documentation/foundation/nstask/1412022-processidentifier> method of NSTask.

• Returns: An instance of an SBApplication subclass that represents the target application whose process identifier is pid. Returns nil if no such application can be found or if the application does not have a scripting interface.

pub unsafe fn classForScriptingClass( &self, class_name: &NSString, ) -> Option<&'static AnyClass>

Returns a class object that represents a particular class in the target application.

You invoke this method on an instance of a scriptable application. Once you have the class object, you may allocate an instance of the class and appropriately the raw instance. Or you may use it in a call to <doc ://com.apple.documentation/documentation/objectivec/1418956-nsobject/1418511-iskindofclass> to determine the class type of an object.

• Parameters:

• className: The name of the scripting class, as it appears in the scripting interface. For example, “document”.

• Returns: A Class object representing the scripting class.

pub unsafe fn isRunning(&self) -> bool

A Boolean that indicates whether the target application represented by the receiver is running.

<doc ://com.apple.documentation/documentation/swift/true> if the application is running, <doc ://com.apple.documentation/documentation/swift/false> otherwise.

This may be <doc ://com.apple.documentation/documentation/swift/true> for instances initialized with a bundle identifier or URL because SBApplication launches the application only when it’s necessary to send it an event.

pub unsafe fn activate(&self)

Moves the target application to the foreground immediately.

If the target application is not already running, this method launches it.

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

The error-handling delegate of the receiver.

The delegate should implement the SBApplicationDelegate/eventDidFail:withError: method of the SBApplicationDelegate informal protocol.

pub unsafe fn setDelegate( &self, delegate: Option<&ProtocolObject<dyn SBApplicationDelegate>>, )

Setter for delegate.

pub unsafe fn launchFlags(&self) -> LSLaunchFlags

Available on crate feature objc2-core-services only.

The launch flags for the application represented by the receiver.

For more information, see <doc ://com.apple.documentation/documentation/coreservices/launch_services>.

pub unsafe fn setLaunchFlags(&self, launch_flags: LSLaunchFlags)

Available on crate feature objc2-core-services only.

Setter for launchFlags.

pub unsafe fn sendMode(&self) -> AESendMode

Available on crate feature objc2-core-services only.

The mode for sending Apple events to the target application.

For more information, see <doc ://com.apple.documentation/documentation/applicationservices/apple_event_manager>.

The default send mode is <doc ://com.apple.documentation/documentation/coreservices/1542914-anonymous/kaewaitreply>. If the send mode is something other than kAEWaitReply, the receiver might not correctly handle reply events from the target application.

pub unsafe fn setSendMode(&self, send_mode: AESendMode)

Available on crate feature objc2-core-services only.

Setter for sendMode.

pub unsafe fn timeout(&self) -> c_long

The period the application will wait to receive reply Apple events.

For more information, see <doc ://com.apple.documentation/documentation/applicationservices/apple_event_manager>.

The default timeout value is <doc ://com.apple.documentation/documentation/coreservices/1542814-timeout_constants/kaedefaulttimeout>, which is about a minute. If you want the receiver to wait indefinitely for reply Apple events, use <doc ://com.apple.documentation/documentation/coreservices/1542814-timeout_constants/knotimeout>. For more information, see <doc ://com.apple.documentation/documentation/applicationservices/apple_event_manager>.

pub unsafe fn setTimeout(&self, timeout: c_long)

Setter for timeout.

impl SBApplication

Methods declared on superclass SBObject.

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

Initializes and returns an instance of an SBObject subclass.

Scripting Bridge does not actually create an object in the target application until you add the object returned from this method to an element array (SBElementArray).

• Returns: An SBObject object or nil if the object could not be initialized.

pub unsafe fn initWithProperties( this: Allocated<Self>, properties: &NSDictionary, ) -> Retained<Self>

Returns an instance of an SBObject subclass initialized with the specified properties.

Scripting Bridge does not actually create an object in the target application until you add the object returned from this method to an element array (SBElementArray).

• Parameters:

• properties: A dictionary with keys specifying the names of properties (that is, attributes or to-one relationships) and the values for those properties.

• Returns: An SBObject object or nil if the object could not be initialized.

Safety

properties generic should be of the correct type.

pub unsafe fn initWithData( this: Allocated<Self>, data: &AnyObject, ) -> Retained<Self>

Returns an instance of an SBObject subclass initialized with the given data.

Scripting Bridge does not actually create an object in the target application until you add the object returned from this method to an element array (SBElementArray).

• Parameters:

• data: An object containing data for the new SBObject object. The data varies according to the type of scripting object to be created.

• Returns: An SBObject object or nil if the object could not be initialized.

Safety

data should be of the correct type.

impl SBApplication

Methods declared on superclass NSObject.

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

Methods from Deref<Target = SBObject>

pub unsafe fn get(&self) -> Option<Retained<AnyObject>>

Forces evaluation of the receiver, causing the real object to be returned immediately.

This method forces the current object reference (the receiver) to be evaluated, resulting in the return of the referenced object. By default, Scripting Bridge deals with references to objects until you actually request some concrete data from them or until you call the get method.

• Returns: For most properties, the result is a Foundation object such as an NSString. For properties with no Foundation equivalent, the result is an NSAppleEventDescriptor or another SBObject for most elements.

pub unsafe fn lastError(&self) -> Option<Retained<NSError>>

The error from the last event this object sent, or nil if it succeeded.

pub unsafe fn propertyWithCode(&self, code: AEKeyword) -> Retained<SBObject>

Available on crate feature objc2-core-services only.

Returns an object representing the specified property of the receiver.

SBObject subclasses use this method to implement application-specific property accessor methods. You should not need to call this method directly.

• Parameters:

• code: A four-character code that uniquely identifies a property of the receiver.

• Returns: An object representing the receiver’s property as identified by code.

pub unsafe fn propertyWithClass_code( &self, cls: &AnyClass, code: AEKeyword, ) -> Retained<SBObject>

Available on crate feature objc2-core-services only.

Returns an object of the designated scripting class representing the specified property of the receiver

SBObject subclasses use this method to implement application-specific property accessor methods. You should not need to call this method directly.

Note: This method doesn’t retrieve the value of the property. To get the value, call get.

• Parameters:

• class: The SBObject subclass with which to instantiate the object.

• code: A four-character code that uniquely identifies a property of the receiver.

• Returns: An instance of the designated class that represents the receiver’s property identified by code.

Safety

cls probably has further requirements.

pub unsafe fn elementArrayWithCode( &self, code: DescType, ) -> Retained<SBElementArray>

Available on crate features SBElementArray and objc2-core-services only.

Returns an array containing every child of the receiver with the given class-type code.

SBObject subclasses use this method to implement application-specific property accessor methods. You should not need to call this method directly.

Note: This method doesn’t retrieve the value of the property. To get the value, call get.

• Parameters:

• code: A four-character code that identifies a scripting class.

• Returns: An SBElementArray object containing every child of the receiver whose class matches code.

pub unsafe fn setTo(&self, value: Option<&AnyObject>)

Sets the receiver to a specified value.

You should not call this method directly.

• Parameters:
• value: The data the receiver should be set to. It can be an <doc ://com.apple.documentation/documentation/foundation/nsstring>, <doc ://com.apple.documentation/documentation/foundation/nsnumber>, <doc ://com.apple.documentation/documentation/foundation/nsarray>, SBObject, or any other type of object supported by the Scripting Bridge framework.

Safety

value should be of the correct type.

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 SBApplication

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for SBApplication

fn as_ref(&self) -> &NSObject

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

impl AsRef<SBApplication> for SBApplication

fn as_ref(&self) -> &Self

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

impl AsRef<SBObject> for SBApplication

fn as_ref(&self) -> &SBObject

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

impl Borrow<AnyObject> for SBApplication

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for SBApplication

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl Borrow<SBObject> for SBApplication

fn borrow(&self) -> &SBObject

Immutably borrows from an owned value.

impl ClassType for SBApplication

const NAME: &'static str = "SBApplication"

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

type Super = SBObject

The superclass of this class.

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

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

Formats the value using the given formatter.

impl Deref for SBApplication

type Target = SBObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for SBApplication

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 SBApplication

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSCoding for SBApplication

unsafe fn encodeWithCoder(&self, coder: &NSCoder)

where Self: Sized + Message,

Safety

unsafe fn initWithCoder( this: Allocated<Self>, coder: &NSCoder, ) -> Option<Retained<Self>>

where Self: Sized + Message,

Safety

impl NSObjectProtocol for SBApplication

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 SBApplication

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 SBApplication

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

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

impl DowncastTarget for SBApplication

impl Eq for SBApplication