Instance Method

beginModalSessionForWindow:

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

Declaration

- (NSModalSession)beginModalSessionForWindow:(NSWindow *)window;

Parameters

aWindow

The window for the session.

Return Value

A pointer to the NSModalSession structure that represents the session.

Discussion

In a modal session, the app receives mouse events only if they occur in aWindow. The window is made key, and if not already visible is placed onscreen using the NSWindow method center.

The beginModalSessionForWindow: method only sets up the modal session. To actually run the session, use runModalSession:. beginModalSessionForWindow: should be balanced by endModalSession:. Make sure these two messages are sent within the same exception-handling scope. That is, if you send beginModalSessionForWindow: inside an NS_DURING construct, you must send endModalSession: before NS_ENDHANDLER.

If an exception is raised, beginModalSessionForWindow: arranges for proper cleanup. Do not use NS_DURING constructs to send an endModalSession: message in the event of an exception.

A loop using these methods is similar to a modal event loop run with runModalForWindow:, except the app can continue processing between method invocations.

See Also

Running a Modal Window

- runModalForWindow:

Starts a modal event loop for the specified 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:.

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