Class: WindowManager

.ui.WindowManager(configopt)

new WindowManager(configopt)

Window managers are used to open and close windows and control their presentation. 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 window manager makes available three promises: opening, opened, and closing, which represent the primary stages of the cycle:

Opening: the opening stage begins when the window manager’s #openWindow or a window’s open method is used, and the window manager begins to open the window.

  • an opening event is emitted with an opening promise
  • the #getSetupDelay method is called and the returned value is used to time a pause in execution before the window’s setup method is called which executes OO.ui.Window#getSetupProcess.
  • a setup progress notification is emitted from the opening promise
  • the #getReadyDelay method is called the returned value is used to time a pause in execution before the window’s ready method is called which executes OO.ui.Window#getReadyProcess.
  • a ready progress notification is emitted from the opening promise
  • the opening promise is resolved with an opened promise

Opened: the window is now open.

Closing: the closing stage begins when the window manager's #closeWindow or the window's close methods is used, and the window manager begins to close the window.

  • the opened promise is resolved with closing promise and a closing event is emitted
  • the #getHoldDelay method is called and the returned value is used to time a pause in execution before the window's getHoldProces method is called on the window and its result executed
  • a hold progress notification is emitted from the closing promise
  • the #getTeardownDelay() method is called and the returned value is used to time a pause in execution before the window's getTeardownProcess method is called on the window and its result executed
  • a teardown progress notification is emitted from the closing promise
  • the closing promise is resolved. The window is now closed

See the OOjs UI documentation on MediaWiki for more information.

Parameters:
Name Type Attributes Description
config Object <optional>

Configuration options

Properties
Name Type Attributes Default Description
factory OO.Factory <optional>

Window factory to use for automatic instantiation Note that window classes that are instantiated with a factory must have a static name property that specifies a symbolic name.
modal boolean <optional>
 true

Prevent interaction outside the dialog
Mixes In:
  • OO.EventEmitter
Source:

Extends

Methods

addWindows(windows)

Add windows to the window manager.

Windows can be added by reference, symbolic name, or explicitly defined symbolic names. See the OOjs ui documentation on MediaWiki for examples.

This function can be called in two manners:

  1. .addWindows( [ windowA, windowB, ... ] ) (where windowA, windowB are OO.ui.Window objects)

    This syntax registers windows under the symbolic names defined in their .static.name properties. For example, if windowA.constructor.static.name is 'nameA', calling .openWindow( 'nameA' ) afterwards will open the window windowA. This syntax requires the static name to be set, otherwise an exception will be thrown.

    This is the recommended way, as it allows for an easier switch to using a window factory.

  2. .addWindows( { nameA: windowA, nameB: windowB, ... } )

    This syntax registers windows under the explicitly given symbolic names. In this example, calling .openWindow( 'nameA' ) afterwards will open the window windowA, regardless of what its .static.name is set to. The static name is not required to be set.

    This should only be used if you need to override the default symbolic names.

Example:

var windowManager = new OO.ui.WindowManager();
$( 'body' ).append( windowManager.$element );

// Add a window under the default name: see OO.ui.MessageDialog.static.name
windowManager.addWindows( [ new OO.ui.MessageDialog() ] );
// Add a window under an explicit name
windowManager.addWindows( { myMessageDialog: new OO.ui.MessageDialog() } );

// Open window by default name
windowManager.openWindow( 'message' );
// Open window by explicitly given name
windowManager.openWindow( 'myMessageDialog' );
Parameters:
Name Type Description
windows Object.<string, OO.ui.Window> | Array.<OO.ui.Window>

An array of window objects specified by reference, symbolic name, or explicitly defined symbolic names.
Source:
Throws:

An error is thrown if a window is added by symbolic name, but has neither an explicit nor a statically configured symbolic name.

Type
Error

clearWindows() → {jQuery.Promise}

Remove all windows from the window manager.

Windows will be closed before they are removed. Note that the window manager, though not in use, will still listen to events. If the window manager will not be used again, you may wish to use the #destroy method instead. To remove just a subset of windows, use the #removeWindows method.

