OOUI/Windows

A Window is a container for elements in a child frame. Each window is managed by a WindowManager, which is used to open and close the window, and control its presentation. The size of a window is specified using a symbolic name ('small', 'medium', 'large', or 'full'), which is interpreted by the window manager. If the requested size is not recognized, the window manager will choose a sensible fallback.

OOUI windows include Dialog, ProcessDialog, and MessageDialog. For simple use cases, several convenience functions exist. See OOUI/Windows/Simple messages.

Note that windows are responsive to the size of the viewing device and will dynamically adjust their display accordingly. The size of the dialog should therefore be considered an approximation rather than an exact specification.

Window lifecycle

Managed windows are mutually exclusive. A new window cannot be opened while a current window is opened. Windows themselves are persistent and—rather than being torn down when closed—can be repopulated with the pertinent data and reused.

The lifecycle of a window is represented by a WindowInstance object. This object has four properties, containing promises that represent the primary stages of the cycle: 'opening', 'opened', 'closing', and 'closed'.

• The opening promise is resolved after the window has started opening (this may be delayed if another window is still closing), with the 'data' value passed to the openWindow() call.
• The opened promise is resolved after the window is opened, with the 'data' value passed to the openWindow() call.
• The closing promise is resolved after the window has started closing, with the 'data' value passed to the closeWindow() call.
• The closed promise is resolved after the window is closed, with the 'data' value passed to the closeWindow() call.

See Process dialogs, for examples that show this promise chain in practice.

For backwards compatibility, WindowInstance objects returned by openWindow() and closeWindow() are extended with Promise-like properties. This will be removed in the future.

Before the window is opened for the first time (and only before the first time), the initialize() method is called. The initialize() method is used to populate the window with persistent content, providing a sort of caching mechanism. A window that contains a list of 250 languages can be populated with that list during initialization, for example, and if the window is opened again, the list will not have to be reloaded.

Steps

Opening

The opening stage begins when the window manager’s openWindow() or the window’s open() method is used to open a window. WindowInstance's 'opening' promise is resolved. For backwards compatibility, the window manager emits an 'opening' event with a promise that will be resolved with an 'opened' promise when the window is setup, ready, and opened.

The window manager then calls the getSetupDelay() method, which gets the number of milliseconds to wait before calling the window’s getSetupProcess() method and executing the result. The getSetupProcess() method assembles a process for setting up the window with data passed to the opening function. Each time a window is reused, it can be set up with new data. When setup is complete, a 'setup' progress notification is emitted from the opening promise.

The window manager then calls the getReadyDelay() method, which gets the number of milliseconds to wait between finishing setup and calling the window’s getReadyProcess() method and executing the result. A 'ready' progress notification is then emitted from the backwards-compatibility opening promise.

Opened

When the window is set up and ready, WindowInstance's 'opened' promise is resolved, and the backwards-compatibility 'opening' promise is resolved with a backwards-compatibility 'opened' promise. The window is now opened.  At this point it is okay to set the focus inside the window.

Closing

The closing stage begins when the window manager’s closeWindow() or the window’s close() method is used to close a window. WindowInstance's 'closing' promise is resolved. For backwards compatibility, the window manager emits a 'closing' event and the backwards-compatibility 'opened' promise is resolved with a backwards-compatibility 'closing' promise.

The window manager calls the getHoldDelay() method, which gets the number of milliseconds to wait before calling the window’s getHoldProcess() method and executing the result. There is rarely a need to override this method, though one might if a window requires a long time to teardown and you wish to disable the window controls in the meantime. When the hold process is complete, a 'hold' progress notification is emitted from the backwards-compatibility closing promise.

The window manager then calls the getTeardownDelay() method, which gets the number of milliseconds to wait between finishing the hold process and calling the window’s getTeardownProcess() method and executing the result. A 'teardown' progress notification is emitted from the backwards-compatibility closing promise.

Closed

When the teardown process is complete, WindowInstance's 'closed' promise is resolved, the backwards-compatibility closing promise is resolved. Any data passed to the close() method will be passed as a resolution value to WindowInstance's 'closed' promise and the backwards-compatibility closing promise. The window is now closed.

Notes

Note that each process (e.g., setup, ready, hold, teardown) is executed in series, so asynchronous processing can complete. Always assume window processes are executed asynchronously. See Processes and errors for more details about processes.

Closing a window without data will safely close it without making any changes, essentially canceling the process.

The WindowManager can also be configured to prevent interaction outside the window (by setting the modal option to 'true'). For a full list of supported methods and configuration options, please see the code-level documentation.

WindowInstance usage example

instance = windowManager.openWindow( ... );
instance.opening.then( function () {
    // Code here runs after the window has started opening.
} );
instance.opened.then( function () {
    // Code here runs after the window is opened.
} );
instance.closing.then( function () {
    // Code here runs after the window has started closing.
} );
instance.closed.then( function ( data ) {
    // Code here runs after the window is closed.
} );

If you just want to open window and wait for it to be closed, use:

windowManager.openWindow( ... ).closed.then( function ( data ) {
    // Code here runs after the window is closed.
} );