NSRunningApplication Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Declared in
NSRunningApplication.h
Related sample code

Overview

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 key-value observing, in which case the description comment for the method notes this capability.

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 in NSWorkspace.

Tasks

Getting Running Application Instances

Activating Applications

Hiding and Unhiding Applications

Application Information

Terminating Applications

Properties

activationPolicy

Indicates the activation policy of the application. (read-only)

@property(readonly) NSApplicationActivationPolicy activationPolicy
Discussion

The value returned by this property is usually fixed, but it may change through a call to activateWithOptions:.

This property is observable using key-value observing.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

active

Indicates whether the application is currently frontmost. (read-only)

@property(readonly, getter=isActive) BOOL active
Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

bundleIdentifier

Indicates the CFBundleIdentifier of the application. (read-only)

@property(readonly) NSString *bundleIdentifier
Discussion

The value of this property will be nil if the application does not have an Info.plist.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

bundleURL

Indicates the URL to the application's bundle. (read-only)

@property(readonly) NSURL *bundleURL
Discussion

The value of this property is nil of the application does not have a bundle structure.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSRunningApplication.h

executableArchitecture

Indicates the executing processor architecture for the application. (read-only)

@property(readonly) NSInteger executableArchitecture
Discussion

The returned value will be one of the constants in Mach-O Architecture in NSBundle Class Reference.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSRunningApplication.h

executableURL

Indicates the URL to the application's executable. (read-only)

@property(readonly) NSURL *executableURL
Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSRunningApplication.h

finishedLaunching

Indicates whether the receiver’s process has finished launching, (read-only)

@property(readonly, getter=isFinishedLaunching) BOOL finishedLaunching
Discussion

The value of this property corresponds to the running application having received an NSApplicationDidFinishLaunchingNotification notification internally. Some applications do not post this notification (applications that do not rely on NSApplication) and so are never reported as finished launching.

This property is observable using key-value observing.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

hidden

Indicates whether the application is currently hidden. (read-only)

@property(readonly, getter=isHidden) BOOL hidden
Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSRunningApplication.h

icon

Returns the icon for the receiver’s application. (read-only)

@property(readonly) NSImage *icon
Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

launchDate

Indicates the date when the application was launched. (read-only)

@property(readonly) NSDate *launchDate
Discussion

This property is only available for applications that were launched by LaunchServices.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

localizedName

Indicates the localized name of the application. (read-only)

@property(readonly) NSString *localizedName
Discussion

The value of this property is dependent on the current localization of the application and is suitable for presentation to the user.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

ownsMenuBar

Returns whether the application owns the current menu bar. (read-only)

@property(readonly) BOOL ownsMenuBar
Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSRunningApplication.h

processIdentifier

Indicates the process identifier (pid) of the application. (read-only)

@property(readonly) pid_t processIdentifier
Discussion

Not all applications have a pid. Applications without a pid return a value of -1.

Do not rely on this for comparing processes, instead compare NSRunningApplication instances using isEqual:.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

terminated

Indicates that the receiver’s application has terminated. (read-only)

@property(readonly, getter=isTerminated) BOOL terminated
Discussion

The value of terminated is YES if the receiver’s application has terminated, otherwise NO.

This property is observable using key-value observing.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSRunningApplication.h

Class Methods

currentApplication

Returns an NSRunningApplication representing this application.

+ (NSRunningApplication *)currentApplication
Return Value

An NSRunningApplication instance for the current application.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

runningApplicationsWithBundleIdentifier:

Returns an array of currently running applications with the specified bundle identifier.

+ (NSArray *)runningApplicationsWithBundleIdentifier:(NSString *)bundleIdentifier
Parameters
bundleIdentifier

The bundle identifier.

Return Value

An array of NSRunningApplications, or an empty array if no applications match the bundle identifier.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSRunningApplication.h

runningApplicationWithProcessIdentifier:

Returns the running application with the given process identifier, or nil if no application has that pid.

+ (NSRunningApplication *)runningApplicationWithProcessIdentifier:(pid_t)pid
Parameters
pid

The process identifier.

Return Value

An instance of NSRunningApplication for the specified pid, or nil if the application has no process identifier.

Discussion

Applications that do not have PIDs cannot be returned from this method.

Availability
  • Available in OS X v10.6 and later.
See Also
Related Sample Code
Declared In
NSRunningApplication.h

terminateAutomaticallyTerminableApplications

Terminates invisibly running applications as if triggered by system memory pressure.

+ (void)terminateAutomaticallyTerminableApplications
Discussion

This method is intended for installer applications and similar applications to ensure that nothing is unexpectedly relying on the files they're replacing.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSRunningApplication.h

Instance Methods

activateWithOptions:

Attempts to activate the application using the specified options.

- (BOOL)activateWithOptions:(NSApplicationActivationOptions)options
Parameters
options

The options to use when activating the application. See “NSApplicationActivationOptions” for the possible values.

Return Value

YES if the application was activated successfully, otherwise NO.

Discussion

This method will return NO if the application has quit, or is not a type of application than can be activated.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSRunningApplication.h

forceTerminate

Attempts to force the receiver to quit.

- (BOOL)forceTerminate
Return Value

Returns YES if the application successfully terminated, otherwise NO.

Discussion

This method will return NO if the application is no longer running when the forceTerminate message is sent to the receiver.

This method may return before the receiver exits; you should observe the terminated property to determine when the application terminates.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSRunningApplication.h

hide

Attempts to hide or the application.

- (BOOL)hide
Return Value

YES if the application was successfully hidden, otherwise NO.

Discussion

The property of this value will be NO if the application has already quit, or if of a type that is unable to be hidden.

Availability
  • Available in OS X v10.6 and later.
See Also
Related Sample Code
Declared In
NSRunningApplication.h

terminate

Attempts to quit the receiver normally.

- (BOOL)terminate
Return Value

Returns YES if the application successfully terminated, otherwise NO.

Discussion

This method will return NO if the application is no longer running when the terminate message is sent to the receiver.

This method may return before the receiver exits; you should observe the terminated property to determine when the application terminates.

Availability
  • Available in OS X v10.6 and later.
See Also
Related Sample Code
Declared In
NSRunningApplication.h

unhide

Attempts to unhide or the application.

- (BOOL)unhide
Return Value

YES if the application was successfully shown, otherwise NO.

Discussion

The property of this value will be NO if the application has already quit, or if of a type that is unable to be hidden.

Availability
  • Available in OS X v10.6 and later.
See Also
Related Sample Code
Declared In
NSRunningApplication.h

Constants

NSApplicationActivationOptions

The following flags are for activateWithOptions:.

enum {
   NSApplicationActivateAllWindows = 1 << 0,
   NSApplicationActivateIgnoringOtherApps = 1 << 1
};
typedef NSUInteger NSApplicationActivationOptions;
Constants
NSApplicationActivateAllWindows

By default, activation brings only the main and key windows forward. If you specify NSApplicationActivateAllWindows, all of the application's windows are brought forward.

Available in OS X v10.6 and later.

Declared in NSRunningApplication.h.

NSApplicationActivateIgnoringOtherApps

By default, activation deactivates the calling app (assuming it was active), and then the new app is activated only if there is no currently active application. This prevents the new app from stealing focus from the user, if the app is slow to activate and the user has switched to a different app in the interim. However, if you specify NSApplicationActivateIgnoringOtherApps, the application is activated regardless of the currently active app, potentially stealing focus from the user. You should rarely pass this flag because stealing key focus produces a very bad user experience.

Available in OS X v10.6 and later.

Declared in NSRunningApplication.h.

NSApplicationActivationPolicy

The following activation policies control whether and how an application may be activated. They are used by activationPolicy.

enum {
   NSApplicationActivationPolicyRegular,
   NSApplicationActivationPolicyAccessory,
   NSApplicationActivationPolicyProhibited
};
typedef NSInteger NSApplicationActivationPolicy;
Constants
NSApplicationActivationPolicyRegular

The application is an ordinary app that appears in the Dock and may have a user interface. This is the default for bundled apps, unless overridden in the Info.plist.

Available in OS X v10.6 and later.

Declared in NSRunningApplication.h.

NSApplicationActivationPolicyAccessory

The application does not appear in the Dock and does not have a menu bar, but it may be activated programmatically or by clicking on one of its windows. This corresponds to value of the LSUIElement key in the application’s Info.plist being 1.

Available in OS X v10.6 and later.

Declared in NSRunningApplication.h.

NSApplicationActivationPolicyProhibited

The application does not appear in the Dock and may not create windows or be activated. This corresponds to the value of the LSBackgroundOnly key in the application’s Info.plist being 1. This is also the default for unbundled executables that do not have Info.plists.

Available in OS X v10.6 and later.

Declared in NSRunningApplication.h.



© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-06-06)

Did this document help you? Yes It's good, but... Not helpful...