Struct NSRunningApplication

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

Available on crate feature NSRunningApplication only.

NSRunningApplication is a class to manipulate and provide information for a single instance of an application. Only user applications are tracked; this does not provide information about every process on the system.

Some properties of an application are fixed, such as the bundle identifier. Other properties may vary over time, such as whether the app is hidden. Properties that vary can be observed with KVO, in which case the description comment for the method will mention it.

Properties that vary over time are inherently race-prone. For example, a hidden app may unhide itself at any time. To ameliorate this, properties persist until the next turn of the main run loop in a common mode. For example, if you repeatedly poll an unhidden app for its hidden property without allowing the run loop to run, it will continue to return NO, even if the app hides, until the next turn of the run loop.

NSRunningApplication is thread safe, in that its properties are returned atomically. However, it is still subject to the main run loop policy described above. If you access an instance of NSRunningApplication from a background thread, be aware that its time-varying properties may change from under you as the main run loop runs (or not).

An NSRunningApplication instance remains valid after the application exits. However, most properties lose their significance, and some properties may not be available on a terminated application.

To access the list of all running applications, use the -runningApplications method on NSWorkspace.

See also Apple’s documentation

Implementations

impl NSRunningApplication

pub unsafe fn isTerminated(&self) -> bool

Indicates that the process is an exited application. This is observable through KVO.

pub unsafe fn isFinishedLaunching(&self) -> bool

Indicates that the process is finished launching, which corresponds to the NSApplicationDidFinishLaunchinginternal notification. This is observable through KVO. Some applications do not post this notification and so are never reported as finished launching.

pub unsafe fn isHidden(&self) -> bool

Indicates whether the application is currently hidden. This is observable through KVO.

pub unsafe fn isActive(&self) -> bool

Indicates whether the application is currently frontmost. This is observable through KVO.

pub unsafe fn ownsMenuBar(&self) -> bool

Indicates whether the application currently owns the menu bar. This is observable through KVO.

pub unsafe fn activationPolicy(&self) -> NSApplicationActivationPolicy

Indicates the activation policy of the application. This is observable through KVO (the type is usually fixed, but may be changed through a call to -[NSApplication setActivationPolicy:]).

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

Indicates the name of the application. This is dependent on the current localization of the referenced app, and is suitable for presentation to the user.

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

Indicates the CFBundleIdentifier of the application, or nil if the application does not have an Info.plist.

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

Indicates the URL to the application’s bundle, or nil if the application does not have a bundle.

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

Indicates the URL to the application’s executable.

pub unsafe fn processIdentifier(&self) -> pid_t

Available on crate feature libc only.

Indicates the process identifier (pid) of the application. Do not rely on this for comparing processes. Use -isEqual: instead.

Note: Not all applications have a pid. Applications without a pid return -1 from this method. This is observable through KVO (an application’s pid may change if it is automatically terminated).

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

Indicates the date when the application was launched. This property is not available for all applications. Specifically, it is not available for applications that were launched without going through LaunchServices.

pub unsafe fn icon(&self) -> Option<Retained<NSImage>>

Available on crate feature NSImage only.

Returns: The icon of the application.

pub unsafe fn executableArchitecture(&self) -> NSInteger

Indicates the executing processor architecture for the application, as an NSBundleExecutableArchitecturefrom NSBundle.h.

pub unsafe fn hide(&self) -> bool

Attempts to hide the receiver.

Returns: YES if the request to hide or unhide was successfully sent, NO if not (for example, if the application has quit, or is of a type that cannot be unhidden).

pub unsafe fn unhide(&self) -> bool

Attempts to unhide the receiver.

Returns: YES if the request to hide or unhide was successfully sent, NO if not (for example, if the application has quit, or is of a type that cannot be unhidden).

pub unsafe fn activateFromApplication_options( &self, application: &NSRunningApplication, options: NSApplicationActivationOptions, ) -> bool

Attempts to activate the application using the specified options.

You shouldn’t assume the app will be active immediately after sending this message. The framework also does not guarantee that the app will be activated at all.

Additionally allows specifying another application to take the active status from, which can be used for coordinated or cooperative activation. The other application should call -yieldActivationToApplication: or equivalent prior to this request being sent.

Returns: YES if the request has been allowed by the system, otherwise NO.

pub unsafe fn activateWithOptions( &self, options: NSApplicationActivationOptions, ) -> bool

Attempts to activate the receiver.

Returns: YES if the request to activate was successfully sent, NO if not (for example, if the application has quit, or is of a type that cannot be activated).

pub unsafe fn terminate(&self) -> bool

Attempts to quit the receiver normally.

Returns: YES if the request was successfully sent, NO if not (for example, if the application is no longer running). This method may return before the receiver exits; you should observe the terminated property or listen for the notification to detect when the app has exited.

pub unsafe fn forceTerminate(&self) -> bool

Attempts to force the receiver to quit.

Returns: YES if the request was successfully sent, NO if not (for example, if the application is no longer running). This method may return before the receiver exits; you should observe the terminated property or listen for the notification to detect when the app has exited.

pub unsafe fn runningApplicationsWithBundleIdentifier( bundle_identifier: &NSString, ) -> Retained<NSArray<NSRunningApplication>>

Returns: An array of currently running applications with the given bundle identifier, or an empty array if no apps match.

pub unsafe fn runningApplicationWithProcessIdentifier( pid: pid_t, ) -> Option<Retained<Self>>

Available on crate feature libc only.

Returns: The running application with the given process identifier, or nil if no application has that pid. Applications that do not have PIDs cannot be returned from this method.

pub unsafe fn currentApplication() -> Retained<NSRunningApplication>

Returns: An NSRunningApplicationrepresenting this application.

pub unsafe fn terminateAutomaticallyTerminableApplications()

Cause any applications that are invisibly still running (see NSProcessInfo.h automatic termination methods and docs) to terminate as if triggered by system memory pressure. This is intended for installer apps and the like to make sure that nothing is unexpectedly relying on the files they’re replacing.

impl NSRunningApplication

Methods declared on superclass NSObject.

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

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 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 NSRunningApplication

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for NSRunningApplication

fn as_ref(&self) -> &NSObject

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

impl AsRef<NSRunningApplication> for NSRunningApplication

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for NSRunningApplication

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSRunningApplication

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for NSRunningApplication

const NAME: &'static str = "NSRunningApplication"

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

type Super = NSObject

The superclass of this class.

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

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

Formats the value using the given formatter.

impl Deref for NSRunningApplication

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for NSRunningApplication

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 NSRunningApplication

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for NSRunningApplication

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 NSRunningApplication

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 NSRunningApplication

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

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

impl DowncastTarget for NSRunningApplication

impl Eq for NSRunningApplication

impl Send for NSRunningApplication

impl Sync for NSRunningApplication