| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.6 and later. |
| Declared in | NSRunningApplication.h |
| Related sample code |
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.
+ runningApplicationWithProcessIdentifier:
+ runningApplicationsWithBundleIdentifier:
+ currentApplication
active property
– activateWithOptions:
activationPolicy property
localizedName property
icon property
bundleIdentifier property
bundleURL property
executableArchitecture property
executableURL property
launchDate property
finishedLaunching property
processIdentifier property
– forceTerminate
– terminate
terminated property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
Indicates the activation policy of the application. (read-only)
@property(readonly) NSApplicationActivationPolicy activationPolicy
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.
NSRunningApplication.hIndicates whether the application is currently frontmost. (read-only)
@property(readonly, getter=isActive) BOOL active
This property is observable using key-value observing.
NSRunningApplication.hIndicates the CFBundleIdentifier of the application. (read-only)
@property(readonly) NSString *bundleIdentifier
The value of this property will be nil if the application does not have an Info.plist.
NSRunningApplication.hIndicates the URL to the application's bundle. (read-only)
@property(readonly) NSURL *bundleURL
The value of this property is nil of the application does not have a bundle structure.
NSRunningApplication.hIndicates the URL to the application's executable. (read-only)
@property(readonly) NSInteger executableArchitecture
NSRunningApplication.hIndicates the URL to the application's executable. (read-only)
@property(readonly) NSURL *executableURL
NSRunningApplication.hIndicates whether the receiver’s process has finished launching, (read-only)
@property(readonly, getter=isFinishedLaunching) BOOL finishedLaunching
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.
NSRunningApplication.hIndicates whether the application is currently hidden. (read-only)
@property(readonly, getter=isHidden) BOOL hidden
This property is observable using key-value observing.
NSRunningApplication.hReturns the icon for the receiver’s application. (read-only)
@property(readonly) NSImage *icon
NSRunningApplication.hIndicates the date when the application was launched. (read-only)
@property(readonly) NSDate *launchDate
This property is not available for all applications. Specifically, it is not available for applications that were launched not launched by LaunchServices.
NSRunningApplication.hIndicates the localized name of the application. (read-only)
@property(readonly) NSString *localizedName
The value of this property is dependent on the current localization of the application and is suitable for presentation to the user.
NSRunningApplication.hIndicates the process identifier (pid) of the application. (read-only)
@property(readonly) pid_t processIdentifier
Not all applications have a pid. Applications without a return a value of -1.
Do not rely on this for comparing processes, instead compare NSRunningApplication instances using isEqual:.
NSRunningApplication.hIndicates that the receiver’s application has terminated. (read-only)
@property(readonly, getter=isTerminated) BOOL terminated
The value of terminated is YES if the receiver’s application has terminated, otherwise NO.
This property is observable using key-value observing.
NSRunningApplication.hReturns an NSRunningApplication representing this application.
+ (NSRunningApplication *)currentApplication
An NSRunningApplication instance for the current application.
NSRunningApplication.hReturns an array of currently running applications with the specified bundle identifier.
+ (NSArray *)runningApplicationsWithBundleIdentifier:(NSString *)bundleIdentifier
The bundle identifier.
An array of NSRunningApplications, or an empty array if no applications match the bundle identifier.
NSRunningApplication.hReturns the running application with the given process identifier, or nil if no application has that pid.
+ (NSRunningApplication *)runningApplicationWithProcessIdentifier:(pid_t)pid
The process identifier.
An instance of NSRunningApplication for the specified pid, or nil if the application has no process identifier.
Applications that do not have PIDs cannot be returned from this method.
NSRunningApplication.hAttempts to activate the application using the specified options.
- (BOOL)activateWithOptions:(NSApplicationActivationOptions)options
The options to use when activating the application. See “NSApplicationActivationOptions” for the possible values.
YES if the application was activated successfully, otherwise NO.
This method will return NO if the application has quit, or is not a type of application than can be activated.
NSRunningApplication.hAttempts to force the receiver to quit.
- (BOOL)forceTerminate
Returns YES if the application successfully terminated, otherwise NO.
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.
NSRunningApplication.hAttempts to hide or the application.
- (BOOL)hide
YES if the application was successfully hidden, otherwise NO.
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.
NSRunningApplication.hAttempts to quit the receiver normally.
- (BOOL)terminate
Returns YES if the application successfully terminated, otherwise NO.
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.
NSRunningApplication.hAttempts to unhide or the application.
- (BOOL)unhide
YES if the application was successfully shown, otherwise NO.
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.
NSRunningApplication.hThe following flags are for activateWithOptions:.
enum {
NSApplicationActivateAllWindows = 1 << 0,
NSApplicationActivateIgnoringOtherApps = 1 << 1
};
typedef NSUInteger NSApplicationActivationOptions;
NSApplicationActivateAllWindowsBy 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 Mac OS X v10.6 and later.
Declared in NSRunningApplication.h.
NSApplicationActivateIgnoringOtherAppsBy 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 Mac OS X v10.6 and later.
Declared in NSRunningApplication.h.
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;
NSApplicationActivationPolicyRegularThe 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 Mac OS X v10.6 and later.
Declared in NSRunningApplication.h.
NSApplicationActivationPolicyAccessoryThe 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 Mac OS X v10.6 and later.
Declared in NSRunningApplication.h.
NSApplicationActivationPolicyProhibitedThe 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 Mac OS X v10.6 and later.
Declared in NSRunningApplication.h.
Last updated: 2009-08-15
Mac OS X Reference Library Data Management: Event Handling NSRunningApplication Class Reference