Source:
Returns:

Promise resolved when all windows are closed and removed

Type
jQuery.Promise

closeWindow(win, dataopt) → {OO.ui.WindowInstance|jQuery.Promise}

Close a window.

Parameters:
Name Type Attributes Description
win OO.ui.Window | string

Window object or symbolic name of window to close
data Object <optional>

Window closing data
Source:
Fires:
Returns:

A lifecycle object representing this particular opening of the window. For backwards-compatibility, the object is also a Thenable that is resolved when the window is done closing, see T163510.

Type
OO.ui.WindowInstance | jQuery.Promise

destroy()

Destroy the window manager.

Destroying the window manager ensures that it will no longer listen to events. If you would like to continue using the window manager, but wish to remove all windows from it, use the #clearWindows method instead.

Source:

getClosestScrollableElementContainer() → {HTMLElement}

Get closest scrollable container.

Inherited From:
Source:
Returns:

Closest scrollable container

Type
HTMLElement

getCurrentWindow() → {OO.ui.Window|null}

Get current window.

Source:
Returns:

Currently opening/opened/closing window

Type
OO.ui.Window | null

getData() → {Mixed}

Get element data.

Inherited From:
Source:
Returns:

Element data

Type
Mixed

getElementDocument() → {HTMLDocument}

Get the DOM document.

Inherited From:
Source:
Returns:

Document object

Type
HTMLDocument

getElementGroup() → {OO.ui.mixin.GroupElement|null}

Get group element is in.

Inherited From:
Source:
Returns:

Group element, null if none

Type
OO.ui.mixin.GroupElement | null

getElementId() → {string}

Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.

Inherited From:
Source:
Returns:
Type
string

getElementWindow() → {Window}

Get the DOM window.

Inherited From:
Source:
Returns:

Window object

Type
Window

getHoldDelay(win, dataopt) → {number}

Get the number of milliseconds to wait after closing has begun before executing the 'hold' process.

Parameters:
Name Type Attributes Description
win OO.ui.Window

Window being closed
data Object <optional>

Window closing data
Source:
Returns:

Milliseconds to wait

Type
number

getReadyDelay(win, dataopt) → {number}

Get the number of milliseconds to wait after setup has finished before executing the ‘ready’ process.

Parameters:
Name Type Attributes Description
win OO.ui.Window

Window being opened
data Object <optional>

Window opening data
Source:
Returns:

Milliseconds to wait

Type
number

getSetupDelay(win, dataopt) → {number}

Get the number of milliseconds to wait after opening begins before executing the ‘setup’ process.

Parameters:
Name Type Attributes Description
win OO.ui.Window

Window being opened
data Object <optional>

Window opening data
Source:
Returns:

Milliseconds to wait

Type
number

getTagName() → {string}

Get the HTML tag name.

Override this method to base the result on instance information.

Inherited From:
Source:
Returns:

HTML tag name

Type
string

getTeardownDelay(win, dataopt) → {number}

Get the number of milliseconds to wait after the ‘hold’ process has finished before executing the ‘teardown’ process.

Parameters:
Name Type Attributes Description
win OO.ui.Window

Window being closed
data Object <optional>

Window closing data
Source:
Returns:

Milliseconds to wait

Type
number

getWindow(name) → {jQuery.Promise}

Get a window by its symbolic name.

If the window is not yet instantiated and its symbolic name is recognized by a factory, it will be instantiated and added to the window manager automatically. Please see the OOjs UI documentation on MediaWiki for more information about using factories.

Parameters:
Name Type Description
name string

Symbolic name of the window
Source:
Throws:

  • An error is thrown if the symbolic name is not recognized by the factory.

    Type
    Error

  • An error is thrown if the named window is not recognized as a managed window.

    Type
    Error
Returns:

Promise resolved with matching window, or rejected with an OO.ui.Error

Type
jQuery.Promise

hasWindow(win) → {boolean}

Check if a window is being managed.

Parameters:
Name Type Description
win OO.ui.Window

Window to check
Source:
Returns:

Window is being managed

Type
boolean

isClosing(win) → {boolean}

Check if window is closing.

Parameters:
Name Type Description
win OO.ui.Window

Window to check
Source:
Returns:

Window is closing

Type
boolean

isElementAttached() → {boolean}

Check if the element is attached to the DOM

Inherited From:
Source:
Returns:

The element is attached to the DOM

Type
boolean

isOpened(win) → {boolean}

Check if window is opened.

Parameters:
Name Type Description
win OO.ui.Window

Window to check
Source:
Returns:

Window is opened

Type
boolean

isOpening(win) → {boolean}

Check if window is opening.

Parameters:
Name Type Description
win OO.ui.Window

Window to check
Source:
Returns:

Window is opening

Type
boolean

isVisible() → {boolean}

Check if element is visible.

Inherited From:
Source:
Returns:

element is visible

Type
boolean

openWindow(win, dataopt) → {OO.ui.WindowInstance|jQuery.Promise}

Open a window.

Parameters:
Name Type Attributes Description
win OO.ui.Window | string

Window object or symbolic name of window to open
data Object <optional>

Window opening data

Properties
Name Type Attributes Description
$returnFocusTo jQuery | null <optional>

Element to which the window will return focus when closed. Defaults the current activeElement. If set to null, focus isn't changed on close.
Source:
Fires:
Returns:

A lifecycle object representing this particular opening of the window. For backwards-compatibility, then object is also a Thenable that is resolved when the window is done opening, with nested promise for when closing starts. This behaviour is deprecated and is not compatible with jQuery 3. See T163510.

Type
OO.ui.WindowInstance | jQuery.Promise

removeWindows(names) → {jQuery.Promise}

Remove the specified windows from the windows manager.

Windows will be closed before they are removed. If you wish to remove all windows, you may wish to use the #clearWindows method instead. If you no longer need the window manager and want to ensure that it no longer listens to events, use the #destroy method.

Parameters:
Name Type Description
names Array.<string>

Symbolic names of windows to remove
Source:
Throws:

An error is thrown if the named windows are not managed by the window manager.

Type
Error
Returns:

Promise resolved when window is closed and removed

Type
jQuery.Promise

(protected) restorePreInfuseState(state)

Restore the pre-infusion dynamic state for this widget.

This method is called after #$element has been inserted into DOM. The parameter is the return value of #gatherPreInfuseState.

Parameters:
Name Type Description
state Object
Inherited From:
Source:

scrollElementIntoView(configopt) → {jQuery.Promise}

Scroll element into view.

Parameters:
Name Type Attributes Description
config Object <optional>

Configuration options
Inherited From:
Source:
Returns:

Promise which resolves when the scroll is complete

Type
jQuery.Promise

setData(data)

Set element data.

Parameters:
Name Type Description
data Mixed

Element data
Inherited From:
Source:

setElementGroup(group)

Set group element is in.

Parameters:
Name Type Description
group OO.ui.mixin.GroupElement | null

Group element, null if none
Inherited From:
Source:

setElementId(id)

Set the element has an 'id' attribute.

Parameters:
Name Type Description
id string
Inherited From:
Source:

supports(methods) → {boolean}

Check if element supports one or more methods.

Parameters:
Name Type Description
methods string | Array.<string>

Method or list of methods to check
Inherited From:
Source:
Returns:

All methods are supported

Type
boolean

toggle(showopt)

Toggle visibility of an element.

Parameters:
Name Type Attributes Description
show boolean <optional>

Make element visible, omit to toggle visibility
Inherited From:
Source:
Fires:
  • event:visible

updateThemeClasses()

Update the theme-provided classes.

Inherited From:
Source:

updateWindowSize(win)

Set dialog size. In general, this method should not be called directly.

Fullscreen mode will be used if the dialog is too wide to fit in the screen.

Parameters:
Name Type Description
win OO.ui.Window

Window to update, should be the current window
Source: