Instance Method

runModalForWindow:

Starts a modal event loop for the specified window.

Declaration

- (NSModalResponse)runModalForWindow:(NSWindow *)window;

Parameters

window

The window to be displayed modally. If it is not already visible, the window is centered on the screen using the value in its center method and made visible and key. If it is already visible, it is simply made key.

Return Value

An integer indicating the reason that this method returned. See NSModalResponse possible return values.

Discussion

This method runs a modal event loop for the specified window synchronously. It displays the specified window, makes it key, starts the run loop, and processes events for that window. (You do not need to show the window yourself.) While the app is in that loop, it does not respond to any other events (including mouse, keyboard, or window-close events) unless they are associated with the window. It also does not perform any tasks (such as firing timers) that are not associated with the modal run loop. In other words, this method consumes only enough CPU time to process events and dispatch them to the action methods associated with the modal window.

You can exit the modal loop by calling the stopModal, stopModalWithCode:, or abortModal methods from your modal window code. If you use the stopModalWithCode: method to stop the modal event loop, this method returns the argument passed to stopModalWithCode:. If you use stopModal instead, this method returns the constant NSModalResponseStop. If you use abortModal, this method returns the constant NSModalResponseAbort.

See Also

Running a Modal Window

- stopModal

Stops a modal event loop.

- stopModalWithCode:

Stops a modal event loop, allowing you to return a custom result code.

- abortModal

Aborts the event loop started by runModalForWindow: or runModalSession:.

- beginModalSessionForWindow:

Sets up a modal session with the given window and returns a pointer to the NSModalSession structure representing the session.

- runModalSession:

Runs a given modal session, as defined in a previous invocation of beginModalSessionForWindow:.

modalWindow

The modal window displayed by the app.

NSModalResponse

A set of button return values for modal dialogs.

NSModalSession

Variables of type NSModalSession point to information used by the system between NSApplication’s beginModalSessionForWindow: and endModalSession: messages.

NSModalPanelRunLoopMode

A run loop should be set to this mode when waiting for input from a modal panel, such as NSSavePanel or NSOpenPanel.