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.

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.

Managed windows are mutually exclusive. If a new window is opened while a current window is opening or is opened, the current window will be closed, and any ongoing process will be cancelled. Windows themselves are persistent and—rather than being torn down when closed—can be repopulated with the pertinent data and reused.

Over the lifecycle of a window, the WindowManager makes available three promises: ‘opening’, ‘opened’, and ‘closing’, which represent the primary stages of the cycle. The ‘opening’ promise is resolved when window is opened, the ‘opened’ promise is resolved when the window begins closing, and the ‘closing’ promise is resolved when the window is done closing. See Process dialogs, for examples that show this promise chain in practice.

The first time the window is opened (and only the first time), the initialize method is called before opening. 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.

 

Opening
The opening stage begins when the window manager’s openWindow or the window’s open method is used to open a window. 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 opening promise. When a window is ‘ready’ everything is set up and visible,  and it is okay to set the focus.

Opened
When the window is set up and ready, the ‘opening’ promise is resolved with an ‘opened’ promise. The window is now opened.

Closing
The closing stage begins when the window manager’s closeWindow or the window’s close method is used to close a window. The window manager emits a ‘closing’ event and the ‘opened’ promise is resolved with a ‘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 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. During teardown, any data passed to the close method will be conveyed and the window closed. When the teardown process is complete, a ‘teardown’ progress notification is emitted from the closing promise, which is then resolved. The window is now closed.

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 isolate window content using inline frames (by setting the isolate option to ‘true’) or 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.