Extends
Constructor
new OO.ui.Window([config])abstract
#
A window is a container for elements that are in a child frame. They are used with a window manager (OO.ui.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 (e.g., ‘small’, ‘medium’, ‘large’), which is interpreted by the window manager. If the requested size is not recognized, the window manager will choose a sensible fallback.
The lifecycle of a window has three primary stages (opening, opened, and closing) in which different processes are executed:
opening: The opening stage begins when the window manager's
openWindow
or the window's open
methods are
used, and the window manager begins to open the window.
getSetupProcess
method is called and its result executedgetReadyProcess
method is called and its result executed
opened: The window is now open
closing: The closing stage begins when the window manager's
closeWindow
or the window's close
methods are used, and the window manager begins to close the
window.
getHoldProcess
method is called and its result executedgetTeardownProcess
method is called and its result executed. The window is now closed
Each of the window's processes (setup, ready, hold, and teardown) can be extended in subclasses
by overriding the window's #getSetupProcess, #getReadyProcess, #getHoldProcess and
#getTeardownProcess methods. Note that each process
is executed in series,
so asynchronous processing can complete. Always assume window processes are executed
asynchronously.
For more information, please see the OOUI documentation on MediaWiki.
Parameters:
Name | Type | Attributes | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
config |
Object |
optional |
Configuration options Properties:
|
- Mixes in:
- Source:
Properties
sizestatic
#
small
, medium
, large
, larger
or full
.
$focusTrapBefore
#
Set focus traps
It is considered best practice to trap focus in a loop within a modal dialog, even though with 'inert' support we could allow focus to break out to the browser chrome.
Set focus traps
It is considered best practice to trap focus in a loop within a modal dialog, even though with 'inert' support we could allow focus to break out to the browser chrome.
$overlay
#
Overlay element to use for the $overlay
configuration option of widgets that support it.
Things put inside it are overlaid on top of the window and are not bound to its dimensions.
See https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays.
MyDialog.prototype.initialize = function () {
...
const popupButton = new OO.ui.PopupButtonWidget( {
$overlay: this.$overlay,
label: 'Popup button',
popup: {
$content: $( '<p>Popup content.</p><p>More content.</p><p>Yet more content.</p>' ),
padded: true
}
} );
...
};
Properties:
Type | Description |
---|---|
jQuery |
$overlay
configuration option of widgets that support it.
Methods
close([data]) → {OO.ui.WindowInstance}
#
Close the window.
This method is a wrapper around a call to the window
manager’s closeWindow
method.
The window's #getHoldProcess and #getTeardownProcess methods are called during the closing phase of the window’s lifecycle and can be used to specify closing behavior each time the window closes.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window closing data |
Returns:
See OO.ui.WindowManager#closeWindow
- Type
- OO.ui.WindowInstance
Throws:
-
An error is thrown if the window is not attached to a window manager
- Type
- Error
focus([focusLast]) → {OO.ui.Window}chainable
#
Focus the window
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
focusLast |
boolean |
optional |
false | Focus the last focusable element in the window, instead of the first |
Returns:
The window, for chaining
- Type
- OO.ui.Window
getBodyHeight() → {number}
#
Get the height of the window body.
To get the height of the full window contents (the window body, head, and foot together), use #getContentHeight.
When this function is called, the window will temporarily have been resized to height=1px, so .scrollHeight measurements can be taken accurately.
Returns:
Height of the window body in pixels
- Type
- number
getClosestScrollableElementContainer() → {HTMLElement}
#
Get closest scrollable container.
- Inherited from:
- Source:
Returns:
Closest scrollable container
- Type
- HTMLElement
getContentHeight() → {number}
#
Get the height of the full window contents (i.e., the window head, body and foot together).
What constitutes the head, body, and foot varies depending on the window type.
A message dialog
displays a title and message in its body,
and any actions in the foot. A process dialog
displays a title
and special actions in the head, and dialog content in the body.
To get just the height of the dialog body, use the #getBodyHeight method.
Returns:
The height of the window contents (the dialog head, body and foot) in pixels
- Type
- number
getData() → {any}
#
Get element data.
- Inherited from:
- Source:
Returns:
Element data
- Type
- any
getDir() → {string}
#
getElementDocument() → {HTMLDocument}
#
getElementGroup() → {OO.ui.mixin.GroupElement|null
}
#
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
Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.
getElementWindow() → {Window}
#
getHoldProcess([data]) → {OO.ui.Process}
#
Get the 'hold' process.
The hold process is used to keep a window from being used in a particular context, based on the
data
argument. This method is called during the closing phase of the window’s lifecycle (before
the closing animation). You can close dropdowns of elements in the window in this process, if
they do not get closed automatically.
Override this method to add additional steps to the 'hold' process the parent method provides
using the first
and next
methods
of OO.ui.Process.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window closing data |
Returns:
Hold process
- Type
- OO.ui.Process
getManager() → {OO.ui.WindowManager}
#
Get the window manager.
All windows must be attached to a window manager, which is used to open and close the window and control its presentation.
Returns:
Manager of window
- Type
- OO.ui.WindowManager
getReadyProcess([data]) → {OO.ui.Process}
#
Get the ‘ready’ process.
The ready process is used to ready a window for use in a particular context, based on the data
argument. This method is called during the opening phase of the window’s lifecycle, after the
window has been setup
(after the opening animation). You can focus
elements in the window in this process, or open their dropdowns.
Override this method to add additional steps to the ‘ready’ process the parent method
provides using the first
and next
methods of OO.ui.Process.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window opening data |
Returns:
Ready process
- Type
- OO.ui.Process
getSetupProcess([data]) → {OO.ui.Process}
#
Get the 'setup' process.
The setup process is used to set up a window for use in a particular context, based on the data
argument. This method is called during the opening phase of the window’s lifecycle (before the
opening animation). You can add elements to the window in this process or set their default
values.
Override this method to add additional steps to the ‘setup’ process the parent method provides
using the first
and next
methods
of OO.ui.Process.
To add window content that persists between openings, you may wish to use the #initialize method instead.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window opening data |
Returns:
Setup process
- Type
- OO.ui.Process
getSize() → {string}
#
small
or medium
).
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
getTeardownProcess([data]) → {OO.ui.Process}
#
Get the ‘teardown’ process.
The teardown process is used to teardown a window after use. During teardown, user interactions
within the window are conveyed and the window is closed, based on the data
argument. This
method is called during the closing phase of the window’s lifecycle (after the closing
animation). You can remove elements in the window in this process or clear their values.
Override this method to add additional steps to the ‘teardown’ process the parent method provides
using the first
and next
methods
of OO.ui.Process.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window closing data |
Returns:
Teardown process
- Type
- OO.ui.Process
hold([data]) → {jQuery.Promise}
#
Hold window.
This is called by OO.ui.WindowManager during window closing (before the animation), and should not be called directly by other systems.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window closing data |
Returns:
Promise resolved when window is held
- Type
- jQuery.Promise
initialize() → {OO.ui.Window}chainable
#
Initialize window contents.
Before the window is opened for the first time, #initialize is called so that content that persists between openings can be added to the window.
To set up a window with new content each time the window opens, use #getSetupProcess.
Returns:
The window, for chaining
- Type
- OO.ui.Window
Throws:
-
An error is thrown if the window is not attached to a window manager
- Type
- Error
isClosing() → {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
isInitialized() → {boolean}
#
isOpened() → {boolean}
#
isOpening() → {boolean}
#
isVisible() → {boolean}
#
Check if the window is visible.
- Overrides:
- Source:
Returns:
Window is visible
- Type
- boolean
onFocusTrapFocused(event)
#
Called when someone tries to focus the hidden element at the end of the dialog. Sends focus back to the start of the dialog.
Parameters:
Name | Type | Description |
---|---|---|
event |
jQuery.Event | Focus event |
open([data]) → {OO.ui.WindowInstance}
#
Open the window.
This method is a wrapper around a call to the window
manager’s openWindow
method.
To customize the window each time it opens, use #getSetupProcess or #getReadyProcess.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window opening data |
Returns:
See OO.ui.WindowManager#openWindow
- Type
- OO.ui.WindowInstance
Throws:
-
An error is thrown if the window is not attached to a window manager
- Type
- Error
ready([data]) → {jQuery.Promise}
#
Ready window.
This is called by OO.ui.WindowManager during window opening (after the animation), and should not be called directly by other systems.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window opening data |
Returns:
Promise resolved when window is ready
- Type
- jQuery.Promise
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:
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
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
setDimensions(dim) → {OO.ui.Window}chainable
#
Set window dimensions. This method is called by the window manager
when the window is opening. In general, setDimensions should not be called directly.
To set the size of the window, use the #setSize method.
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
dim |
Object | CSS dimension properties Properties:
|
Returns:
The window, for chaining
- Type
- OO.ui.Window
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
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
setManager(manager) → {OO.ui.Window}chainable
#
Set the window manager.
This will cause the window to initialize. Calling it more than once will cause an error.
Parameters:
Name | Type | Description |
---|---|---|
manager |
OO.ui.WindowManager | Manager for this window |
Returns:
The window, for chaining
- Type
- OO.ui.Window
Throws:
-
An error is thrown if the method is called more than once
- Type
- Error
setSize(size) → {OO.ui.Window}chainable
#
Set the window size by symbolic name (e.g., 'small' or 'medium')
Parameters:
Name | Type | Description |
---|---|---|
size |
string | Symbolic name of size: |
Returns:
The window, for chaining
- Type
- OO.ui.Window
setup([data]) → {jQuery.Promise}
#
Setup window.
This is called by OO.ui.WindowManager during window opening (before the animation), and should not be called directly by other systems.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window opening data |
Returns:
Promise resolved when window is setup
- Type
- jQuery.Promise
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
teardown([data]) → {jQuery.Promise}
#
Teardown window.
This is called by OO.ui.WindowManager during window closing (after the animation), and should not be called directly by other systems.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
Object |
optional |
Window closing data |
Returns:
Promise resolved when window is torn down
- Type
- jQuery.Promise
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:
Returns:
The element, for chaining
- Type
- OO.ui.Element
Fires:
updateSize() → {OO.ui.Window}chainable
#
Update the window size.
Returns:
The window, for chaining
- Type
- OO.ui.Window
Throws:
-
An error is thrown if the window is not attached to a window manager
- Type
- Error
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: