Expand all

OO.ui.WindowManager

Extends

Constructor

new OO.ui.WindowManager([config]) #

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 on-going 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 getHoldProcess 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 OOUI 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 current window
forceTrapFocus boolean optional

Force the trapping of focus within windows. This is done automatically for modal window managers and full screen windows.
Mixes in:
Source:

Window managers are used to open and close windows and control their presentation.

Properties

defaultSizestatic #

Symbolic name of the default window size.

The default size is used if the window's requested size is not recognized.

Properties:

Type Description
string
Source:
Symbolic name of the default window size.

sizesstatic #

Map of the symbolic name of each window size and its CSS properties.

Symbolic name must be valid as a CSS class name suffix.

Properties:

Type Description
Object
Source:
Map of the symbolic name of each window size and its CSS properties.

Methods

addWindows(windows) #

Add windows to the window manager.

Windows can be added by reference, symbolic name, or explicitly defined symbolic names. See the [OOUI documentation on MediaWiki][2] for examples. [2]: https://www.mediawiki.org/wiki/OOUI/Windows/Window_managers

This function can be called in two manners:

  1. .addWindows( [ winA, winB, ... ] ) (where winA, winB 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: winA, nameB: winB, ... } )

    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:

const windowManager = new OO.ui.WindowManager();
$( document.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
Add windows to the window manager.

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
Remove all windows from the window manager.

closeWindow(win, [data]) → {OO.ui.WindowInstance} #

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
Close a window.

destroy() #

Destroy the window manager.

Source:
Destroy the window manager.

getClosestScrollableElementContainer() → {HTMLElement} #

Get closest scrollable container.

Inherited from:
Source:

Returns:

Closest scrollable container

Type
HTMLElement
Get closest scrollable container.

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

Get current window.

Source:

Returns:

Currently opening/opened/closing window

Type
OO.ui.Window | null
Get current window.

getData() → {any} #

Get element data.

Inherited from:
Source:

Returns:

Element data

Type
any
Get element data.

getElementDocument() → {HTMLDocument} #

Get the DOM document.

Inherited from:
Source:

Returns:

Document object

Type
HTMLDocument
Get the DOM document.

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
Get group element is in.

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

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

getElementWindow() → {Window} #

Get the DOM window.

Inherited from:
Source:

Returns:

Window object

Type
Window
Get the DOM window.

getHoldDelay(win, [data]) → {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

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

getReadyDelay(win, [data]) → {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

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

getSetupDelay(win, [data]) → {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
Get the number of milliseconds to wait after opening begins before executing the ‘setup’ process.

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
Get the HTML tag name.

getTeardownDelay(win, [data]) → {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

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

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 [OOUI documentation on MediaWiki][3] for more information about using factories. [3]: https://www.mediawiki.org/wiki/OOUI/Windows/Window_managers

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
Get a window by its symbolic name.

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
Check if a window is being managed.

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
Check if window is closing.

isElementAttached() → {boolean} #

Check if the element is attached to the DOM

Inherited from:
Source:

Returns:

The element is attached to the DOM

Type
boolean
Check if the element is attached to the DOM

isModal() → {boolean} #

Check if the window manager is modal, preventing interaction outside the current window

Source:

Returns:

The window manager is modal

Type
boolean
Check if the window manager is modal, preventing interaction outside the current window

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
Check if window is opened.

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
Check if window is opening.

isVisible() → {boolean} #

Check if element is visible.

Inherited from:
Source:

Returns:

element is visible

Type
boolean
Check if element is visible.

openWindow(win, [data], [lifecycle], [compatOpening]) → {OO.ui.WindowInstance} #

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.
lifecycle OO.ui.WindowInstance optional

Used internally
compatOpening jQuery.Deferred optional

Used internally
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
Open a window.

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
Remove the specified windows from the windows manager.

restorePreInfuseState(state)protected #

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:
Restore the pre-infusion dynamic state for this widget.

scrollElementIntoView([config]) → {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
Scroll element into view.

setData(data) → {OO.ui.Element}chainable #

Set element data.

Parameters:

Name Type Description
data any

Element data
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set element data.

setElementGroup(group) → {OO.ui.Element}chainable #

Set group element is in.

Parameters:

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

Group element, null if none
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set group element is in.

setElementId(id) → {OO.ui.Element}chainable #

Set the element has an 'id' attribute.

Parameters:

Name Type Description
id string
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set the element has an 'id' attribute.

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
Check if element supports one or more methods.

toggle([show]) → {OO.ui.Element}chainable #

Toggle visibility of an element.

Parameters:

Name Type Attributes Description
show boolean optional

Make element visible, omit to toggle visibility
Inherited from:
Source:

Fires:

Returns:

The element, for chaining

Type
OO.ui.Element
Toggle visibility of an element.

updateThemeClasses() #

Update the theme-provided classes.

This is called in element mixins and widget classes any time state changes. Updating is debounced, minimizing overhead of changing multiple attributes and guaranteeing that theme updates do not occur within an element's constructor

Inherited from:
Source:
Update the theme-provided classes.

updateWindowSize(win) → {OO.ui.WindowManager}chainable #

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:

Returns:

The manager, for chaining

Type
OO.ui.WindowManager
Set dialog size.

Events

closing(win, closed, data) #

A 'closing' event is emitted when the window begins to be closed.

Parameters:

Name Type Description
win OO.ui.Window

Window that's being closed
closed jQuery.Promise

A promise resolved with a value when the window is closed successfully. This promise also emits hold and teardown notifications. When this promise is resolved, the first argument of its value is the closing data.
data Object

Window closing data
Source:
A 'closing' event is emitted when the window begins to be closed.

opening(win, opened, data) #

An 'opening' event is emitted when the window begins to be opened.

Parameters:

Name Type Description
win OO.ui.Window

Window that's being opened
opened jQuery.Promise

A promise resolved with a value when the window is opened successfully. This promise also emits setup and ready notifications. When this promise is resolved, the first argument of the value is an 'closed' promise, the second argument is the opening data.
data Object

Window opening data
Source:
An 'opening' event is emitted when the window begins to be opened.

resize(win) #

A 'resize' event is emitted when a window is resized.

Parameters:

Name Type Description
win OO.ui.Window

Window that was resized
Source:
A 'resize' event is emitted when a window is resized.