Class

NSApplication

An object that manages an app’s main event loop and resources used by all of that app’s objects.

Declaration

@interface NSApplication : NSResponder

Overview

Every app uses a single instance of NSApplication to control the main event loop, keep track of the app’s windows and menus, distribute events to the appropriate objects (that’s, itself or one of its windows), set up autorelease pools, and receive notification of app-level events. An NSApplication object has a delegate (an object that you assign) that’s notified when the app starts or terminates, is hidden or activated, should open a file selected by the user, and so forth. By setting the delegate and implementing the delegate methods, you customize the behavior of your app without having to subclass NSApplication.In your app’s main() function, create the NSApplication instance by calling the sharedApplication class method. After creating the application object, the main() function should load your app’s main nib file and then start the event loop by sending the application object a run message. If you create an Application project in Xcode, this main() function is created for you. The main() function Xcode creates begins by calling a function named NSApplicationMain(), which is functionally similar to the following:

void NSApplicationMain(int argc, char *argv[]) {
    [NSApplication sharedApplication];
    [NSBundle loadNibNamed:@"myMain" owner:NSApp];
    [NSApp run];
}

The sharedApplication class method initializes the display environment and connects your program to the window server and the display server. The NSApplication object maintains a list of all the NSWindow objects the app uses, so it can retrieve any of the app’s NSView objects. The sharedApplication method also initializes the global variable NSApp, which you use to retrieve the NSApplication instance. sharedApplication only performs the initialization once. If you invoke it more than once, it returns the application object it created previously.

The shared NSApplication object performs the important task of receiving events from the window server and distributing them to the proper NSResponder objects. NSApp translates an event into an NSEvent object, then forwards the event object to the affected NSWindow object. All keyboard and mouse events go directly to the NSWindow object associated with the event. The only exception to this rule is if the Command key is pressed when a key-down event occurs; in this case, every NSWindow object has an opportunity to respond to the event. When a window object receives an NSEvent object from NSApp, it distributes it to the objects in its view hierarchy.

NSApplication is also responsible for dispatching certain Apple events received by the app. For example, macOS sends Apple events to your app at various times, such as when the app is launched or reopened. NSApplication installs Apple event handlers to handle these events by sending a message to the appropriate object. You can also use the NSAppleEventManager class to register your own Apple event handlers. The applicationWillFinishLaunching: method is generally the best place to do so. For more information on how events are handled and how you can modify the default behavior, including information on working with Apple events in scriptable apps, see How Cocoa Applications Handle Apple Events in Cocoa Scripting Guide.

The NSApplication class sets up @autorelease block during initialization and inside the event loop—specifically, within its initialization (or sharedApplication) and run methods. Similarly, the methods AppKit adds to NSBundle employ @autorelease blocks during the loading of nib files. These @autorelease blocks aren’t accessible outside the scope of the respective NSApplication and NSBundle methods. Typically, an app creates objects either while the event loop is running or by loading objects from nib files, so this lack of access usually isn’t a problem. However, if you do need to use Cocoa classes within the main() function itself (other than to load nib files or to instantiate NSApplication), you should create an @autorelease block to contain the code using the classes.

The Delegate and Notifications

You can assign a delegate to your NSApplication object. The delegate responds to certain messages on behalf of the object. Some of these messages, such as application:openFile:, ask the delegate to perform an action. Another message, applicationShouldTerminate:, lets the delegate determine whether the app should be allowed to quit. The NSApplication class sends these messages directly to its delegate.

NSApplication also posts notifications to the app’s default notification center. Any object may register to receive one or more of the notifications posted by NSApplication by sending the message addObserver:selector:name:object: to the default notification center (an instance of the NSNotificationCenter class). The delegate of NSApplication is automatically registered to receive these notifications if it implements certain delegate methods. For example, NSApplication posts notifications when it’s about to be done launching the app and when it’s done launching the app (NSApplicationWillFinishLaunchingNotification and NSApplicationDidFinishLaunchingNotification). The delegate has an opportunity to respond to these notifications by implementing the methods applicationWillFinishLaunching: and applicationDidFinishLaunching:. If the delegate wants to be informed of both events, it implements both methods. If it needs to know only when the app is finished launching, it implements only applicationDidFinishLaunching:.

System Services

NSApplication interacts with the system services architecture to provide services to your app through the Services menu.

Subclassing Notes

You rarely should find a real need to create a custom NSApplication subclass. Unlike some object-oriented libraries, Cocoa doesn’t require you to subclass NSApplication to customize app behavior. Instead it gives you many other ways to customize an app. This section discusses both some of the possible reasons to subclass NSApplication and some of the reasons not to subclass NSApplication.

To use a custom subclass of NSApplication, send sharedApplication to your subclass rather than directly to NSApplication. If you create your app in Xcode, you can accomplish this by setting your custom app class to be the principal class. In Xcode, double-click the app target in the Groups and Files list to open the Info window for the target. Then display the Properties pane of the window and replace “NSApplication” in the Principal Class field with the name of your custom class. The NSApplicationMain function sends sharedApplication to the principal class to obtain the global app instance (NSApp)—which in this case will be an instance of your custom subclass of NSApplication.

Methods to Override

Generally, you subclass NSApplication to provide your own special responses to messages that are routinely sent to the global app object (NSApp). NSApplication doesn’t have primitive methods in the sense of methods that you must override in your subclass. Here are four methods that are possible candidates for overriding:

  • Override run if you want the app to manage the main event loop differently than it does by default. (This a critical and complex task, however, that you should only attempt with good reason).

  • Override sendEvent: if you want to change how events are dispatched or perform some special event processing.

  • Override requestUserAttention: if you want to modify how your app attracts the attention of the user (for example, offering an alternative to the bouncing app icon in the Dock).

  • Override targetForAction: to substitute another object for the target of an action message.

Special Considerations

The global app object uses @autorelease blocks in its run method; if you override this method, you’ll need to create your own @autorelease blocks.

Do not override sharedApplication. The default implementation, which is essential to app behavior, is too complex to duplicate on your own.

Alternatives to Subclassing

NSApplication defines numerous Delegation methods that offer opportunities for modifying specific aspects of app behavior. Instead of making a custom subclass of NSApplication, your app delegate may be able to implement one or more of these methods to accomplish your design goals. In general, a better design than subclassing NSApplication is to put the code that expresses your app’s special behavior into one or more custom objects called controllers. Methods defined in your controllers can be invoked from a small dispatcher object without being closely tied to the global app object.

Topics

Getting the Shared App Object

sharedApplication

Returns the application instance, creating it if it doesn’t exist yet.

NSApp

The global variable for the shared app instance.

Managing the App's Behavior

delegate

The app delegate object.

NSApplicationDelegate

A set of methods that delegates of NSApplication objects can implement.

Managing the Event Loop

- nextEventMatchingMask:untilDate:inMode:dequeue:

Returns the next event matching a given mask, or nil if no such event is found before a specified expiration date.

- discardEventsMatchingMask:beforeEvent:

Removes all events matching the given mask and generated before the specified event.

currentEvent

The last event object that the app retrieved from the event queue.

running

A Boolean value indicating whether the main event loop is running.

- run

Starts the main event loop.

- finishLaunching

Activates the app, opens any files specified by the NSOpen user default, and unhighlights the app’s icon.

- stop:

Stops the main event loop.

- sendEvent:

Dispatches an event to other objects.

- postEvent:atStart:

Adds a given event to the receiver’s event queue.

NSEventTrackingRunLoopMode

A run loop should be set to this mode when tracking events modally, such as a mouse-dragging loop.

Posting Actions

- tryToPerform:with:

Dispatches an action message to the specified target.

- sendAction:to:from:

Sends the given action message to the given target.

- targetForAction:

Returns the object that receives the action message specified by the given selector.

- targetForAction:to:from:

Searches for an object that can receive the message specified by the given selector.

Terminating the App

- terminate:

Terminates the receiver.

- replyToApplicationShouldTerminate:

Responds to NSTerminateLater once the app knows whether it can terminate.

Activating and Deactivating the App

active

A Boolean value indicating whether this is the active app.

- activateIgnoringOtherApps:

Makes the receiver the active app.

- deactivate

Deactivates the receiver.

Managing Relaunch on Login

- disableRelaunchOnLogin

Disables relaunching the app on login.

- enableRelaunchOnLogin

Enables relaunching the app on login.

Managing Remote Notifications

- registerForRemoteNotifications

Register for notifications sent by Apple Push Notification service (APNs).

- unregisterForRemoteNotifications

Unregister for notifications received from Apple Push Notification service.

enabledRemoteNotificationTypes

The types of push notifications that the app accepts.

- registerForRemoteNotificationTypes:

Register to receive notifications of the specified types from a provider through the Apple Push Notification service.

registeredForRemoteNotifications

A Boolean value indicating whether the app is registered with Apple Push Notification service (APNs).

NSRemoteNotificationType

These constants determine whether apps launched by remote notifications display a badge.

Managing the App's Appearance

appearance

The appearance associated with the app’s windows.

effectiveAppearance

The appearance that AppKit uses to draw the app’s interface.

currentSystemPresentationOptions

The set of app presentation options that are currently in effect for the system.

presentationOptions

The presentation options that should be in effect for the system when this app is active.

NSApplicationPresentationOptions

Constants that control the presentation of the app, typically for fullscreen apps such as games or kiosks.

Managing Windows, Panels, and Menus

App Windows

Show, hide, minimize, arrange, and update your app's windows.

Modal Windows and Panels

Display a modal window or show one of the standard app panels, such as the app's About panel.

User Interface Layout Direction

userInterfaceLayoutDirection

The layout direction of the user interface.

NSUserInterfaceLayoutDirection

Specifies the directional flow of the user interface.

Accessing the Dock Tile

dockTile

The app’s Dock tile.

applicationIconImage

The image used for the app’s icon.

Customizing the Touch Bar

- toggleTouchBarCustomizationPalette:

Show or hides the interface for customizing the Touch Bar.

Managing User Attention Requests

- requestUserAttention:

Starts a user attention request.

NSRequestUserAttentionType

These constants specify the level of severity of a user attention request and are used by cancelUserAttentionRequest: and requestUserAttention:.

- cancelUserAttentionRequest:

Cancels a previous user attention request.

- replyToOpenOrPrint:

Handles errors that might occur when the user attempts to open or print files.

NSApplicationDelegateReply

Constants that indicate whether a copy or print operation was successful, was canceled, or failed.

Providing Help Information

- registerUserInterfaceItemSearchHandler:

Register an object that provides help data to your app.

- searchString:inUserInterfaceItemString:searchRange:foundRange:

Searches for the string in the user interface.

- unregisterUserInterfaceItemSearchHandler:

Unregister an object that provides help data to your app.

- showHelp:

If your project is properly registered, and the necessary keys have been set in the property list, this method launches Help Viewer and displays the first page of your app’s help book.

- activateContextHelpMode:

Places the receiver in context-sensitive help mode.

helpMenu

The help menu used by the app.

Providing Services

- validRequestorForSendType:returnType:

Indicates whether the receiver can send and receive the specified pasteboard types.

servicesProvider

The object that provides the services the current app advertises in the Services menu of other apps.

Determining Access to the Keyboard

fullKeyboardAccessEnabled

A Boolean value indicating whether Full Keyboard Access is enabled in the Keyboard preference pane.

Hiding Apps

- hideOtherApplications:

Hides all apps, except the receiver.

- unhideAllApplications:

Unhides all apps, including the receiver.

Managing Threads

+ detachDrawingThread:toTarget:withObject:

Creates and executes a new thread based on the specified target and selector.

Logging Exceptions

- reportException:

Logs a given exception by calling NSLog().

Configuring the Activation Policy

- activationPolicy

Returns the app’s activation policy.

- setActivationPolicy:

Attempts to modify the app’s activation policy.

NSApplicationActivationPolicy

Activation policies (used by activationPolicy) that control whether and how an app may be activated.

Scripting Your App

orderedDocuments

An array of document objects arranged according to the front-to-back ordering of their associated windows.

orderedWindows

An array of window objects arranged according to their front-to-back ordering on the screen.

- application:delegateHandlesKey:

Sent by Cocoa’s built-in scripting support during execution of get or set script commands to find out if the delegate can handle operations on the specified key-value key.

Deprecated

Notifications

These notifications apply to NSApplication. See Notifications in NSWorkspace for additional, similar notifications.

NSApplicationDidBecomeActiveNotification

Posted immediately after the app becomes active.

NSApplicationDidChangeScreenParametersNotification

Posted when the configuration of the displays attached to the computer is changed.

NSApplicationDidFinishLaunchingNotification

Posted at the end of the finishLaunching method to indicate that the app has completed launching and is ready to run.

NSApplicationDidHideNotification

Posted at the end of the hide: method to indicate that the app is now hidden.

NSApplicationDidResignActiveNotification

Posted immediately after the app gives up its active status to another app.

NSApplicationDidUnhideNotification

Posted at the end of the unhideWithoutActivation method to indicate that the app is now visible.

NSApplicationDidUpdateNotification

Posted at the end of the updateWindows method to indicate that the app has finished updating its windows.

NSApplicationWillBecomeActiveNotification

Posted immediately before the app becomes active.

NSApplicationWillFinishLaunchingNotification

Posted at the start of the finishLaunching method to indicate that the app has completed its initialization process and is about to finish launching.

NSApplicationWillHideNotification

Posted at the start of the hide: method to indicate that the app is about to be hidden.

NSApplicationWillResignActiveNotification

Posted immediately before the app gives up its active status to another app.

NSApplicationWillTerminateNotification

Posted by the terminate: method to indicate that the app will terminate.

NSApplicationWillUnhideNotification

Posted at the start of the unhideWithoutActivation method to indicate that the app is about to become visible.

NSApplicationWillUpdateNotification

Posted at the start of the updateWindows method to indicate that the app is about to update its windows.

NSApplicationDidFinishRestoringWindowsNotification

Posted when the app has finished restoring windows.

NSApplicationDidChangeOcclusionStateNotification

Posted when the app’s occlusion state changes.

Loading Cocoa Bundles

NSApplicationLoad

Startup function to call when running Cocoa code from a Carbon application.

See Also

Application

NSRunningApplication

An object that can manipulate and provide information for a single instance of an app.

NSApplicationDelegate

A set of methods that delegates of NSApplication objects can implement.

NSApplicationMain

Called by the main function to create and run the application.