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.

OOjs UI windows include Dialog, ProcessDialog, and MessageDialog. For simple use cases, several convenience functions exist. See OOjs UI/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’. See Process dialogs, for examples that show this promise chain in practice.
 * The opening promise is resolved after the window has started opening (this may be delayed if another window is still being closed), 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.

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.



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.

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