3 * https://www.mediawiki.org/wiki/OOjs_UI
5 * Copyright 2011–2016 OOjs UI Team and other contributors.
6 * Released under the MIT license
7 * http://oojs.mit-license.org
9 * Date: 2016-03-16T19:20:22Z
16 * Namespace for all classes, static methods and static properties.
48 * Constants for MouseEvent.which
52 OO
.ui
.MouseButtons
= {
64 * Generate a unique ID for element
66 * @return {string} [id]
68 OO
.ui
.generateElementId = function () {
70 return 'oojsui-' + OO
.ui
.elementId
;
74 * Check if an element is focusable.
75 * Inspired from :focusable in jQueryUI v1.11.4 - 2015-04-14
77 * @param {jQuery} $element Element to test
80 OO
.ui
.isFocusableElement = function ( $element
) {
82 element
= $element
[ 0 ];
84 // Anything disabled is not focusable
85 if ( element
.disabled
) {
89 // Check if the element is visible
91 // This is quicker than calling $element.is( ':visible' )
92 $.expr
.filters
.visible( element
) &&
93 // Check that all parents are visible
94 !$element
.parents().addBack().filter( function () {
95 return $.css( this, 'visibility' ) === 'hidden';
101 // Check if the element is ContentEditable, which is the string 'true'
102 if ( element
.contentEditable
=== 'true' ) {
106 // Anything with a non-negative numeric tabIndex is focusable.
107 // Use .prop to avoid browser bugs
108 if ( $element
.prop( 'tabIndex' ) >= 0 ) {
112 // Some element types are naturally focusable
113 // (indexOf is much faster than regex in Chrome and about the
114 // same in FF: https://jsperf.com/regex-vs-indexof-array2)
115 nodeName
= element
.nodeName
.toLowerCase();
116 if ( [ 'input', 'select', 'textarea', 'button', 'object' ].indexOf( nodeName
) !== -1 ) {
120 // Links and areas are focusable if they have an href
121 if ( ( nodeName
=== 'a' || nodeName
=== 'area' ) && $element
.attr( 'href' ) !== undefined ) {
129 * Find a focusable child
131 * @param {jQuery} $container Container to search in
132 * @param {boolean} [backwards] Search backwards
133 * @return {jQuery} Focusable child, an empty jQuery object if none found
135 OO
.ui
.findFocusable = function ( $container
, backwards
) {
136 var $focusable
= $( [] ),
137 // $focusableCandidates is a superset of things that
138 // could get matched by isFocusableElement
139 $focusableCandidates
= $container
140 .find( 'input, select, textarea, button, object, a, area, [contenteditable], [tabindex]' );
143 $focusableCandidates
= Array
.prototype.reverse
.call( $focusableCandidates
);
146 $focusableCandidates
.each( function () {
147 var $this = $( this );
148 if ( OO
.ui
.isFocusableElement( $this ) ) {
157 * Get the user's language and any fallback languages.
159 * These language codes are used to localize user interface elements in the user's language.
161 * In environments that provide a localization system, this function should be overridden to
162 * return the user's language(s). The default implementation returns English (en) only.
164 * @return {string[]} Language codes, in descending order of priority
166 OO
.ui
.getUserLanguages = function () {
171 * Get a value in an object keyed by language code.
173 * @param {Object.<string,Mixed>} obj Object keyed by language code
174 * @param {string|null} [lang] Language code, if omitted or null defaults to any user language
175 * @param {string} [fallback] Fallback code, used if no matching language can be found
176 * @return {Mixed} Local value
178 OO
.ui
.getLocalValue = function ( obj
, lang
, fallback
) {
181 // Requested language
185 // Known user language
186 langs
= OO
.ui
.getUserLanguages();
187 for ( i
= 0, len
= langs
.length
; i
< len
; i
++ ) {
194 if ( obj
[ fallback
] ) {
195 return obj
[ fallback
];
197 // First existing language
198 for ( lang
in obj
) {
206 * Check if a node is contained within another node
208 * Similar to jQuery#contains except a list of containers can be supplied
209 * and a boolean argument allows you to include the container in the match list
211 * @param {HTMLElement|HTMLElement[]} containers Container node(s) to search in
212 * @param {HTMLElement} contained Node to find
213 * @param {boolean} [matchContainers] Include the container(s) in the list of nodes to match, otherwise only match descendants
214 * @return {boolean} The node is in the list of target nodes
216 OO
.ui
.contains = function ( containers
, contained
, matchContainers
) {
218 if ( !Array
.isArray( containers
) ) {
219 containers
= [ containers
];
221 for ( i
= containers
.length
- 1; i
>= 0; i
-- ) {
222 if ( ( matchContainers
&& contained
=== containers
[ i
] ) || $.contains( containers
[ i
], contained
) ) {
230 * Return a function, that, as long as it continues to be invoked, will not
231 * be triggered. The function will be called after it stops being called for
232 * N milliseconds. If `immediate` is passed, trigger the function on the
233 * leading edge, instead of the trailing.
235 * Ported from: http://underscorejs.org/underscore.js
237 * @param {Function} func
238 * @param {number} wait
239 * @param {boolean} immediate
242 OO
.ui
.debounce = function ( func
, wait
, immediate
) {
247 later = function () {
250 func
.apply( context
, args
);
253 if ( immediate
&& !timeout
) {
254 func
.apply( context
, args
);
256 if ( !timeout
|| wait
) {
257 clearTimeout( timeout
);
258 timeout
= setTimeout( later
, wait
);
264 * Returns a function, that, when invoked, will only be triggered at most once
265 * during a given window of time. If called again during that window, it will
266 * wait until the window ends and then trigger itself again.
268 * As it's not knowable to the caller whether the function will actually run
269 * when the wrapper is called, return values from the function are entirely
272 * @param {Function} func
273 * @param {number} wait
276 OO
.ui
.throttle = function ( func
, wait
) {
277 var context
, args
, timeout
,
281 previous
= OO
.ui
.now();
282 func
.apply( context
, args
);
285 // Check how long it's been since the last time the function was
286 // called, and whether it's more or less than the requested throttle
287 // period. If it's less, run the function immediately. If it's more,
288 // set a timeout for the remaining time -- but don't replace an
289 // existing timeout, since that'd indefinitely prolong the wait.
290 var remaining
= wait
- ( OO
.ui
.now() - previous
);
293 if ( remaining
<= 0 ) {
294 // Note: unless wait was ridiculously large, this means we'll
295 // automatically run the first time the function was called in a
296 // given period. (If you provide a wait period larger than the
297 // current Unix timestamp, you *deserve* unexpected behavior.)
298 clearTimeout( timeout
);
300 } else if ( !timeout
) {
301 timeout
= setTimeout( run
, remaining
);
307 * A (possibly faster) way to get the current timestamp as an integer
309 * @return {number} Current timestamp
311 OO
.ui
.now
= Date
.now
|| function () {
312 return new Date().getTime();
316 * Proxy for `node.addEventListener( eventName, handler, true )`.
318 * @param {HTMLElement} node
319 * @param {string} eventName
320 * @param {Function} handler
321 * @deprecated since 0.15.0
323 OO
.ui
.addCaptureEventListener = function ( node
, eventName
, handler
) {
324 node
.addEventListener( eventName
, handler
, true );
328 * Proxy for `node.removeEventListener( eventName, handler, true )`.
330 * @param {HTMLElement} node
331 * @param {string} eventName
332 * @param {Function} handler
333 * @deprecated since 0.15.0
335 OO
.ui
.removeCaptureEventListener = function ( node
, eventName
, handler
) {
336 node
.removeEventListener( eventName
, handler
, true );
340 * Reconstitute a JavaScript object corresponding to a widget created by
341 * the PHP implementation.
343 * This is an alias for `OO.ui.Element.static.infuse()`.
345 * @param {string|HTMLElement|jQuery} idOrNode
346 * A DOM id (if a string) or node for the widget to infuse.
347 * @return {OO.ui.Element}
348 * The `OO.ui.Element` corresponding to this (infusable) document node.
350 OO
.ui
.infuse = function ( idOrNode
) {
351 return OO
.ui
.Element
.static.infuse( idOrNode
);
356 * Message store for the default implementation of OO.ui.msg
358 * Environments that provide a localization system should not use this, but should override
359 * OO.ui.msg altogether.
364 // Tool tip for a button that moves items in a list down one place
365 'ooui-outline-control-move-down': 'Move item down',
366 // Tool tip for a button that moves items in a list up one place
367 'ooui-outline-control-move-up': 'Move item up',
368 // Tool tip for a button that removes items from a list
369 'ooui-outline-control-remove': 'Remove item',
370 // Label for the toolbar group that contains a list of all other available tools
371 'ooui-toolbar-more': 'More',
372 // Label for the fake tool that expands the full list of tools in a toolbar group
373 'ooui-toolgroup-expand': 'More',
374 // Label for the fake tool that collapses the full list of tools in a toolbar group
375 'ooui-toolgroup-collapse': 'Fewer',
376 // Default label for the accept button of a confirmation dialog
377 'ooui-dialog-message-accept': 'OK',
378 // Default label for the reject button of a confirmation dialog
379 'ooui-dialog-message-reject': 'Cancel',
380 // Title for process dialog error description
381 'ooui-dialog-process-error': 'Something went wrong',
382 // Label for process dialog dismiss error button, visible when describing errors
383 'ooui-dialog-process-dismiss': 'Dismiss',
384 // Label for process dialog retry action button, visible when describing only recoverable errors
385 'ooui-dialog-process-retry': 'Try again',
386 // Label for process dialog retry action button, visible when describing only warnings
387 'ooui-dialog-process-continue': 'Continue',
388 // Label for the file selection widget's select file button
389 'ooui-selectfile-button-select': 'Select a file',
390 // Label for the file selection widget if file selection is not supported
391 'ooui-selectfile-not-supported': 'File selection is not supported',
392 // Label for the file selection widget when no file is currently selected
393 'ooui-selectfile-placeholder': 'No file is selected',
394 // Label for the file selection widget's drop target
395 'ooui-selectfile-dragdrop-placeholder': 'Drop file here'
399 * Get a localized message.
401 * In environments that provide a localization system, this function should be overridden to
402 * return the message translated in the user's language. The default implementation always returns
405 * After the message key, message parameters may optionally be passed. In the default implementation,
406 * any occurrences of $1 are replaced with the first parameter, $2 with the second parameter, etc.
407 * Alternative implementations of OO.ui.msg may use any substitution system they like, as long as
408 * they support unnamed, ordered message parameters.
410 * @param {string} key Message key
411 * @param {...Mixed} [params] Message parameters
412 * @return {string} Translated message with parameters substituted
414 OO
.ui
.msg = function ( key
) {
415 var message
= messages
[ key
],
416 params
= Array
.prototype.slice
.call( arguments
, 1 );
417 if ( typeof message
=== 'string' ) {
418 // Perform $1 substitution
419 message
= message
.replace( /\$(\d+)/g, function ( unused
, n
) {
420 var i
= parseInt( n
, 10 );
421 return params
[ i
- 1 ] !== undefined ? params
[ i
- 1 ] : '$' + n
;
424 // Return placeholder if message not found
425 message
= '[' + key
+ ']';
432 * Package a message and arguments for deferred resolution.
434 * Use this when you are statically specifying a message and the message may not yet be present.
436 * @param {string} key Message key
437 * @param {...Mixed} [params] Message parameters
438 * @return {Function} Function that returns the resolved message when executed
440 OO
.ui
.deferMsg = function () {
441 var args
= arguments
;
443 return OO
.ui
.msg
.apply( OO
.ui
, args
);
450 * If the message is a function it will be executed, otherwise it will pass through directly.
452 * @param {Function|string} msg Deferred message, or message text
453 * @return {string} Resolved message
455 OO
.ui
.resolveMsg = function ( msg
) {
456 if ( $.isFunction( msg
) ) {
463 * @param {string} url
466 OO
.ui
.isSafeUrl = function ( url
) {
467 // Keep this function in sync with php/Tag.php
468 var i
, protocolWhitelist
;
470 function stringStartsWith( haystack
, needle
) {
471 return haystack
.substr( 0, needle
.length
) === needle
;
474 protocolWhitelist
= [
475 'bitcoin', 'ftp', 'ftps', 'geo', 'git', 'gopher', 'http', 'https', 'irc', 'ircs',
476 'magnet', 'mailto', 'mms', 'news', 'nntp', 'redis', 'sftp', 'sip', 'sips', 'sms', 'ssh',
477 'svn', 'tel', 'telnet', 'urn', 'worldwind', 'xmpp'
484 for ( i
= 0; i
< protocolWhitelist
.length
; i
++ ) {
485 if ( stringStartsWith( url
, protocolWhitelist
[ i
] + ':' ) ) {
490 // This matches '//' too
491 if ( stringStartsWith( url
, '/' ) || stringStartsWith( url
, './' ) ) {
494 if ( stringStartsWith( url
, '?' ) || stringStartsWith( url
, '#' ) ) {
506 * Namespace for OOjs UI mixins.
508 * Mixins are named according to the type of object they are intended to
509 * be mixed in to. For example, OO.ui.mixin.GroupElement is intended to be
510 * mixed in to an instance of OO.ui.Element, and OO.ui.mixin.GroupWidget
511 * is intended to be mixed in to an instance of OO.ui.Widget.
519 * Each Element represents a rendering in the DOM—a button or an icon, for example, or anything
520 * that is visible to a user. Unlike {@link OO.ui.Widget widgets}, plain elements usually do not have events
521 * connected to them and can't be interacted with.
527 * @param {Object} [config] Configuration options
528 * @cfg {string[]} [classes] The names of the CSS classes to apply to the element. CSS styles are added
529 * to the top level (e.g., the outermost div) of the element. See the [OOjs UI documentation on MediaWiki][2]
531 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#cssExample
532 * @cfg {string} [id] The HTML id attribute used in the rendered tag.
533 * @cfg {string} [text] Text to insert
534 * @cfg {Array} [content] An array of content elements to append (after #text).
535 * Strings will be html-escaped; use an OO.ui.HtmlSnippet to append raw HTML.
536 * Instances of OO.ui.Element will have their $element appended.
537 * @cfg {jQuery} [$content] Content elements to append (after #text).
538 * @cfg {jQuery} [$element] Wrapper element. Defaults to a new element with #getTagName.
539 * @cfg {Mixed} [data] Custom data of any type or combination of types (e.g., string, number, array, object).
540 * Data can also be specified with the #setData method.
542 OO
.ui
.Element
= function OoUiElement( config
) {
543 // Configuration initialization
544 config
= config
|| {};
549 this.data
= config
.data
;
550 this.$element
= config
.$element
||
551 $( document
.createElement( this.getTagName() ) );
552 this.elementGroup
= null;
553 this.debouncedUpdateThemeClassesHandler
= OO
.ui
.debounce( this.debouncedUpdateThemeClasses
);
556 if ( Array
.isArray( config
.classes
) ) {
557 this.$element
.addClass( config
.classes
.join( ' ' ) );
560 this.$element
.attr( 'id', config
.id
);
563 this.$element
.text( config
.text
);
565 if ( config
.content
) {
566 // The `content` property treats plain strings as text; use an
567 // HtmlSnippet to append HTML content. `OO.ui.Element`s get their
568 // appropriate $element appended.
569 this.$element
.append( config
.content
.map( function ( v
) {
570 if ( typeof v
=== 'string' ) {
571 // Escape string so it is properly represented in HTML.
572 return document
.createTextNode( v
);
573 } else if ( v
instanceof OO
.ui
.HtmlSnippet
) {
576 } else if ( v
instanceof OO
.ui
.Element
) {
582 if ( config
.$content
) {
583 // The `$content` property treats plain strings as HTML.
584 this.$element
.append( config
.$content
);
590 OO
.initClass( OO
.ui
.Element
);
592 /* Static Properties */
595 * The name of the HTML tag used by the element.
597 * The static value may be ignored if the #getTagName method is overridden.
603 OO
.ui
.Element
.static.tagName
= 'div';
608 * Reconstitute a JavaScript object corresponding to a widget created
609 * by the PHP implementation.
611 * @param {string|HTMLElement|jQuery} idOrNode
612 * A DOM id (if a string) or node for the widget to infuse.
613 * @return {OO.ui.Element}
614 * The `OO.ui.Element` corresponding to this (infusable) document node.
615 * For `Tag` objects emitted on the HTML side (used occasionally for content)
616 * the value returned is a newly-created Element wrapping around the existing
619 OO
.ui
.Element
.static.infuse = function ( idOrNode
) {
620 var obj
= OO
.ui
.Element
.static.unsafeInfuse( idOrNode
, false );
621 // Verify that the type matches up.
622 // FIXME: uncomment after T89721 is fixed (see T90929)
624 if ( !( obj instanceof this['class'] ) ) {
625 throw new Error( 'Infusion type mismatch!' );
632 * Implementation helper for `infuse`; skips the type check and has an
633 * extra property so that only the top-level invocation touches the DOM.
636 * @param {string|HTMLElement|jQuery} idOrNode
637 * @param {jQuery.Promise|boolean} domPromise A promise that will be resolved
638 * when the top-level widget of this infusion is inserted into DOM,
639 * replacing the original node; or false for top-level invocation.
640 * @return {OO.ui.Element}
642 OO
.ui
.Element
.static.unsafeInfuse = function ( idOrNode
, domPromise
) {
643 // look for a cached result of a previous infusion.
644 var id
, $elem
, data
, cls
, parts
, parent
, obj
, top
, state
, infusedChildren
;
645 if ( typeof idOrNode
=== 'string' ) {
647 $elem
= $( document
.getElementById( id
) );
649 $elem
= $( idOrNode
);
650 id
= $elem
.attr( 'id' );
652 if ( !$elem
.length
) {
653 throw new Error( 'Widget not found: ' + id
);
655 if ( $elem
[ 0 ].oouiInfused
) {
656 $elem
= $elem
[ 0 ].oouiInfused
;
658 data
= $elem
.data( 'ooui-infused' );
661 if ( data
=== true ) {
662 throw new Error( 'Circular dependency! ' + id
);
665 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
666 state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
667 // restore dynamic state after the new element is re-inserted into DOM under infused parent
668 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
669 infusedChildren
= $elem
.data( 'ooui-infused-children' );
670 if ( infusedChildren
&& infusedChildren
.length
) {
671 infusedChildren
.forEach( function ( data
) {
672 var state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
673 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
679 data
= $elem
.attr( 'data-ooui' );
681 throw new Error( 'No infusion data found: ' + id
);
684 data
= $.parseJSON( data
);
688 if ( !( data
&& data
._
) ) {
689 throw new Error( 'No valid infusion data found: ' + id
);
691 if ( data
._
=== 'Tag' ) {
692 // Special case: this is a raw Tag; wrap existing node, don't rebuild.
693 return new OO
.ui
.Element( { $element
: $elem
} );
695 parts
= data
._
.split( '.' );
696 cls
= OO
.getProp
.apply( OO
, [ window
].concat( parts
) );
697 if ( cls
=== undefined ) {
698 // The PHP output might be old and not including the "OO.ui" prefix
699 // TODO: Remove this back-compat after next major release
700 cls
= OO
.getProp
.apply( OO
, [ OO
.ui
].concat( parts
) );
701 if ( cls
=== undefined ) {
702 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
706 // Verify that we're creating an OO.ui.Element instance
709 while ( parent
!== undefined ) {
710 if ( parent
=== OO
.ui
.Element
) {
715 parent
= parent
.parent
;
718 if ( parent
!== OO
.ui
.Element
) {
719 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
722 if ( domPromise
=== false ) {
724 domPromise
= top
.promise();
726 $elem
.data( 'ooui-infused', true ); // prevent loops
727 data
.id
= id
; // implicit
728 infusedChildren
= [];
729 data
= OO
.copy( data
, null, function deserialize( value
) {
731 if ( OO
.isPlainObject( value
) ) {
733 infused
= OO
.ui
.Element
.static.unsafeInfuse( value
.tag
, domPromise
);
734 infusedChildren
.push( infused
);
735 // Flatten the structure
736 infusedChildren
.push
.apply( infusedChildren
, infused
.$element
.data( 'ooui-infused-children' ) || [] );
737 infused
.$element
.removeData( 'ooui-infused-children' );
740 if ( value
.html
!== undefined ) {
741 return new OO
.ui
.HtmlSnippet( value
.html
);
745 // allow widgets to reuse parts of the DOM
746 data
= cls
.static.reusePreInfuseDOM( $elem
[ 0 ], data
);
747 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
748 state
= cls
.static.gatherPreInfuseState( $elem
[ 0 ], data
);
750 // jscs:disable requireCapitalizedConstructors
751 obj
= new cls( data
);
752 // jscs:enable requireCapitalizedConstructors
753 // now replace old DOM with this new DOM.
755 // An efficient constructor might be able to reuse the entire DOM tree of the original element,
756 // so only mutate the DOM if we need to.
757 if ( $elem
[ 0 ] !== obj
.$element
[ 0 ] ) {
758 $elem
.replaceWith( obj
.$element
);
759 // This element is now gone from the DOM, but if anyone is holding a reference to it,
760 // let's allow them to OO.ui.infuse() it and do what they expect (T105828).
761 // Do not use jQuery.data(), as using it on detached nodes leaks memory in 1.x line by design.
762 $elem
[ 0 ].oouiInfused
= obj
.$element
;
766 obj
.$element
.data( 'ooui-infused', obj
);
767 obj
.$element
.data( 'ooui-infused-children', infusedChildren
);
768 // set the 'data-ooui' attribute so we can identify infused widgets
769 obj
.$element
.attr( 'data-ooui', '' );
770 // restore dynamic state after the new element is inserted into DOM
771 domPromise
.done( obj
.restorePreInfuseState
.bind( obj
, state
) );
776 * Pick out parts of `node`'s DOM to be reused when infusing a widget.
778 * This method **must not** make any changes to the DOM, only find interesting pieces and add them
779 * to `config` (which should then be returned). Actual DOM juggling should then be done by the
780 * constructor, which will be given the enhanced config.
783 * @param {HTMLElement} node
784 * @param {Object} config
787 OO
.ui
.Element
.static.reusePreInfuseDOM = function ( node
, config
) {
792 * Gather the dynamic state (focus, value of form inputs, scroll position, etc.) of a HTML DOM node
793 * (and its children) that represent an Element of the same class and the given configuration,
794 * generated by the PHP implementation.
796 * This method is called just before `node` is detached from the DOM. The return value of this
797 * function will be passed to #restorePreInfuseState after the newly created widget's #$element
798 * is inserted into DOM to replace `node`.
801 * @param {HTMLElement} node
802 * @param {Object} config
805 OO
.ui
.Element
.static.gatherPreInfuseState = function () {
810 * Get a jQuery function within a specific document.
813 * @param {jQuery|HTMLElement|HTMLDocument|Window} context Context to bind the function to
814 * @param {jQuery} [$iframe] HTML iframe element that contains the document, omit if document is
816 * @return {Function} Bound jQuery function
818 OO
.ui
.Element
.static.getJQuery = function ( context
, $iframe
) {
819 function wrapper( selector
) {
820 return $( selector
, wrapper
.context
);
823 wrapper
.context
= this.getDocument( context
);
826 wrapper
.$iframe
= $iframe
;
833 * Get the document of an element.
836 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Object to get the document for
837 * @return {HTMLDocument|null} Document object
839 OO
.ui
.Element
.static.getDocument = function ( obj
) {
840 // jQuery - selections created "offscreen" won't have a context, so .context isn't reliable
841 return ( obj
[ 0 ] && obj
[ 0 ].ownerDocument
) ||
842 // Empty jQuery selections might have a context
849 ( obj
.nodeType
=== 9 && obj
) ||
854 * Get the window of an element or document.
857 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the window for
858 * @return {Window} Window object
860 OO
.ui
.Element
.static.getWindow = function ( obj
) {
861 var doc
= this.getDocument( obj
);
862 return doc
.defaultView
;
866 * Get the direction of an element or document.
869 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the direction for
870 * @return {string} Text direction, either 'ltr' or 'rtl'
872 OO
.ui
.Element
.static.getDir = function ( obj
) {
875 if ( obj
instanceof jQuery
) {
878 isDoc
= obj
.nodeType
=== 9;
879 isWin
= obj
.document
!== undefined;
880 if ( isDoc
|| isWin
) {
886 return $( obj
).css( 'direction' );
890 * Get the offset between two frames.
892 * TODO: Make this function not use recursion.
895 * @param {Window} from Window of the child frame
896 * @param {Window} [to=window] Window of the parent frame
897 * @param {Object} [offset] Offset to start with, used internally
898 * @return {Object} Offset object, containing left and top properties
900 OO
.ui
.Element
.static.getFrameOffset = function ( from, to
, offset
) {
901 var i
, len
, frames
, frame
, rect
;
907 offset
= { top
: 0, left
: 0 };
909 if ( from.parent
=== from ) {
913 // Get iframe element
914 frames
= from.parent
.document
.getElementsByTagName( 'iframe' );
915 for ( i
= 0, len
= frames
.length
; i
< len
; i
++ ) {
916 if ( frames
[ i
].contentWindow
=== from ) {
922 // Recursively accumulate offset values
924 rect
= frame
.getBoundingClientRect();
925 offset
.left
+= rect
.left
;
926 offset
.top
+= rect
.top
;
928 this.getFrameOffset( from.parent
, offset
);
935 * Get the offset between two elements.
937 * The two elements may be in a different frame, but in that case the frame $element is in must
938 * be contained in the frame $anchor is in.
941 * @param {jQuery} $element Element whose position to get
942 * @param {jQuery} $anchor Element to get $element's position relative to
943 * @return {Object} Translated position coordinates, containing top and left properties
945 OO
.ui
.Element
.static.getRelativePosition = function ( $element
, $anchor
) {
946 var iframe
, iframePos
,
947 pos
= $element
.offset(),
948 anchorPos
= $anchor
.offset(),
949 elementDocument
= this.getDocument( $element
),
950 anchorDocument
= this.getDocument( $anchor
);
952 // If $element isn't in the same document as $anchor, traverse up
953 while ( elementDocument
!== anchorDocument
) {
954 iframe
= elementDocument
.defaultView
.frameElement
;
956 throw new Error( '$element frame is not contained in $anchor frame' );
958 iframePos
= $( iframe
).offset();
959 pos
.left
+= iframePos
.left
;
960 pos
.top
+= iframePos
.top
;
961 elementDocument
= iframe
.ownerDocument
;
963 pos
.left
-= anchorPos
.left
;
964 pos
.top
-= anchorPos
.top
;
969 * Get element border sizes.
972 * @param {HTMLElement} el Element to measure
973 * @return {Object} Dimensions object with `top`, `left`, `bottom` and `right` properties
975 OO
.ui
.Element
.static.getBorders = function ( el
) {
976 var doc
= el
.ownerDocument
,
977 win
= doc
.defaultView
,
978 style
= win
.getComputedStyle( el
, null ),
980 top
= parseFloat( style
? style
.borderTopWidth
: $el
.css( 'borderTopWidth' ) ) || 0,
981 left
= parseFloat( style
? style
.borderLeftWidth
: $el
.css( 'borderLeftWidth' ) ) || 0,
982 bottom
= parseFloat( style
? style
.borderBottomWidth
: $el
.css( 'borderBottomWidth' ) ) || 0,
983 right
= parseFloat( style
? style
.borderRightWidth
: $el
.css( 'borderRightWidth' ) ) || 0;
994 * Get dimensions of an element or window.
997 * @param {HTMLElement|Window} el Element to measure
998 * @return {Object} Dimensions object with `borders`, `scroll`, `scrollbar` and `rect` properties
1000 OO
.ui
.Element
.static.getDimensions = function ( el
) {
1002 doc
= el
.ownerDocument
|| el
.document
,
1003 win
= doc
.defaultView
;
1005 if ( win
=== el
|| el
=== doc
.documentElement
) {
1008 borders
: { top
: 0, left
: 0, bottom
: 0, right
: 0 },
1010 top
: $win
.scrollTop(),
1011 left
: $win
.scrollLeft()
1013 scrollbar
: { right
: 0, bottom
: 0 },
1017 bottom
: $win
.innerHeight(),
1018 right
: $win
.innerWidth()
1024 borders
: this.getBorders( el
),
1026 top
: $el
.scrollTop(),
1027 left
: $el
.scrollLeft()
1030 right
: $el
.innerWidth() - el
.clientWidth
,
1031 bottom
: $el
.innerHeight() - el
.clientHeight
1033 rect
: el
.getBoundingClientRect()
1039 * Get scrollable object parent
1041 * documentElement can't be used to get or set the scrollTop
1042 * property on Blink. Changing and testing its value lets us
1043 * use 'body' or 'documentElement' based on what is working.
1045 * https://code.google.com/p/chromium/issues/detail?id=303131
1048 * @param {HTMLElement} el Element to find scrollable parent for
1049 * @return {HTMLElement} Scrollable parent
1051 OO
.ui
.Element
.static.getRootScrollableElement = function ( el
) {
1052 var scrollTop
, body
;
1054 if ( OO
.ui
.scrollableElement
=== undefined ) {
1055 body
= el
.ownerDocument
.body
;
1056 scrollTop
= body
.scrollTop
;
1059 if ( body
.scrollTop
=== 1 ) {
1060 body
.scrollTop
= scrollTop
;
1061 OO
.ui
.scrollableElement
= 'body';
1063 OO
.ui
.scrollableElement
= 'documentElement';
1067 return el
.ownerDocument
[ OO
.ui
.scrollableElement
];
1071 * Get closest scrollable container.
1073 * Traverses up until either a scrollable element or the root is reached, in which case the window
1077 * @param {HTMLElement} el Element to find scrollable container for
1078 * @param {string} [dimension] Dimension of scrolling to look for; `x`, `y` or omit for either
1079 * @return {HTMLElement} Closest scrollable container
1081 OO
.ui
.Element
.static.getClosestScrollableContainer = function ( el
, dimension
) {
1083 // props = [ 'overflow' ] doesn't work due to https://bugzilla.mozilla.org/show_bug.cgi?id=889091
1084 props
= [ 'overflow-x', 'overflow-y' ],
1085 $parent
= $( el
).parent();
1087 if ( dimension
=== 'x' || dimension
=== 'y' ) {
1088 props
= [ 'overflow-' + dimension
];
1091 while ( $parent
.length
) {
1092 if ( $parent
[ 0 ] === this.getRootScrollableElement( el
) ) {
1093 return $parent
[ 0 ];
1097 val
= $parent
.css( props
[ i
] );
1098 if ( val
=== 'auto' || val
=== 'scroll' ) {
1099 return $parent
[ 0 ];
1102 $parent
= $parent
.parent();
1104 return this.getDocument( el
).body
;
1108 * Scroll element into view.
1111 * @param {HTMLElement} el Element to scroll into view
1112 * @param {Object} [config] Configuration options
1113 * @param {string} [config.duration='fast'] jQuery animation duration value
1114 * @param {string} [config.direction] Scroll in only one direction, e.g. 'x' or 'y', omit
1115 * to scroll in both directions
1116 * @param {Function} [config.complete] Function to call when scrolling completes.
1117 * Deprecated since 0.15.4, use the return promise instead.
1118 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1120 OO
.ui
.Element
.static.scrollIntoView = function ( el
, config
) {
1121 var position
, animations
, callback
, container
, $container
, elementDimensions
, containerDimensions
, $window
,
1122 deferred
= $.Deferred();
1124 // Configuration initialization
1125 config
= config
|| {};
1128 callback
= typeof config
.complete
=== 'function' && config
.complete
;
1129 container
= this.getClosestScrollableContainer( el
, config
.direction
);
1130 $container
= $( container
);
1131 elementDimensions
= this.getDimensions( el
);
1132 containerDimensions
= this.getDimensions( container
);
1133 $window
= $( this.getWindow( el
) );
1135 // Compute the element's position relative to the container
1136 if ( $container
.is( 'html, body' ) ) {
1137 // If the scrollable container is the root, this is easy
1139 top
: elementDimensions
.rect
.top
,
1140 bottom
: $window
.innerHeight() - elementDimensions
.rect
.bottom
,
1141 left
: elementDimensions
.rect
.left
,
1142 right
: $window
.innerWidth() - elementDimensions
.rect
.right
1145 // Otherwise, we have to subtract el's coordinates from container's coordinates
1147 top
: elementDimensions
.rect
.top
- ( containerDimensions
.rect
.top
+ containerDimensions
.borders
.top
),
1148 bottom
: containerDimensions
.rect
.bottom
- containerDimensions
.borders
.bottom
- containerDimensions
.scrollbar
.bottom
- elementDimensions
.rect
.bottom
,
1149 left
: elementDimensions
.rect
.left
- ( containerDimensions
.rect
.left
+ containerDimensions
.borders
.left
),
1150 right
: containerDimensions
.rect
.right
- containerDimensions
.borders
.right
- containerDimensions
.scrollbar
.right
- elementDimensions
.rect
.right
1154 if ( !config
.direction
|| config
.direction
=== 'y' ) {
1155 if ( position
.top
< 0 ) {
1156 animations
.scrollTop
= containerDimensions
.scroll
.top
+ position
.top
;
1157 } else if ( position
.top
> 0 && position
.bottom
< 0 ) {
1158 animations
.scrollTop
= containerDimensions
.scroll
.top
+ Math
.min( position
.top
, -position
.bottom
);
1161 if ( !config
.direction
|| config
.direction
=== 'x' ) {
1162 if ( position
.left
< 0 ) {
1163 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ position
.left
;
1164 } else if ( position
.left
> 0 && position
.right
< 0 ) {
1165 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ Math
.min( position
.left
, -position
.right
);
1168 if ( !$.isEmptyObject( animations
) ) {
1169 $container
.stop( true ).animate( animations
, config
.duration
=== undefined ? 'fast' : config
.duration
);
1170 $container
.queue( function ( next
) {
1183 return deferred
.promise();
1187 * Force the browser to reconsider whether it really needs to render scrollbars inside the element
1188 * and reserve space for them, because it probably doesn't.
1190 * Workaround primarily for <https://code.google.com/p/chromium/issues/detail?id=387290>, but also
1191 * similar bugs in other browsers. "Just" forcing a reflow is not sufficient in all cases, we need
1192 * to first actually detach (or hide, but detaching is simpler) all children, *then* force a reflow,
1193 * and then reattach (or show) them back.
1196 * @param {HTMLElement} el Element to reconsider the scrollbars on
1198 OO
.ui
.Element
.static.reconsiderScrollbars = function ( el
) {
1199 var i
, len
, scrollLeft
, scrollTop
, nodes
= [];
1200 // Save scroll position
1201 scrollLeft
= el
.scrollLeft
;
1202 scrollTop
= el
.scrollTop
;
1203 // Detach all children
1204 while ( el
.firstChild
) {
1205 nodes
.push( el
.firstChild
);
1206 el
.removeChild( el
.firstChild
);
1209 void el
.offsetHeight
;
1210 // Reattach all children
1211 for ( i
= 0, len
= nodes
.length
; i
< len
; i
++ ) {
1212 el
.appendChild( nodes
[ i
] );
1214 // Restore scroll position (no-op if scrollbars disappeared)
1215 el
.scrollLeft
= scrollLeft
;
1216 el
.scrollTop
= scrollTop
;
1222 * Toggle visibility of an element.
1224 * @param {boolean} [show] Make element visible, omit to toggle visibility
1228 OO
.ui
.Element
.prototype.toggle = function ( show
) {
1229 show
= show
=== undefined ? !this.visible
: !!show
;
1231 if ( show
!== this.isVisible() ) {
1232 this.visible
= show
;
1233 this.$element
.toggleClass( 'oo-ui-element-hidden', !this.visible
);
1234 this.emit( 'toggle', show
);
1241 * Check if element is visible.
1243 * @return {boolean} element is visible
1245 OO
.ui
.Element
.prototype.isVisible = function () {
1246 return this.visible
;
1252 * @return {Mixed} Element data
1254 OO
.ui
.Element
.prototype.getData = function () {
1261 * @param {Mixed} data Element data
1264 OO
.ui
.Element
.prototype.setData = function ( data
) {
1270 * Check if element supports one or more methods.
1272 * @param {string|string[]} methods Method or list of methods to check
1273 * @return {boolean} All methods are supported
1275 OO
.ui
.Element
.prototype.supports = function ( methods
) {
1279 methods
= Array
.isArray( methods
) ? methods
: [ methods
];
1280 for ( i
= 0, len
= methods
.length
; i
< len
; i
++ ) {
1281 if ( $.isFunction( this[ methods
[ i
] ] ) ) {
1286 return methods
.length
=== support
;
1290 * Update the theme-provided classes.
1292 * @localdoc This is called in element mixins and widget classes any time state changes.
1293 * Updating is debounced, minimizing overhead of changing multiple attributes and
1294 * guaranteeing that theme updates do not occur within an element's constructor
1296 OO
.ui
.Element
.prototype.updateThemeClasses = function () {
1297 this.debouncedUpdateThemeClassesHandler();
1302 * @localdoc This method is called directly from the QUnit tests instead of #updateThemeClasses, to
1303 * make them synchronous.
1305 OO
.ui
.Element
.prototype.debouncedUpdateThemeClasses = function () {
1306 OO
.ui
.theme
.updateElementClasses( this );
1310 * Get the HTML tag name.
1312 * Override this method to base the result on instance information.
1314 * @return {string} HTML tag name
1316 OO
.ui
.Element
.prototype.getTagName = function () {
1317 return this.constructor.static.tagName
;
1321 * Check if the element is attached to the DOM
1323 * @return {boolean} The element is attached to the DOM
1325 OO
.ui
.Element
.prototype.isElementAttached = function () {
1326 return $.contains( this.getElementDocument(), this.$element
[ 0 ] );
1330 * Get the DOM document.
1332 * @return {HTMLDocument} Document object
1334 OO
.ui
.Element
.prototype.getElementDocument = function () {
1335 // Don't cache this in other ways either because subclasses could can change this.$element
1336 return OO
.ui
.Element
.static.getDocument( this.$element
);
1340 * Get the DOM window.
1342 * @return {Window} Window object
1344 OO
.ui
.Element
.prototype.getElementWindow = function () {
1345 return OO
.ui
.Element
.static.getWindow( this.$element
);
1349 * Get closest scrollable container.
1351 * @return {HTMLElement} Closest scrollable container
1353 OO
.ui
.Element
.prototype.getClosestScrollableElementContainer = function () {
1354 return OO
.ui
.Element
.static.getClosestScrollableContainer( this.$element
[ 0 ] );
1358 * Get group element is in.
1360 * @return {OO.ui.mixin.GroupElement|null} Group element, null if none
1362 OO
.ui
.Element
.prototype.getElementGroup = function () {
1363 return this.elementGroup
;
1367 * Set group element is in.
1369 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
1372 OO
.ui
.Element
.prototype.setElementGroup = function ( group
) {
1373 this.elementGroup
= group
;
1378 * Scroll element into view.
1380 * @param {Object} [config] Configuration options
1381 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1383 OO
.ui
.Element
.prototype.scrollElementIntoView = function ( config
) {
1384 return OO
.ui
.Element
.static.scrollIntoView( this.$element
[ 0 ], config
);
1388 * Restore the pre-infusion dynamic state for this widget.
1390 * This method is called after #$element has been inserted into DOM. The parameter is the return
1391 * value of #gatherPreInfuseState.
1394 * @param {Object} state
1396 OO
.ui
.Element
.prototype.restorePreInfuseState = function () {
1400 * Wraps an HTML snippet for use with configuration values which default
1401 * to strings. This bypasses the default html-escaping done to string
1407 * @param {string} [content] HTML content
1409 OO
.ui
.HtmlSnippet
= function OoUiHtmlSnippet( content
) {
1411 this.content
= content
;
1416 OO
.initClass( OO
.ui
.HtmlSnippet
);
1423 * @return {string} Unchanged HTML snippet.
1425 OO
.ui
.HtmlSnippet
.prototype.toString = function () {
1426 return this.content
;
1430 * Layouts are containers for elements and are used to arrange other widgets of arbitrary type in a way
1431 * that is centrally controlled and can be updated dynamically. Layouts can be, and usually are, combined.
1432 * See {@link OO.ui.FieldsetLayout FieldsetLayout}, {@link OO.ui.FieldLayout FieldLayout}, {@link OO.ui.FormLayout FormLayout},
1433 * {@link OO.ui.PanelLayout PanelLayout}, {@link OO.ui.StackLayout StackLayout}, {@link OO.ui.PageLayout PageLayout},
1434 * {@link OO.ui.HorizontalLayout HorizontalLayout}, and {@link OO.ui.BookletLayout BookletLayout} for more information and examples.
1438 * @extends OO.ui.Element
1439 * @mixins OO.EventEmitter
1442 * @param {Object} [config] Configuration options
1444 OO
.ui
.Layout
= function OoUiLayout( config
) {
1445 // Configuration initialization
1446 config
= config
|| {};
1448 // Parent constructor
1449 OO
.ui
.Layout
.parent
.call( this, config
);
1451 // Mixin constructors
1452 OO
.EventEmitter
.call( this );
1455 this.$element
.addClass( 'oo-ui-layout' );
1460 OO
.inheritClass( OO
.ui
.Layout
, OO
.ui
.Element
);
1461 OO
.mixinClass( OO
.ui
.Layout
, OO
.EventEmitter
);
1464 * Widgets are compositions of one or more OOjs UI elements that users can both view
1465 * and interact with. All widgets can be configured and modified via a standard API,
1466 * and their state can change dynamically according to a model.
1470 * @extends OO.ui.Element
1471 * @mixins OO.EventEmitter
1474 * @param {Object} [config] Configuration options
1475 * @cfg {boolean} [disabled=false] Disable the widget. Disabled widgets cannot be used and their
1476 * appearance reflects this state.
1478 OO
.ui
.Widget
= function OoUiWidget( config
) {
1479 // Initialize config
1480 config
= $.extend( { disabled
: false }, config
);
1482 // Parent constructor
1483 OO
.ui
.Widget
.parent
.call( this, config
);
1485 // Mixin constructors
1486 OO
.EventEmitter
.call( this );
1489 this.disabled
= null;
1490 this.wasDisabled
= null;
1493 this.$element
.addClass( 'oo-ui-widget' );
1494 this.setDisabled( !!config
.disabled
);
1499 OO
.inheritClass( OO
.ui
.Widget
, OO
.ui
.Element
);
1500 OO
.mixinClass( OO
.ui
.Widget
, OO
.EventEmitter
);
1502 /* Static Properties */
1505 * Whether this widget will behave reasonably when wrapped in a HTML `<label>`. If this is true,
1506 * wrappers such as OO.ui.FieldLayout may use a `<label>` instead of implementing own label click
1511 * @property {boolean}
1513 OO
.ui
.Widget
.static.supportsSimpleLabel
= false;
1520 * A 'disable' event is emitted when the disabled state of the widget changes
1521 * (i.e. on disable **and** enable).
1523 * @param {boolean} disabled Widget is disabled
1529 * A 'toggle' event is emitted when the visibility of the widget changes.
1531 * @param {boolean} visible Widget is visible
1537 * Check if the widget is disabled.
1539 * @return {boolean} Widget is disabled
1541 OO
.ui
.Widget
.prototype.isDisabled = function () {
1542 return this.disabled
;
1546 * Set the 'disabled' state of the widget.
1548 * When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.
1550 * @param {boolean} disabled Disable widget
1553 OO
.ui
.Widget
.prototype.setDisabled = function ( disabled
) {
1556 this.disabled
= !!disabled
;
1557 isDisabled
= this.isDisabled();
1558 if ( isDisabled
!== this.wasDisabled
) {
1559 this.$element
.toggleClass( 'oo-ui-widget-disabled', isDisabled
);
1560 this.$element
.toggleClass( 'oo-ui-widget-enabled', !isDisabled
);
1561 this.$element
.attr( 'aria-disabled', isDisabled
.toString() );
1562 this.emit( 'disable', isDisabled
);
1563 this.updateThemeClasses();
1565 this.wasDisabled
= isDisabled
;
1571 * Update the disabled state, in case of changes in parent widget.
1575 OO
.ui
.Widget
.prototype.updateDisabled = function () {
1576 this.setDisabled( this.disabled
);
1587 * @param {Object} [config] Configuration options
1589 OO
.ui
.Theme
= function OoUiTheme( config
) {
1590 // Configuration initialization
1591 config
= config
|| {};
1596 OO
.initClass( OO
.ui
.Theme
);
1601 * Get a list of classes to be applied to a widget.
1603 * The 'on' and 'off' lists combined MUST contain keys for all classes the theme adds or removes,
1604 * otherwise state transitions will not work properly.
1606 * @param {OO.ui.Element} element Element for which to get classes
1607 * @return {Object.<string,string[]>} Categorized class names with `on` and `off` lists
1609 OO
.ui
.Theme
.prototype.getElementClasses = function () {
1610 return { on
: [], off
: [] };
1614 * Update CSS classes provided by the theme.
1616 * For elements with theme logic hooks, this should be called any time there's a state change.
1618 * @param {OO.ui.Element} element Element for which to update classes
1619 * @return {Object.<string,string[]>} Categorized class names with `on` and `off` lists
1621 OO
.ui
.Theme
.prototype.updateElementClasses = function ( element
) {
1622 var $elements
= $( [] ),
1623 classes
= this.getElementClasses( element
);
1625 if ( element
.$icon
) {
1626 $elements
= $elements
.add( element
.$icon
);
1628 if ( element
.$indicator
) {
1629 $elements
= $elements
.add( element
.$indicator
);
1633 .removeClass( classes
.off
.join( ' ' ) )
1634 .addClass( classes
.on
.join( ' ' ) );
1638 * The TabIndexedElement class is an attribute mixin used to add additional functionality to an
1639 * element created by another class. The mixin provides a ‘tabIndex’ property, which specifies the
1640 * order in which users will navigate through the focusable elements via the "tab" key.
1643 * // TabIndexedElement is mixed into the ButtonWidget class
1644 * // to provide a tabIndex property.
1645 * var button1 = new OO.ui.ButtonWidget( {
1649 * var button2 = new OO.ui.ButtonWidget( {
1653 * var button3 = new OO.ui.ButtonWidget( {
1657 * var button4 = new OO.ui.ButtonWidget( {
1661 * $( 'body' ).append( button1.$element, button2.$element, button3.$element, button4.$element );
1667 * @param {Object} [config] Configuration options
1668 * @cfg {jQuery} [$tabIndexed] The element that should use the tabindex functionality. By default,
1669 * the functionality is applied to the element created by the class ($element). If a different element is specified, the tabindex
1670 * functionality will be applied to it instead.
1671 * @cfg {number|null} [tabIndex=0] Number that specifies the element’s position in the tab-navigation
1672 * order (e.g., 1 for the first focusable element). Use 0 to use the default navigation order; use -1
1673 * to remove the element from the tab-navigation flow.
1675 OO
.ui
.mixin
.TabIndexedElement
= function OoUiMixinTabIndexedElement( config
) {
1676 // Configuration initialization
1677 config
= $.extend( { tabIndex
: 0 }, config
);
1680 this.$tabIndexed
= null;
1681 this.tabIndex
= null;
1684 this.connect( this, { disable
: 'onTabIndexedElementDisable' } );
1687 this.setTabIndex( config
.tabIndex
);
1688 this.setTabIndexedElement( config
.$tabIndexed
|| this.$element
);
1693 OO
.initClass( OO
.ui
.mixin
.TabIndexedElement
);
1698 * Set the element that should use the tabindex functionality.
1700 * This method is used to retarget a tabindex mixin so that its functionality applies
1701 * to the specified element. If an element is currently using the functionality, the mixin’s
1702 * effect on that element is removed before the new element is set up.
1704 * @param {jQuery} $tabIndexed Element that should use the tabindex functionality
1707 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndexedElement = function ( $tabIndexed
) {
1708 var tabIndex
= this.tabIndex
;
1709 // Remove attributes from old $tabIndexed
1710 this.setTabIndex( null );
1711 // Force update of new $tabIndexed
1712 this.$tabIndexed
= $tabIndexed
;
1713 this.tabIndex
= tabIndex
;
1714 return this.updateTabIndex();
1718 * Set the value of the tabindex.
1720 * @param {number|null} tabIndex Tabindex value, or `null` for no tabindex
1723 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndex = function ( tabIndex
) {
1724 tabIndex
= typeof tabIndex
=== 'number' ? tabIndex
: null;
1726 if ( this.tabIndex
!== tabIndex
) {
1727 this.tabIndex
= tabIndex
;
1728 this.updateTabIndex();
1735 * Update the `tabindex` attribute, in case of changes to tab index or
1741 OO
.ui
.mixin
.TabIndexedElement
.prototype.updateTabIndex = function () {
1742 if ( this.$tabIndexed
) {
1743 if ( this.tabIndex
!== null ) {
1744 // Do not index over disabled elements
1745 this.$tabIndexed
.attr( {
1746 tabindex
: this.isDisabled() ? -1 : this.tabIndex
,
1747 // Support: ChromeVox and NVDA
1748 // These do not seem to inherit aria-disabled from parent elements
1749 'aria-disabled': this.isDisabled().toString()
1752 this.$tabIndexed
.removeAttr( 'tabindex aria-disabled' );
1759 * Handle disable events.
1762 * @param {boolean} disabled Element is disabled
1764 OO
.ui
.mixin
.TabIndexedElement
.prototype.onTabIndexedElementDisable = function () {
1765 this.updateTabIndex();
1769 * Get the value of the tabindex.
1771 * @return {number|null} Tabindex value
1773 OO
.ui
.mixin
.TabIndexedElement
.prototype.getTabIndex = function () {
1774 return this.tabIndex
;
1778 * ButtonElement is often mixed into other classes to generate a button, which is a clickable
1779 * interface element that can be configured with access keys for accessibility.
1780 * See the [OOjs UI documentation on MediaWiki] [1] for examples.
1782 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#Buttons
1788 * @param {Object} [config] Configuration options
1789 * @cfg {jQuery} [$button] The button element created by the class.
1790 * If this configuration is omitted, the button element will use a generated `<a>`.
1791 * @cfg {boolean} [framed=true] Render the button with a frame
1793 OO
.ui
.mixin
.ButtonElement
= function OoUiMixinButtonElement( config
) {
1794 // Configuration initialization
1795 config
= config
|| {};
1798 this.$button
= null;
1800 this.active
= false;
1801 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
1802 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
1803 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
1804 this.onKeyUpHandler
= this.onKeyUp
.bind( this );
1805 this.onClickHandler
= this.onClick
.bind( this );
1806 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
1809 this.$element
.addClass( 'oo-ui-buttonElement' );
1810 this.toggleFramed( config
.framed
=== undefined || config
.framed
);
1811 this.setButtonElement( config
.$button
|| $( '<a>' ) );
1816 OO
.initClass( OO
.ui
.mixin
.ButtonElement
);
1818 /* Static Properties */
1821 * Cancel mouse down events.
1823 * This property is usually set to `true` to prevent the focus from changing when the button is clicked.
1824 * Classes such as {@link OO.ui.mixin.DraggableElement DraggableElement} and {@link OO.ui.ButtonOptionWidget ButtonOptionWidget}
1825 * use a value of `false` so that dragging behavior is possible and mousedown events can be handled by a
1830 * @property {boolean}
1832 OO
.ui
.mixin
.ButtonElement
.static.cancelButtonMouseDownEvents
= true;
1837 * A 'click' event is emitted when the button element is clicked.
1845 * Set the button element.
1847 * This method is used to retarget a button mixin so that its functionality applies to
1848 * the specified button element instead of the one created by the class. If a button element
1849 * is already set, the method will remove the mixin’s effect on that element.
1851 * @param {jQuery} $button Element to use as button
1853 OO
.ui
.mixin
.ButtonElement
.prototype.setButtonElement = function ( $button
) {
1854 if ( this.$button
) {
1856 .removeClass( 'oo-ui-buttonElement-button' )
1857 .removeAttr( 'role accesskey' )
1859 mousedown
: this.onMouseDownHandler
,
1860 keydown
: this.onKeyDownHandler
,
1861 click
: this.onClickHandler
,
1862 keypress
: this.onKeyPressHandler
1866 this.$button
= $button
1867 .addClass( 'oo-ui-buttonElement-button' )
1868 .attr( { role
: 'button' } )
1870 mousedown
: this.onMouseDownHandler
,
1871 keydown
: this.onKeyDownHandler
,
1872 click
: this.onClickHandler
,
1873 keypress
: this.onKeyPressHandler
1878 * Handles mouse down events.
1881 * @param {jQuery.Event} e Mouse down event
1883 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown = function ( e
) {
1884 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
1887 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
1888 // Run the mouseup handler no matter where the mouse is when the button is let go, so we can
1889 // reliably remove the pressed class
1890 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
1891 // Prevent change of focus unless specifically configured otherwise
1892 if ( this.constructor.static.cancelButtonMouseDownEvents
) {
1898 * Handles mouse up events.
1901 * @param {MouseEvent} e Mouse up event
1903 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp = function ( e
) {
1904 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
1907 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
1908 // Stop listening for mouseup, since we only needed this once
1909 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
1913 * Handles mouse click events.
1916 * @param {jQuery.Event} e Mouse click event
1919 OO
.ui
.mixin
.ButtonElement
.prototype.onClick = function ( e
) {
1920 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
1921 if ( this.emit( 'click' ) ) {
1928 * Handles key down events.
1931 * @param {jQuery.Event} e Key down event
1933 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyDown = function ( e
) {
1934 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
1937 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
1938 // Run the keyup handler no matter where the key is when the button is let go, so we can
1939 // reliably remove the pressed class
1940 this.getElementDocument().addEventListener( 'keyup', this.onKeyUpHandler
, true );
1944 * Handles key up events.
1947 * @param {KeyboardEvent} e Key up event
1949 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyUp = function ( e
) {
1950 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
1953 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
1954 // Stop listening for keyup, since we only needed this once
1955 this.getElementDocument().removeEventListener( 'keyup', this.onKeyUpHandler
, true );
1959 * Handles key press events.
1962 * @param {jQuery.Event} e Key press event
1965 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyPress = function ( e
) {
1966 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
1967 if ( this.emit( 'click' ) ) {
1974 * Check if button has a frame.
1976 * @return {boolean} Button is framed
1978 OO
.ui
.mixin
.ButtonElement
.prototype.isFramed = function () {
1983 * Render the button with or without a frame. Omit the `framed` parameter to toggle the button frame on and off.
1985 * @param {boolean} [framed] Make button framed, omit to toggle
1988 OO
.ui
.mixin
.ButtonElement
.prototype.toggleFramed = function ( framed
) {
1989 framed
= framed
=== undefined ? !this.framed
: !!framed
;
1990 if ( framed
!== this.framed
) {
1991 this.framed
= framed
;
1993 .toggleClass( 'oo-ui-buttonElement-frameless', !framed
)
1994 .toggleClass( 'oo-ui-buttonElement-framed', framed
);
1995 this.updateThemeClasses();
2002 * Set the button's active state.
2004 * The active state occurs when a {@link OO.ui.ButtonOptionWidget ButtonOptionWidget} or
2005 * a {@link OO.ui.ToggleButtonWidget ToggleButtonWidget} is pressed. This method does nothing
2006 * for other button types.
2008 * @param {boolean} value Make button active
2011 OO
.ui
.mixin
.ButtonElement
.prototype.setActive = function ( value
) {
2012 this.active
= !!value
;
2013 this.$element
.toggleClass( 'oo-ui-buttonElement-active', this.active
);
2018 * Check if the button is active
2020 * @return {boolean} The button is active
2022 OO
.ui
.mixin
.ButtonElement
.prototype.isActive = function () {
2027 * Any OOjs UI widget that contains other widgets (such as {@link OO.ui.ButtonWidget buttons} or
2028 * {@link OO.ui.OptionWidget options}) mixes in GroupElement. Adding, removing, and clearing
2029 * items from the group is done through the interface the class provides.
2030 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
2032 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Groups
2038 * @param {Object} [config] Configuration options
2039 * @cfg {jQuery} [$group] The container element created by the class. If this configuration
2040 * is omitted, the group element will use a generated `<div>`.
2042 OO
.ui
.mixin
.GroupElement
= function OoUiMixinGroupElement( config
) {
2043 // Configuration initialization
2044 config
= config
|| {};
2049 this.aggregateItemEvents
= {};
2052 this.setGroupElement( config
.$group
|| $( '<div>' ) );
2058 * Set the group element.
2060 * If an element is already set, items will be moved to the new element.
2062 * @param {jQuery} $group Element to use as group
2064 OO
.ui
.mixin
.GroupElement
.prototype.setGroupElement = function ( $group
) {
2067 this.$group
= $group
;
2068 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2069 this.$group
.append( this.items
[ i
].$element
);
2074 * Check if a group contains no items.
2076 * @return {boolean} Group is empty
2078 OO
.ui
.mixin
.GroupElement
.prototype.isEmpty = function () {
2079 return !this.items
.length
;
2083 * Get all items in the group.
2085 * The method returns an array of item references (e.g., [button1, button2, button3]) and is useful
2086 * when synchronizing groups of items, or whenever the references are required (e.g., when removing items
2089 * @return {OO.ui.Element[]} An array of items.
2091 OO
.ui
.mixin
.GroupElement
.prototype.getItems = function () {
2092 return this.items
.slice( 0 );
2096 * Get an item by its data.
2098 * Only the first item with matching data will be returned. To return all matching items,
2099 * use the #getItemsFromData method.
2101 * @param {Object} data Item data to search for
2102 * @return {OO.ui.Element|null} Item with equivalent data, `null` if none exists
2104 OO
.ui
.mixin
.GroupElement
.prototype.getItemFromData = function ( data
) {
2106 hash
= OO
.getHash( data
);
2108 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2109 item
= this.items
[ i
];
2110 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2119 * Get items by their data.
2121 * All items with matching data will be returned. To return only the first match, use the #getItemFromData method instead.
2123 * @param {Object} data Item data to search for
2124 * @return {OO.ui.Element[]} Items with equivalent data
2126 OO
.ui
.mixin
.GroupElement
.prototype.getItemsFromData = function ( data
) {
2128 hash
= OO
.getHash( data
),
2131 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2132 item
= this.items
[ i
];
2133 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2142 * Aggregate the events emitted by the group.
2144 * When events are aggregated, the group will listen to all contained items for the event,
2145 * and then emit the event under a new name. The new event will contain an additional leading
2146 * parameter containing the item that emitted the original event. Other arguments emitted from
2147 * the original event are passed through.
2149 * @param {Object.<string,string|null>} events An object keyed by the name of the event that should be
2150 * aggregated (e.g., ‘click’) and the value of the new name to use (e.g., ‘groupClick’).
2151 * A `null` value will remove aggregated events.
2153 * @throws {Error} An error is thrown if aggregation already exists.
2155 OO
.ui
.mixin
.GroupElement
.prototype.aggregate = function ( events
) {
2156 var i
, len
, item
, add
, remove
, itemEvent
, groupEvent
;
2158 for ( itemEvent
in events
) {
2159 groupEvent
= events
[ itemEvent
];
2161 // Remove existing aggregated event
2162 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2163 // Don't allow duplicate aggregations
2165 throw new Error( 'Duplicate item event aggregation for ' + itemEvent
);
2167 // Remove event aggregation from existing items
2168 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2169 item
= this.items
[ i
];
2170 if ( item
.connect
&& item
.disconnect
) {
2172 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2173 item
.disconnect( this, remove
);
2176 // Prevent future items from aggregating event
2177 delete this.aggregateItemEvents
[ itemEvent
];
2180 // Add new aggregate event
2182 // Make future items aggregate event
2183 this.aggregateItemEvents
[ itemEvent
] = groupEvent
;
2184 // Add event aggregation to existing items
2185 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2186 item
= this.items
[ i
];
2187 if ( item
.connect
&& item
.disconnect
) {
2189 add
[ itemEvent
] = [ 'emit', groupEvent
, item
];
2190 item
.connect( this, add
);
2198 * Add items to the group.
2200 * Items will be added to the end of the group array unless the optional `index` parameter specifies
2201 * a different insertion point. Adding an existing item will move it to the end of the array or the point specified by the `index`.
2203 * @param {OO.ui.Element[]} items An array of items to add to the group
2204 * @param {number} [index] Index of the insertion point
2207 OO
.ui
.mixin
.GroupElement
.prototype.addItems = function ( items
, index
) {
2208 var i
, len
, item
, event
, events
, currentIndex
,
2211 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2214 // Check if item exists then remove it first, effectively "moving" it
2215 currentIndex
= this.items
.indexOf( item
);
2216 if ( currentIndex
>= 0 ) {
2217 this.removeItems( [ item
] );
2218 // Adjust index to compensate for removal
2219 if ( currentIndex
< index
) {
2224 if ( item
.connect
&& item
.disconnect
&& !$.isEmptyObject( this.aggregateItemEvents
) ) {
2226 for ( event
in this.aggregateItemEvents
) {
2227 events
[ event
] = [ 'emit', this.aggregateItemEvents
[ event
], item
];
2229 item
.connect( this, events
);
2231 item
.setElementGroup( this );
2232 itemElements
.push( item
.$element
.get( 0 ) );
2235 if ( index
=== undefined || index
< 0 || index
>= this.items
.length
) {
2236 this.$group
.append( itemElements
);
2237 this.items
.push
.apply( this.items
, items
);
2238 } else if ( index
=== 0 ) {
2239 this.$group
.prepend( itemElements
);
2240 this.items
.unshift
.apply( this.items
, items
);
2242 this.items
[ index
].$element
.before( itemElements
);
2243 this.items
.splice
.apply( this.items
, [ index
, 0 ].concat( items
) );
2250 * Remove the specified items from a group.
2252 * Removed items are detached (not removed) from the DOM so that they may be reused.
2253 * To remove all items from a group, you may wish to use the #clearItems method instead.
2255 * @param {OO.ui.Element[]} items An array of items to remove
2258 OO
.ui
.mixin
.GroupElement
.prototype.removeItems = function ( items
) {
2259 var i
, len
, item
, index
, remove
, itemEvent
;
2261 // Remove specific items
2262 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2264 index
= this.items
.indexOf( item
);
2265 if ( index
!== -1 ) {
2267 item
.connect
&& item
.disconnect
&&
2268 !$.isEmptyObject( this.aggregateItemEvents
)
2271 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2272 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2274 item
.disconnect( this, remove
);
2276 item
.setElementGroup( null );
2277 this.items
.splice( index
, 1 );
2278 item
.$element
.detach();
2286 * Clear all items from the group.
2288 * Cleared items are detached from the DOM, not removed, so that they may be reused.
2289 * To remove only a subset of items from a group, use the #removeItems method.
2293 OO
.ui
.mixin
.GroupElement
.prototype.clearItems = function () {
2294 var i
, len
, item
, remove
, itemEvent
;
2297 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2298 item
= this.items
[ i
];
2300 item
.connect
&& item
.disconnect
&&
2301 !$.isEmptyObject( this.aggregateItemEvents
)
2304 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2305 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2307 item
.disconnect( this, remove
);
2309 item
.setElementGroup( null );
2310 item
.$element
.detach();
2318 * IconElement is often mixed into other classes to generate an icon.
2319 * Icons are graphics, about the size of normal text. They are used to aid the user
2320 * in locating a control or to convey information in a space-efficient way. See the
2321 * [OOjs UI documentation on MediaWiki] [1] for a list of icons
2322 * included in the library.
2324 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2330 * @param {Object} [config] Configuration options
2331 * @cfg {jQuery} [$icon] The icon element created by the class. If this configuration is omitted,
2332 * the icon element will use a generated `<span>`. To use a different HTML tag, or to specify that
2333 * the icon element be set to an existing icon instead of the one generated by this class, set a
2334 * value using a jQuery selection. For example:
2336 * // Use a <div> tag instead of a <span>
2338 * // Use an existing icon element instead of the one generated by the class
2339 * $icon: this.$element
2340 * // Use an icon element from a child widget
2341 * $icon: this.childwidget.$element
2342 * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
2343 * symbolic names. A map is used for i18n purposes and contains a `default` icon
2344 * name and additional names keyed by language code. The `default` name is used when no icon is keyed
2345 * by the user's language.
2347 * Example of an i18n map:
2349 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2350 * See the [OOjs UI documentation on MediaWiki] [2] for a list of icons included in the library.
2351 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2352 * @cfg {string|Function} [iconTitle] A text string used as the icon title, or a function that returns title
2353 * text. The icon title is displayed when users move the mouse over the icon.
2355 OO
.ui
.mixin
.IconElement
= function OoUiMixinIconElement( config
) {
2356 // Configuration initialization
2357 config
= config
|| {};
2362 this.iconTitle
= null;
2365 this.setIcon( config
.icon
|| this.constructor.static.icon
);
2366 this.setIconTitle( config
.iconTitle
|| this.constructor.static.iconTitle
);
2367 this.setIconElement( config
.$icon
|| $( '<span>' ) );
2372 OO
.initClass( OO
.ui
.mixin
.IconElement
);
2374 /* Static Properties */
2377 * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map is used
2378 * for i18n purposes and contains a `default` icon name and additional names keyed by
2379 * language code. The `default` name is used when no icon is keyed by the user's language.
2381 * Example of an i18n map:
2383 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2385 * Note: the static property will be overridden if the #icon configuration is used.
2389 * @property {Object|string}
2391 OO
.ui
.mixin
.IconElement
.static.icon
= null;
2394 * The icon title, displayed when users move the mouse over the icon. The value can be text, a
2395 * function that returns title text, or `null` for no title.
2397 * The static property will be overridden if the #iconTitle configuration is used.
2401 * @property {string|Function|null}
2403 OO
.ui
.mixin
.IconElement
.static.iconTitle
= null;
2408 * Set the icon element. This method is used to retarget an icon mixin so that its functionality
2409 * applies to the specified icon element instead of the one created by the class. If an icon
2410 * element is already set, the mixin’s effect on that element is removed. Generated CSS classes
2411 * and mixin methods will no longer affect the element.
2413 * @param {jQuery} $icon Element to use as icon
2415 OO
.ui
.mixin
.IconElement
.prototype.setIconElement = function ( $icon
) {
2418 .removeClass( 'oo-ui-iconElement-icon oo-ui-icon-' + this.icon
)
2419 .removeAttr( 'title' );
2423 .addClass( 'oo-ui-iconElement-icon' )
2424 .toggleClass( 'oo-ui-icon-' + this.icon
, !!this.icon
);
2425 if ( this.iconTitle
!== null ) {
2426 this.$icon
.attr( 'title', this.iconTitle
);
2429 this.updateThemeClasses();
2433 * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove an icon.
2434 * The icon parameter can also be set to a map of icon names. See the #icon config setting
2437 * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map of icon names} keyed
2438 * by language code, or `null` to remove the icon.
2441 OO
.ui
.mixin
.IconElement
.prototype.setIcon = function ( icon
) {
2442 icon
= OO
.isPlainObject( icon
) ? OO
.ui
.getLocalValue( icon
, null, 'default' ) : icon
;
2443 icon
= typeof icon
=== 'string' && icon
.trim().length
? icon
.trim() : null;
2445 if ( this.icon
!== icon
) {
2447 if ( this.icon
!== null ) {
2448 this.$icon
.removeClass( 'oo-ui-icon-' + this.icon
);
2450 if ( icon
!== null ) {
2451 this.$icon
.addClass( 'oo-ui-icon-' + icon
);
2457 this.$element
.toggleClass( 'oo-ui-iconElement', !!this.icon
);
2458 this.updateThemeClasses();
2464 * Set the icon title. Use `null` to remove the title.
2466 * @param {string|Function|null} iconTitle A text string used as the icon title,
2467 * a function that returns title text, or `null` for no title.
2470 OO
.ui
.mixin
.IconElement
.prototype.setIconTitle = function ( iconTitle
) {
2471 iconTitle
= typeof iconTitle
=== 'function' ||
2472 ( typeof iconTitle
=== 'string' && iconTitle
.length
) ?
2473 OO
.ui
.resolveMsg( iconTitle
) : null;
2475 if ( this.iconTitle
!== iconTitle
) {
2476 this.iconTitle
= iconTitle
;
2478 if ( this.iconTitle
!== null ) {
2479 this.$icon
.attr( 'title', iconTitle
);
2481 this.$icon
.removeAttr( 'title' );
2490 * Get the symbolic name of the icon.
2492 * @return {string} Icon name
2494 OO
.ui
.mixin
.IconElement
.prototype.getIcon = function () {
2499 * Get the icon title. The title text is displayed when a user moves the mouse over the icon.
2501 * @return {string} Icon title text
2503 OO
.ui
.mixin
.IconElement
.prototype.getIconTitle = function () {
2504 return this.iconTitle
;
2508 * IndicatorElement is often mixed into other classes to generate an indicator.
2509 * Indicators are small graphics that are generally used in two ways:
2511 * - To draw attention to the status of an item. For example, an indicator might be
2512 * used to show that an item in a list has errors that need to be resolved.
2513 * - To clarify the function of a control that acts in an exceptional way (a button
2514 * that opens a menu instead of performing an action directly, for example).
2516 * For a list of indicators included in the library, please see the
2517 * [OOjs UI documentation on MediaWiki] [1].
2519 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2525 * @param {Object} [config] Configuration options
2526 * @cfg {jQuery} [$indicator] The indicator element created by the class. If this
2527 * configuration is omitted, the indicator element will use a generated `<span>`.
2528 * @cfg {string} [indicator] Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2529 * See the [OOjs UI documentation on MediaWiki][2] for a list of indicators included
2531 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2532 * @cfg {string|Function} [indicatorTitle] A text string used as the indicator title,
2533 * or a function that returns title text. The indicator title is displayed when users move
2534 * the mouse over the indicator.
2536 OO
.ui
.mixin
.IndicatorElement
= function OoUiMixinIndicatorElement( config
) {
2537 // Configuration initialization
2538 config
= config
|| {};
2541 this.$indicator
= null;
2542 this.indicator
= null;
2543 this.indicatorTitle
= null;
2546 this.setIndicator( config
.indicator
|| this.constructor.static.indicator
);
2547 this.setIndicatorTitle( config
.indicatorTitle
|| this.constructor.static.indicatorTitle
);
2548 this.setIndicatorElement( config
.$indicator
|| $( '<span>' ) );
2553 OO
.initClass( OO
.ui
.mixin
.IndicatorElement
);
2555 /* Static Properties */
2558 * Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2559 * The static property will be overridden if the #indicator configuration is used.
2563 * @property {string|null}
2565 OO
.ui
.mixin
.IndicatorElement
.static.indicator
= null;
2568 * A text string used as the indicator title, a function that returns title text, or `null`
2569 * for no title. The static property will be overridden if the #indicatorTitle configuration is used.
2573 * @property {string|Function|null}
2575 OO
.ui
.mixin
.IndicatorElement
.static.indicatorTitle
= null;
2580 * Set the indicator element.
2582 * If an element is already set, it will be cleaned up before setting up the new element.
2584 * @param {jQuery} $indicator Element to use as indicator
2586 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorElement = function ( $indicator
) {
2587 if ( this.$indicator
) {
2589 .removeClass( 'oo-ui-indicatorElement-indicator oo-ui-indicator-' + this.indicator
)
2590 .removeAttr( 'title' );
2593 this.$indicator
= $indicator
2594 .addClass( 'oo-ui-indicatorElement-indicator' )
2595 .toggleClass( 'oo-ui-indicator-' + this.indicator
, !!this.indicator
);
2596 if ( this.indicatorTitle
!== null ) {
2597 this.$indicator
.attr( 'title', this.indicatorTitle
);
2600 this.updateThemeClasses();
2604 * Set the indicator by its symbolic name: ‘alert’, ‘down’, ‘next’, ‘previous’, ‘required’, ‘up’. Use `null` to remove the indicator.
2606 * @param {string|null} indicator Symbolic name of indicator, or `null` for no indicator
2609 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicator = function ( indicator
) {
2610 indicator
= typeof indicator
=== 'string' && indicator
.length
? indicator
.trim() : null;
2612 if ( this.indicator
!== indicator
) {
2613 if ( this.$indicator
) {
2614 if ( this.indicator
!== null ) {
2615 this.$indicator
.removeClass( 'oo-ui-indicator-' + this.indicator
);
2617 if ( indicator
!== null ) {
2618 this.$indicator
.addClass( 'oo-ui-indicator-' + indicator
);
2621 this.indicator
= indicator
;
2624 this.$element
.toggleClass( 'oo-ui-indicatorElement', !!this.indicator
);
2625 this.updateThemeClasses();
2631 * Set the indicator title.
2633 * The title is displayed when a user moves the mouse over the indicator.
2635 * @param {string|Function|null} indicatorTitle Indicator title text, a function that returns text, or
2636 * `null` for no indicator title
2639 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorTitle = function ( indicatorTitle
) {
2640 indicatorTitle
= typeof indicatorTitle
=== 'function' ||
2641 ( typeof indicatorTitle
=== 'string' && indicatorTitle
.length
) ?
2642 OO
.ui
.resolveMsg( indicatorTitle
) : null;
2644 if ( this.indicatorTitle
!== indicatorTitle
) {
2645 this.indicatorTitle
= indicatorTitle
;
2646 if ( this.$indicator
) {
2647 if ( this.indicatorTitle
!== null ) {
2648 this.$indicator
.attr( 'title', indicatorTitle
);
2650 this.$indicator
.removeAttr( 'title' );
2659 * Get the symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2661 * @return {string} Symbolic name of indicator
2663 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicator = function () {
2664 return this.indicator
;
2668 * Get the indicator title.
2670 * The title is displayed when a user moves the mouse over the indicator.
2672 * @return {string} Indicator title text
2674 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicatorTitle = function () {
2675 return this.indicatorTitle
;
2679 * LabelElement is often mixed into other classes to generate a label, which
2680 * helps identify the function of an interface element.
2681 * See the [OOjs UI documentation on MediaWiki] [1] for more information.
2683 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2689 * @param {Object} [config] Configuration options
2690 * @cfg {jQuery} [$label] The label element created by the class. If this
2691 * configuration is omitted, the label element will use a generated `<span>`.
2692 * @cfg {jQuery|string|Function|OO.ui.HtmlSnippet} [label] The label text. The label can be specified
2693 * as a plaintext string, a jQuery selection of elements, or a function that will produce a string
2694 * in the future. See the [OOjs UI documentation on MediaWiki] [2] for examples.
2695 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2697 OO
.ui
.mixin
.LabelElement
= function OoUiMixinLabelElement( config
) {
2698 // Configuration initialization
2699 config
= config
|| {};
2706 this.setLabel( config
.label
|| this.constructor.static.label
);
2707 this.setLabelElement( config
.$label
|| $( '<span>' ) );
2712 OO
.initClass( OO
.ui
.mixin
.LabelElement
);
2717 * @event labelChange
2718 * @param {string} value
2721 /* Static Properties */
2724 * The label text. The label can be specified as a plaintext string, a function that will
2725 * produce a string in the future, or `null` for no label. The static value will
2726 * be overridden if a label is specified with the #label config option.
2730 * @property {string|Function|null}
2732 OO
.ui
.mixin
.LabelElement
.static.label
= null;
2734 /* Static methods */
2737 * Highlight the first occurrence of the query in the given text
2739 * @param {string} text Text
2740 * @param {string} query Query to find
2741 * @return {jQuery} Text with the first match of the query
2742 * sub-string wrapped in highlighted span
2744 OO
.ui
.mixin
.LabelElement
.static.highlightQuery = function ( text
, query
) {
2745 var $result
= $( '<span>' ),
2746 offset
= text
.toLowerCase().indexOf( query
.toLowerCase() );
2748 if ( !query
.length
|| offset
=== -1 ) {
2749 return $result
.text( text
);
2752 document
.createTextNode( text
.slice( 0, offset
) ),
2754 .addClass( 'oo-ui-labelElement-label-highlight' )
2755 .text( text
.slice( offset
, offset
+ query
.length
) ),
2756 document
.createTextNode( text
.slice( offset
+ query
.length
) )
2758 return $result
.contents();
2764 * Set the label element.
2766 * If an element is already set, it will be cleaned up before setting up the new element.
2768 * @param {jQuery} $label Element to use as label
2770 OO
.ui
.mixin
.LabelElement
.prototype.setLabelElement = function ( $label
) {
2771 if ( this.$label
) {
2772 this.$label
.removeClass( 'oo-ui-labelElement-label' ).empty();
2775 this.$label
= $label
.addClass( 'oo-ui-labelElement-label' );
2776 this.setLabelContent( this.label
);
2782 * An empty string will result in the label being hidden. A string containing only whitespace will
2783 * be converted to a single ` `.
2785 * @param {jQuery|string|OO.ui.HtmlSnippet|Function|null} label Label nodes; text; a function that returns nodes or
2786 * text; or null for no label
2789 OO
.ui
.mixin
.LabelElement
.prototype.setLabel = function ( label
) {
2790 label
= typeof label
=== 'function' ? OO
.ui
.resolveMsg( label
) : label
;
2791 label
= ( ( typeof label
=== 'string' && label
.length
) || label
instanceof jQuery
|| label
instanceof OO
.ui
.HtmlSnippet
) ? label
: null;
2793 this.$element
.toggleClass( 'oo-ui-labelElement', !!label
);
2795 if ( this.label
!== label
) {
2796 if ( this.$label
) {
2797 this.setLabelContent( label
);
2800 this.emit( 'labelChange' );
2807 * Set the label as plain text with a highlighted query
2809 * @param {string} text Text label to set
2810 * @param {string} query Substring of text to highlight
2813 OO
.ui
.mixin
.LabelElement
.prototype.setHighlightedQuery = function ( text
, query
) {
2814 return this.setLabel( this.constructor.static.highlightQuery( text
, query
) );
2820 * @return {jQuery|string|Function|null} Label nodes; text; a function that returns nodes or
2821 * text; or null for no label
2823 OO
.ui
.mixin
.LabelElement
.prototype.getLabel = function () {
2831 * @deprecated since 0.16.0
2833 OO
.ui
.mixin
.LabelElement
.prototype.fitLabel = function () {
2838 * Set the content of the label.
2840 * Do not call this method until after the label element has been set by #setLabelElement.
2843 * @param {jQuery|string|Function|null} label Label nodes; text; a function that returns nodes or
2844 * text; or null for no label
2846 OO
.ui
.mixin
.LabelElement
.prototype.setLabelContent = function ( label
) {
2847 if ( typeof label
=== 'string' ) {
2848 if ( label
.match( /^\s*$/ ) ) {
2849 // Convert whitespace only string to a single non-breaking space
2850 this.$label
.html( ' ' );
2852 this.$label
.text( label
);
2854 } else if ( label
instanceof OO
.ui
.HtmlSnippet
) {
2855 this.$label
.html( label
.toString() );
2856 } else if ( label
instanceof jQuery
) {
2857 this.$label
.empty().append( label
);
2859 this.$label
.empty();
2864 * The FlaggedElement class is an attribute mixin, meaning that it is used to add
2865 * additional functionality to an element created by another class. The class provides
2866 * a ‘flags’ property assigned the name (or an array of names) of styling flags,
2867 * which are used to customize the look and feel of a widget to better describe its
2868 * importance and functionality.
2870 * The library currently contains the following styling flags for general use:
2872 * - **progressive**: Progressive styling is applied to convey that the widget will move the user forward in a process.
2873 * - **destructive**: Destructive styling is applied to convey that the widget will remove something.
2874 * - **constructive**: Constructive styling is applied to convey that the widget will create something.
2876 * The flags affect the appearance of the buttons:
2879 * // FlaggedElement is mixed into ButtonWidget to provide styling flags
2880 * var button1 = new OO.ui.ButtonWidget( {
2881 * label: 'Constructive',
2882 * flags: 'constructive'
2884 * var button2 = new OO.ui.ButtonWidget( {
2885 * label: 'Destructive',
2886 * flags: 'destructive'
2888 * var button3 = new OO.ui.ButtonWidget( {
2889 * label: 'Progressive',
2890 * flags: 'progressive'
2892 * $( 'body' ).append( button1.$element, button2.$element, button3.$element );
2894 * {@link OO.ui.ActionWidget ActionWidgets}, which are a special kind of button that execute an action, use these flags: **primary** and **safe**.
2895 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
2897 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2903 * @param {Object} [config] Configuration options
2904 * @cfg {string|string[]} [flags] The name or names of the flags (e.g., 'constructive' or 'primary') to apply.
2905 * Please see the [OOjs UI documentation on MediaWiki] [2] for more information about available flags.
2906 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2907 * @cfg {jQuery} [$flagged] The flagged element. By default,
2908 * the flagged functionality is applied to the element created by the class ($element).
2909 * If a different element is specified, the flagged functionality will be applied to it instead.
2911 OO
.ui
.mixin
.FlaggedElement
= function OoUiMixinFlaggedElement( config
) {
2912 // Configuration initialization
2913 config
= config
|| {};
2917 this.$flagged
= null;
2920 this.setFlags( config
.flags
);
2921 this.setFlaggedElement( config
.$flagged
|| this.$element
);
2928 * A flag event is emitted when the #clearFlags or #setFlags methods are used. The `changes`
2929 * parameter contains the name of each modified flag and indicates whether it was
2932 * @param {Object.<string,boolean>} changes Object keyed by flag name. A Boolean `true` indicates
2933 * that the flag was added, `false` that the flag was removed.
2939 * Set the flagged element.
2941 * This method is used to retarget a flagged mixin so that its functionality applies to the specified element.
2942 * If an element is already set, the method will remove the mixin’s effect on that element.
2944 * @param {jQuery} $flagged Element that should be flagged
2946 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlaggedElement = function ( $flagged
) {
2947 var classNames
= Object
.keys( this.flags
).map( function ( flag
) {
2948 return 'oo-ui-flaggedElement-' + flag
;
2951 if ( this.$flagged
) {
2952 this.$flagged
.removeClass( classNames
);
2955 this.$flagged
= $flagged
.addClass( classNames
);
2959 * Check if the specified flag is set.
2961 * @param {string} flag Name of flag
2962 * @return {boolean} The flag is set
2964 OO
.ui
.mixin
.FlaggedElement
.prototype.hasFlag = function ( flag
) {
2965 // This may be called before the constructor, thus before this.flags is set
2966 return this.flags
&& ( flag
in this.flags
);
2970 * Get the names of all flags set.
2972 * @return {string[]} Flag names
2974 OO
.ui
.mixin
.FlaggedElement
.prototype.getFlags = function () {
2975 // This may be called before the constructor, thus before this.flags is set
2976 return Object
.keys( this.flags
|| {} );
2985 OO
.ui
.mixin
.FlaggedElement
.prototype.clearFlags = function () {
2986 var flag
, className
,
2989 classPrefix
= 'oo-ui-flaggedElement-';
2991 for ( flag
in this.flags
) {
2992 className
= classPrefix
+ flag
;
2993 changes
[ flag
] = false;
2994 delete this.flags
[ flag
];
2995 remove
.push( className
);
2998 if ( this.$flagged
) {
2999 this.$flagged
.removeClass( remove
.join( ' ' ) );
3002 this.updateThemeClasses();
3003 this.emit( 'flag', changes
);
3009 * Add one or more flags.
3011 * @param {string|string[]|Object.<string, boolean>} flags A flag name, an array of flag names,
3012 * or an object keyed by flag name with a boolean value that indicates whether the flag should
3013 * be added (`true`) or removed (`false`).
3017 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlags = function ( flags
) {
3018 var i
, len
, flag
, className
,
3022 classPrefix
= 'oo-ui-flaggedElement-';
3024 if ( typeof flags
=== 'string' ) {
3025 className
= classPrefix
+ flags
;
3027 if ( !this.flags
[ flags
] ) {
3028 this.flags
[ flags
] = true;
3029 add
.push( className
);
3031 } else if ( Array
.isArray( flags
) ) {
3032 for ( i
= 0, len
= flags
.length
; i
< len
; i
++ ) {
3034 className
= classPrefix
+ flag
;
3036 if ( !this.flags
[ flag
] ) {
3037 changes
[ flag
] = true;
3038 this.flags
[ flag
] = true;
3039 add
.push( className
);
3042 } else if ( OO
.isPlainObject( flags
) ) {
3043 for ( flag
in flags
) {
3044 className
= classPrefix
+ flag
;
3045 if ( flags
[ flag
] ) {
3047 if ( !this.flags
[ flag
] ) {
3048 changes
[ flag
] = true;
3049 this.flags
[ flag
] = true;
3050 add
.push( className
);
3054 if ( this.flags
[ flag
] ) {
3055 changes
[ flag
] = false;
3056 delete this.flags
[ flag
];
3057 remove
.push( className
);
3063 if ( this.$flagged
) {
3065 .addClass( add
.join( ' ' ) )
3066 .removeClass( remove
.join( ' ' ) );
3069 this.updateThemeClasses();
3070 this.emit( 'flag', changes
);
3076 * TitledElement is mixed into other classes to provide a `title` attribute.
3077 * Titles are rendered by the browser and are made visible when the user moves
3078 * the mouse over the element. Titles are not visible on touch devices.
3081 * // TitledElement provides a 'title' attribute to the
3082 * // ButtonWidget class
3083 * var button = new OO.ui.ButtonWidget( {
3084 * label: 'Button with Title',
3085 * title: 'I am a button'
3087 * $( 'body' ).append( button.$element );
3093 * @param {Object} [config] Configuration options
3094 * @cfg {jQuery} [$titled] The element to which the `title` attribute is applied.
3095 * If this config is omitted, the title functionality is applied to $element, the
3096 * element created by the class.
3097 * @cfg {string|Function} [title] The title text or a function that returns text. If
3098 * this config is omitted, the value of the {@link #static-title static title} property is used.
3100 OO
.ui
.mixin
.TitledElement
= function OoUiMixinTitledElement( config
) {
3101 // Configuration initialization
3102 config
= config
|| {};
3105 this.$titled
= null;
3109 this.setTitle( config
.title
!== undefined ? config
.title
: this.constructor.static.title
);
3110 this.setTitledElement( config
.$titled
|| this.$element
);
3115 OO
.initClass( OO
.ui
.mixin
.TitledElement
);
3117 /* Static Properties */
3120 * The title text, a function that returns text, or `null` for no title. The value of the static property
3121 * is overridden if the #title config option is used.
3125 * @property {string|Function|null}
3127 OO
.ui
.mixin
.TitledElement
.static.title
= null;
3132 * Set the titled element.
3134 * This method is used to retarget a titledElement mixin so that its functionality applies to the specified element.
3135 * If an element is already set, the mixin’s effect on that element is removed before the new element is set up.
3137 * @param {jQuery} $titled Element that should use the 'titled' functionality
3139 OO
.ui
.mixin
.TitledElement
.prototype.setTitledElement = function ( $titled
) {
3140 if ( this.$titled
) {
3141 this.$titled
.removeAttr( 'title' );
3144 this.$titled
= $titled
;
3146 this.$titled
.attr( 'title', this.title
);
3153 * @param {string|Function|null} title Title text, a function that returns text, or `null` for no title
3156 OO
.ui
.mixin
.TitledElement
.prototype.setTitle = function ( title
) {
3157 title
= typeof title
=== 'function' ? OO
.ui
.resolveMsg( title
) : title
;
3158 title
= ( typeof title
=== 'string' && title
.length
) ? title
: null;
3160 if ( this.title
!== title
) {
3161 if ( this.$titled
) {
3162 if ( title
!== null ) {
3163 this.$titled
.attr( 'title', title
);
3165 this.$titled
.removeAttr( 'title' );
3177 * @return {string} Title string
3179 OO
.ui
.mixin
.TitledElement
.prototype.getTitle = function () {
3184 * AccessKeyedElement is mixed into other classes to provide an `accesskey` attribute.
3185 * Accesskeys allow an user to go to a specific element by using
3186 * a shortcut combination of a browser specific keys + the key
3190 * // AccessKeyedElement provides an 'accesskey' attribute to the
3191 * // ButtonWidget class
3192 * var button = new OO.ui.ButtonWidget( {
3193 * label: 'Button with Accesskey',
3196 * $( 'body' ).append( button.$element );
3202 * @param {Object} [config] Configuration options
3203 * @cfg {jQuery} [$accessKeyed] The element to which the `accesskey` attribute is applied.
3204 * If this config is omitted, the accesskey functionality is applied to $element, the
3205 * element created by the class.
3206 * @cfg {string|Function} [accessKey] The key or a function that returns the key. If
3207 * this config is omitted, no accesskey will be added.
3209 OO
.ui
.mixin
.AccessKeyedElement
= function OoUiMixinAccessKeyedElement( config
) {
3210 // Configuration initialization
3211 config
= config
|| {};
3214 this.$accessKeyed
= null;
3215 this.accessKey
= null;
3218 this.setAccessKey( config
.accessKey
|| null );
3219 this.setAccessKeyedElement( config
.$accessKeyed
|| this.$element
);
3224 OO
.initClass( OO
.ui
.mixin
.AccessKeyedElement
);
3226 /* Static Properties */
3229 * The access key, a function that returns a key, or `null` for no accesskey.
3233 * @property {string|Function|null}
3235 OO
.ui
.mixin
.AccessKeyedElement
.static.accessKey
= null;
3240 * Set the accesskeyed element.
3242 * This method is used to retarget a AccessKeyedElement mixin so that its functionality applies to the specified element.
3243 * If an element is already set, the mixin's effect on that element is removed before the new element is set up.
3245 * @param {jQuery} $accessKeyed Element that should use the 'accesskeyes' functionality
3247 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKeyedElement = function ( $accessKeyed
) {
3248 if ( this.$accessKeyed
) {
3249 this.$accessKeyed
.removeAttr( 'accesskey' );
3252 this.$accessKeyed
= $accessKeyed
;
3253 if ( this.accessKey
) {
3254 this.$accessKeyed
.attr( 'accesskey', this.accessKey
);
3261 * @param {string|Function|null} accessKey Key, a function that returns a key, or `null` for no accesskey
3264 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKey = function ( accessKey
) {
3265 accessKey
= typeof accessKey
=== 'string' ? OO
.ui
.resolveMsg( accessKey
) : null;
3267 if ( this.accessKey
!== accessKey
) {
3268 if ( this.$accessKeyed
) {
3269 if ( accessKey
!== null ) {
3270 this.$accessKeyed
.attr( 'accesskey', accessKey
);
3272 this.$accessKeyed
.removeAttr( 'accesskey' );
3275 this.accessKey
= accessKey
;
3284 * @return {string} accessKey string
3286 OO
.ui
.mixin
.AccessKeyedElement
.prototype.getAccessKey = function () {
3287 return this.accessKey
;
3291 * ButtonWidget is a generic widget for buttons. A wide variety of looks,
3292 * feels, and functionality can be customized via the class’s configuration options
3293 * and methods. Please see the [OOjs UI documentation on MediaWiki] [1] for more information
3296 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches
3299 * // A button widget
3300 * var button = new OO.ui.ButtonWidget( {
3301 * label: 'Button with Icon',
3303 * iconTitle: 'Remove'
3305 * $( 'body' ).append( button.$element );
3307 * NOTE: HTML form buttons should use the OO.ui.ButtonInputWidget class.
3310 * @extends OO.ui.Widget
3311 * @mixins OO.ui.mixin.ButtonElement
3312 * @mixins OO.ui.mixin.IconElement
3313 * @mixins OO.ui.mixin.IndicatorElement
3314 * @mixins OO.ui.mixin.LabelElement
3315 * @mixins OO.ui.mixin.TitledElement
3316 * @mixins OO.ui.mixin.FlaggedElement
3317 * @mixins OO.ui.mixin.TabIndexedElement
3318 * @mixins OO.ui.mixin.AccessKeyedElement
3321 * @param {Object} [config] Configuration options
3322 * @cfg {string} [href] Hyperlink to visit when the button is clicked.
3323 * @cfg {string} [target] The frame or window in which to open the hyperlink.
3324 * @cfg {boolean} [noFollow] Search engine traversal hint (default: true)
3326 OO
.ui
.ButtonWidget
= function OoUiButtonWidget( config
) {
3327 // Configuration initialization
3328 config
= config
|| {};
3330 // Parent constructor
3331 OO
.ui
.ButtonWidget
.parent
.call( this, config
);
3333 // Mixin constructors
3334 OO
.ui
.mixin
.ButtonElement
.call( this, config
);
3335 OO
.ui
.mixin
.IconElement
.call( this, config
);
3336 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
3337 OO
.ui
.mixin
.LabelElement
.call( this, config
);
3338 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$button
} ) );
3339 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
3340 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$button
} ) );
3341 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$button
} ) );
3346 this.noFollow
= false;
3349 this.connect( this, { disable
: 'onDisable' } );
3352 this.$button
.append( this.$icon
, this.$label
, this.$indicator
);
3354 .addClass( 'oo-ui-buttonWidget' )
3355 .append( this.$button
);
3356 this.setHref( config
.href
);
3357 this.setTarget( config
.target
);
3358 this.setNoFollow( config
.noFollow
);
3363 OO
.inheritClass( OO
.ui
.ButtonWidget
, OO
.ui
.Widget
);
3364 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.ButtonElement
);
3365 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IconElement
);
3366 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IndicatorElement
);
3367 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.LabelElement
);
3368 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TitledElement
);
3369 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.FlaggedElement
);
3370 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TabIndexedElement
);
3371 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
3378 OO
.ui
.ButtonWidget
.prototype.onMouseDown = function ( e
) {
3379 if ( !this.isDisabled() ) {
3380 // Remove the tab-index while the button is down to prevent the button from stealing focus
3381 this.$button
.removeAttr( 'tabindex' );
3384 return OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown
.call( this, e
);
3390 OO
.ui
.ButtonWidget
.prototype.onMouseUp = function ( e
) {
3391 if ( !this.isDisabled() ) {
3392 // Restore the tab-index after the button is up to restore the button's accessibility
3393 this.$button
.attr( 'tabindex', this.tabIndex
);
3396 return OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp
.call( this, e
);
3400 * Get hyperlink location.
3402 * @return {string} Hyperlink location
3404 OO
.ui
.ButtonWidget
.prototype.getHref = function () {
3409 * Get hyperlink target.
3411 * @return {string} Hyperlink target
3413 OO
.ui
.ButtonWidget
.prototype.getTarget = function () {
3418 * Get search engine traversal hint.
3420 * @return {boolean} Whether search engines should avoid traversing this hyperlink
3422 OO
.ui
.ButtonWidget
.prototype.getNoFollow = function () {
3423 return this.noFollow
;
3427 * Set hyperlink location.
3429 * @param {string|null} href Hyperlink location, null to remove
3431 OO
.ui
.ButtonWidget
.prototype.setHref = function ( href
) {
3432 href
= typeof href
=== 'string' ? href
: null;
3433 if ( href
!== null && !OO
.ui
.isSafeUrl( href
) ) {
3437 if ( href
!== this.href
) {
3446 * Update the `href` attribute, in case of changes to href or
3452 OO
.ui
.ButtonWidget
.prototype.updateHref = function () {
3453 if ( this.href
!== null && !this.isDisabled() ) {
3454 this.$button
.attr( 'href', this.href
);
3456 this.$button
.removeAttr( 'href' );
3463 * Handle disable events.
3466 * @param {boolean} disabled Element is disabled
3468 OO
.ui
.ButtonWidget
.prototype.onDisable = function () {
3473 * Set hyperlink target.
3475 * @param {string|null} target Hyperlink target, null to remove
3477 OO
.ui
.ButtonWidget
.prototype.setTarget = function ( target
) {
3478 target
= typeof target
=== 'string' ? target
: null;
3480 if ( target
!== this.target
) {
3481 this.target
= target
;
3482 if ( target
!== null ) {
3483 this.$button
.attr( 'target', target
);
3485 this.$button
.removeAttr( 'target' );
3493 * Set search engine traversal hint.
3495 * @param {boolean} noFollow True if search engines should avoid traversing this hyperlink
3497 OO
.ui
.ButtonWidget
.prototype.setNoFollow = function ( noFollow
) {
3498 noFollow
= typeof noFollow
=== 'boolean' ? noFollow
: true;
3500 if ( noFollow
!== this.noFollow
) {
3501 this.noFollow
= noFollow
;
3503 this.$button
.attr( 'rel', 'nofollow' );
3505 this.$button
.removeAttr( 'rel' );
3513 * A ButtonGroupWidget groups related buttons and is used together with OO.ui.ButtonWidget and
3514 * its subclasses. Each button in a group is addressed by a unique reference. Buttons can be added,
3515 * removed, and cleared from the group.
3518 * // Example: A ButtonGroupWidget with two buttons
3519 * var button1 = new OO.ui.PopupButtonWidget( {
3520 * label: 'Select a category',
3523 * $content: $( '<p>List of categories...</p>' ),
3528 * var button2 = new OO.ui.ButtonWidget( {
3531 * var buttonGroup = new OO.ui.ButtonGroupWidget( {
3532 * items: [button1, button2]
3534 * $( 'body' ).append( buttonGroup.$element );
3537 * @extends OO.ui.Widget
3538 * @mixins OO.ui.mixin.GroupElement
3541 * @param {Object} [config] Configuration options
3542 * @cfg {OO.ui.ButtonWidget[]} [items] Buttons to add
3544 OO
.ui
.ButtonGroupWidget
= function OoUiButtonGroupWidget( config
) {
3545 // Configuration initialization
3546 config
= config
|| {};
3548 // Parent constructor
3549 OO
.ui
.ButtonGroupWidget
.parent
.call( this, config
);
3551 // Mixin constructors
3552 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
3555 this.$element
.addClass( 'oo-ui-buttonGroupWidget' );
3556 if ( Array
.isArray( config
.items
) ) {
3557 this.addItems( config
.items
);
3563 OO
.inheritClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.Widget
);
3564 OO
.mixinClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.mixin
.GroupElement
);
3567 * IconWidget is a generic widget for {@link OO.ui.mixin.IconElement icons}. In general, IconWidgets should be used with OO.ui.LabelWidget,
3568 * which creates a label that identifies the icon’s function. See the [OOjs UI documentation on MediaWiki] [1]
3569 * for a list of icons included in the library.
3572 * // An icon widget with a label
3573 * var myIcon = new OO.ui.IconWidget( {
3577 * // Create a label.
3578 * var iconLabel = new OO.ui.LabelWidget( {
3581 * $( 'body' ).append( myIcon.$element, iconLabel.$element );
3583 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
3586 * @extends OO.ui.Widget
3587 * @mixins OO.ui.mixin.IconElement
3588 * @mixins OO.ui.mixin.TitledElement
3589 * @mixins OO.ui.mixin.FlaggedElement
3592 * @param {Object} [config] Configuration options
3594 OO
.ui
.IconWidget
= function OoUiIconWidget( config
) {
3595 // Configuration initialization
3596 config
= config
|| {};
3598 // Parent constructor
3599 OO
.ui
.IconWidget
.parent
.call( this, config
);
3601 // Mixin constructors
3602 OO
.ui
.mixin
.IconElement
.call( this, $.extend( {}, config
, { $icon
: this.$element
} ) );
3603 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3604 OO
.ui
.mixin
.FlaggedElement
.call( this, $.extend( {}, config
, { $flagged
: this.$element
} ) );
3607 this.$element
.addClass( 'oo-ui-iconWidget' );
3612 OO
.inheritClass( OO
.ui
.IconWidget
, OO
.ui
.Widget
);
3613 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.IconElement
);
3614 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.TitledElement
);
3615 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.FlaggedElement
);
3617 /* Static Properties */
3619 OO
.ui
.IconWidget
.static.tagName
= 'span';
3622 * IndicatorWidgets create indicators, which are small graphics that are generally used to draw
3623 * attention to the status of an item or to clarify the function of a control. For a list of
3624 * indicators included in the library, please see the [OOjs UI documentation on MediaWiki][1].
3627 * // Example of an indicator widget
3628 * var indicator1 = new OO.ui.IndicatorWidget( {
3629 * indicator: 'alert'
3632 * // Create a fieldset layout to add a label
3633 * var fieldset = new OO.ui.FieldsetLayout();
3634 * fieldset.addItems( [
3635 * new OO.ui.FieldLayout( indicator1, { label: 'An alert indicator:' } )
3637 * $( 'body' ).append( fieldset.$element );
3639 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
3642 * @extends OO.ui.Widget
3643 * @mixins OO.ui.mixin.IndicatorElement
3644 * @mixins OO.ui.mixin.TitledElement
3647 * @param {Object} [config] Configuration options
3649 OO
.ui
.IndicatorWidget
= function OoUiIndicatorWidget( config
) {
3650 // Configuration initialization
3651 config
= config
|| {};
3653 // Parent constructor
3654 OO
.ui
.IndicatorWidget
.parent
.call( this, config
);
3656 // Mixin constructors
3657 OO
.ui
.mixin
.IndicatorElement
.call( this, $.extend( {}, config
, { $indicator
: this.$element
} ) );
3658 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3661 this.$element
.addClass( 'oo-ui-indicatorWidget' );
3666 OO
.inheritClass( OO
.ui
.IndicatorWidget
, OO
.ui
.Widget
);
3667 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.IndicatorElement
);
3668 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.TitledElement
);
3670 /* Static Properties */
3672 OO
.ui
.IndicatorWidget
.static.tagName
= 'span';
3675 * LabelWidgets help identify the function of interface elements. Each LabelWidget can
3676 * be configured with a `label` option that is set to a string, a label node, or a function:
3678 * - String: a plaintext string
3679 * - jQuery selection: a jQuery selection, used for anything other than a plaintext label, e.g., a
3680 * label that includes a link or special styling, such as a gray color or additional graphical elements.
3681 * - Function: a function that will produce a string in the future. Functions are used
3682 * in cases where the value of the label is not currently defined.
3684 * In addition, the LabelWidget can be associated with an {@link OO.ui.InputWidget input widget}, which
3685 * will come into focus when the label is clicked.
3688 * // Examples of LabelWidgets
3689 * var label1 = new OO.ui.LabelWidget( {
3690 * label: 'plaintext label'
3692 * var label2 = new OO.ui.LabelWidget( {
3693 * label: $( '<a href="default.html">jQuery label</a>' )
3695 * // Create a fieldset layout with fields for each example
3696 * var fieldset = new OO.ui.FieldsetLayout();
3697 * fieldset.addItems( [
3698 * new OO.ui.FieldLayout( label1 ),
3699 * new OO.ui.FieldLayout( label2 )
3701 * $( 'body' ).append( fieldset.$element );
3704 * @extends OO.ui.Widget
3705 * @mixins OO.ui.mixin.LabelElement
3708 * @param {Object} [config] Configuration options
3709 * @cfg {OO.ui.InputWidget} [input] {@link OO.ui.InputWidget Input widget} that uses the label.
3710 * Clicking the label will focus the specified input field.
3712 OO
.ui
.LabelWidget
= function OoUiLabelWidget( config
) {
3713 // Configuration initialization
3714 config
= config
|| {};
3716 // Parent constructor
3717 OO
.ui
.LabelWidget
.parent
.call( this, config
);
3719 // Mixin constructors
3720 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: this.$element
} ) );
3721 OO
.ui
.mixin
.TitledElement
.call( this, config
);
3724 this.input
= config
.input
;
3727 if ( this.input
instanceof OO
.ui
.InputWidget
) {
3728 this.$element
.on( 'click', this.onClick
.bind( this ) );
3732 this.$element
.addClass( 'oo-ui-labelWidget' );
3737 OO
.inheritClass( OO
.ui
.LabelWidget
, OO
.ui
.Widget
);
3738 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.LabelElement
);
3739 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.TitledElement
);
3741 /* Static Properties */
3743 OO
.ui
.LabelWidget
.static.tagName
= 'span';
3748 * Handles label mouse click events.
3751 * @param {jQuery.Event} e Mouse click event
3753 OO
.ui
.LabelWidget
.prototype.onClick = function () {
3754 this.input
.simulateLabelClick();
3759 * PendingElement is a mixin that is used to create elements that notify users that something is happening
3760 * and that they should wait before proceeding. The pending state is visually represented with a pending
3761 * texture that appears in the head of a pending {@link OO.ui.ProcessDialog process dialog} or in the input
3762 * field of a {@link OO.ui.TextInputWidget text input widget}.
3764 * Currently, {@link OO.ui.ActionWidget Action widgets}, which mix in this class, can also be marked as pending, but only when
3765 * used in {@link OO.ui.MessageDialog message dialogs}. The behavior is not currently supported for action widgets used
3766 * in process dialogs.
3769 * function MessageDialog( config ) {
3770 * MessageDialog.parent.call( this, config );
3772 * OO.inheritClass( MessageDialog, OO.ui.MessageDialog );
3774 * MessageDialog.static.actions = [
3775 * { action: 'save', label: 'Done', flags: 'primary' },
3776 * { label: 'Cancel', flags: 'safe' }
3779 * MessageDialog.prototype.initialize = function () {
3780 * MessageDialog.parent.prototype.initialize.apply( this, arguments );
3781 * this.content = new OO.ui.PanelLayout( { $: this.$, padded: true } );
3782 * this.content.$element.append( '<p>Click the \'Done\' action widget to see its pending state. Note that action widgets can be marked pending in message dialogs but not process dialogs.</p>' );
3783 * this.$body.append( this.content.$element );
3785 * MessageDialog.prototype.getBodyHeight = function () {
3788 * MessageDialog.prototype.getActionProcess = function ( action ) {
3789 * var dialog = this;
3790 * if ( action === 'save' ) {
3791 * dialog.getActions().get({actions: 'save'})[0].pushPending();
3792 * return new OO.ui.Process()
3794 * .next( function () {
3795 * dialog.getActions().get({actions: 'save'})[0].popPending();
3798 * return MessageDialog.parent.prototype.getActionProcess.call( this, action );
3801 * var windowManager = new OO.ui.WindowManager();
3802 * $( 'body' ).append( windowManager.$element );
3804 * var dialog = new MessageDialog();
3805 * windowManager.addWindows( [ dialog ] );
3806 * windowManager.openWindow( dialog );
3812 * @param {Object} [config] Configuration options
3813 * @cfg {jQuery} [$pending] Element to mark as pending, defaults to this.$element
3815 OO
.ui
.mixin
.PendingElement
= function OoUiMixinPendingElement( config
) {
3816 // Configuration initialization
3817 config
= config
|| {};
3821 this.$pending
= null;
3824 this.setPendingElement( config
.$pending
|| this.$element
);
3829 OO
.initClass( OO
.ui
.mixin
.PendingElement
);
3834 * Set the pending element (and clean up any existing one).
3836 * @param {jQuery} $pending The element to set to pending.
3838 OO
.ui
.mixin
.PendingElement
.prototype.setPendingElement = function ( $pending
) {
3839 if ( this.$pending
) {
3840 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3843 this.$pending
= $pending
;
3844 if ( this.pending
> 0 ) {
3845 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3850 * Check if an element is pending.
3852 * @return {boolean} Element is pending
3854 OO
.ui
.mixin
.PendingElement
.prototype.isPending = function () {
3855 return !!this.pending
;
3859 * Increase the pending counter. The pending state will remain active until the counter is zero
3860 * (i.e., the number of calls to #pushPending and #popPending is the same).
3864 OO
.ui
.mixin
.PendingElement
.prototype.pushPending = function () {
3865 if ( this.pending
=== 0 ) {
3866 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3867 this.updateThemeClasses();
3875 * Decrease the pending counter. The pending state will remain active until the counter is zero
3876 * (i.e., the number of calls to #pushPending and #popPending is the same).
3880 OO
.ui
.mixin
.PendingElement
.prototype.popPending = function () {
3881 if ( this.pending
=== 1 ) {
3882 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3883 this.updateThemeClasses();
3885 this.pending
= Math
.max( 0, this.pending
- 1 );
3891 * Element that can be automatically clipped to visible boundaries.
3893 * Whenever the element's natural height changes, you have to call
3894 * {@link OO.ui.mixin.ClippableElement#clip} to make sure it's still
3895 * clipping correctly.
3897 * The dimensions of #$clippableContainer will be compared to the boundaries of the
3898 * nearest scrollable container. If #$clippableContainer is too tall and/or too wide,
3899 * then #$clippable will be given a fixed reduced height and/or width and will be made
3900 * scrollable. By default, #$clippable and #$clippableContainer are the same element,
3901 * but you can build a static footer by setting #$clippableContainer to an element that contains
3902 * #$clippable and the footer.
3908 * @param {Object} [config] Configuration options
3909 * @cfg {jQuery} [$clippable] Node to clip, assigned to #$clippable, omit to use #$element
3910 * @cfg {jQuery} [$clippableContainer] Node to keep visible, assigned to #$clippableContainer,
3911 * omit to use #$clippable
3913 OO
.ui
.mixin
.ClippableElement
= function OoUiMixinClippableElement( config
) {
3914 // Configuration initialization
3915 config
= config
|| {};
3918 this.$clippable
= null;
3919 this.$clippableContainer
= null;
3920 this.clipping
= false;
3921 this.clippedHorizontally
= false;
3922 this.clippedVertically
= false;
3923 this.$clippableScrollableContainer
= null;
3924 this.$clippableScroller
= null;
3925 this.$clippableWindow
= null;
3926 this.idealWidth
= null;
3927 this.idealHeight
= null;
3928 this.onClippableScrollHandler
= this.clip
.bind( this );
3929 this.onClippableWindowResizeHandler
= this.clip
.bind( this );
3932 if ( config
.$clippableContainer
) {
3933 this.setClippableContainer( config
.$clippableContainer
);
3935 this.setClippableElement( config
.$clippable
|| this.$element
);
3941 * Set clippable element.
3943 * If an element is already set, it will be cleaned up before setting up the new element.
3945 * @param {jQuery} $clippable Element to make clippable
3947 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableElement = function ( $clippable
) {
3948 if ( this.$clippable
) {
3949 this.$clippable
.removeClass( 'oo-ui-clippableElement-clippable' );
3950 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
3951 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
3954 this.$clippable
= $clippable
.addClass( 'oo-ui-clippableElement-clippable' );
3959 * Set clippable container.
3961 * This is the container that will be measured when deciding whether to clip. When clipping,
3962 * #$clippable will be resized in order to keep the clippable container fully visible.
3964 * If the clippable container is unset, #$clippable will be used.
3966 * @param {jQuery|null} $clippableContainer Container to keep visible, or null to unset
3968 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableContainer = function ( $clippableContainer
) {
3969 this.$clippableContainer
= $clippableContainer
;
3970 if ( this.$clippable
) {
3978 * Do not turn clipping on until after the element is attached to the DOM and visible.
3980 * @param {boolean} [clipping] Enable clipping, omit to toggle
3983 OO
.ui
.mixin
.ClippableElement
.prototype.toggleClipping = function ( clipping
) {
3984 clipping
= clipping
=== undefined ? !this.clipping
: !!clipping
;
3986 if ( this.clipping
!== clipping
) {
3987 this.clipping
= clipping
;
3989 this.$clippableScrollableContainer
= $( this.getClosestScrollableElementContainer() );
3990 // If the clippable container is the root, we have to listen to scroll events and check
3991 // jQuery.scrollTop on the window because of browser inconsistencies
3992 this.$clippableScroller
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
3993 $( OO
.ui
.Element
.static.getWindow( this.$clippableScrollableContainer
) ) :
3994 this.$clippableScrollableContainer
;
3995 this.$clippableScroller
.on( 'scroll', this.onClippableScrollHandler
);
3996 this.$clippableWindow
= $( this.getElementWindow() )
3997 .on( 'resize', this.onClippableWindowResizeHandler
);
3998 // Initial clip after visible
4001 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
4002 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4004 this.$clippableScrollableContainer
= null;
4005 this.$clippableScroller
.off( 'scroll', this.onClippableScrollHandler
);
4006 this.$clippableScroller
= null;
4007 this.$clippableWindow
.off( 'resize', this.onClippableWindowResizeHandler
);
4008 this.$clippableWindow
= null;
4016 * Check if the element will be clipped to fit the visible area of the nearest scrollable container.
4018 * @return {boolean} Element will be clipped to the visible area
4020 OO
.ui
.mixin
.ClippableElement
.prototype.isClipping = function () {
4021 return this.clipping
;
4025 * Check if the bottom or right of the element is being clipped by the nearest scrollable container.
4027 * @return {boolean} Part of the element is being clipped
4029 OO
.ui
.mixin
.ClippableElement
.prototype.isClipped = function () {
4030 return this.clippedHorizontally
|| this.clippedVertically
;
4034 * Check if the right of the element is being clipped by the nearest scrollable container.
4036 * @return {boolean} Part of the element is being clipped
4038 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedHorizontally = function () {
4039 return this.clippedHorizontally
;
4043 * Check if the bottom of the element is being clipped by the nearest scrollable container.
4045 * @return {boolean} Part of the element is being clipped
4047 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedVertically = function () {
4048 return this.clippedVertically
;
4052 * Set the ideal size. These are the dimensions the element will have when it's not being clipped.
4054 * @param {number|string} [width] Width as a number of pixels or CSS string with unit suffix
4055 * @param {number|string} [height] Height as a number of pixels or CSS string with unit suffix
4057 OO
.ui
.mixin
.ClippableElement
.prototype.setIdealSize = function ( width
, height
) {
4058 this.idealWidth
= width
;
4059 this.idealHeight
= height
;
4061 if ( !this.clipping
) {
4062 // Update dimensions
4063 this.$clippable
.css( { width
: width
, height
: height
} );
4065 // While clipping, idealWidth and idealHeight are not considered
4069 * Clip element to visible boundaries and allow scrolling when needed. Call this method when
4070 * the element's natural height changes.
4072 * Element will be clipped the bottom or right of the element is within 10px of the edge of, or
4073 * overlapped by, the visible area of the nearest scrollable container.
4077 OO
.ui
.mixin
.ClippableElement
.prototype.clip = function () {
4078 var $container
, extraHeight
, extraWidth
, ccOffset
,
4079 $scrollableContainer
, scOffset
, scHeight
, scWidth
,
4080 ccWidth
, scrollerIsWindow
, scrollTop
, scrollLeft
,
4081 desiredWidth
, desiredHeight
, allotedWidth
, allotedHeight
,
4082 naturalWidth
, naturalHeight
, clipWidth
, clipHeight
,
4083 buffer
= 7; // Chosen by fair dice roll
4085 if ( !this.clipping
) {
4086 // this.$clippableScrollableContainer and this.$clippableWindow are null, so the below will fail
4090 $container
= this.$clippableContainer
|| this.$clippable
;
4091 extraHeight
= $container
.outerHeight() - this.$clippable
.outerHeight();
4092 extraWidth
= $container
.outerWidth() - this.$clippable
.outerWidth();
4093 ccOffset
= $container
.offset();
4094 $scrollableContainer
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4095 this.$clippableWindow
: this.$clippableScrollableContainer
;
4096 scOffset
= $scrollableContainer
.offset() || { top
: 0, left
: 0 };
4097 scHeight
= $scrollableContainer
.innerHeight() - buffer
;
4098 scWidth
= $scrollableContainer
.innerWidth() - buffer
;
4099 ccWidth
= $container
.outerWidth() + buffer
;
4100 scrollerIsWindow
= this.$clippableScroller
[ 0 ] === this.$clippableWindow
[ 0 ];
4101 scrollTop
= scrollerIsWindow
? this.$clippableScroller
.scrollTop() : 0;
4102 scrollLeft
= scrollerIsWindow
? this.$clippableScroller
.scrollLeft() : 0;
4103 desiredWidth
= ccOffset
.left
< 0 ?
4104 ccWidth
+ ccOffset
.left
:
4105 ( scOffset
.left
+ scrollLeft
+ scWidth
) - ccOffset
.left
;
4106 desiredHeight
= ( scOffset
.top
+ scrollTop
+ scHeight
) - ccOffset
.top
;
4107 // It should never be desirable to exceed the dimensions of the browser viewport... right?
4108 desiredWidth
= Math
.min( desiredWidth
, document
.documentElement
.clientWidth
);
4109 desiredHeight
= Math
.min( desiredHeight
, document
.documentElement
.clientHeight
);
4110 allotedWidth
= Math
.ceil( desiredWidth
- extraWidth
);
4111 allotedHeight
= Math
.ceil( desiredHeight
- extraHeight
);
4112 naturalWidth
= this.$clippable
.prop( 'scrollWidth' );
4113 naturalHeight
= this.$clippable
.prop( 'scrollHeight' );
4114 clipWidth
= allotedWidth
< naturalWidth
;
4115 clipHeight
= allotedHeight
< naturalHeight
;
4118 this.$clippable
.css( { overflowX
: 'scroll', width
: Math
.max( 0, allotedWidth
) } );
4120 this.$clippable
.css( { width
: this.idealWidth
? this.idealWidth
- extraWidth
: '', overflowX
: '' } );
4123 this.$clippable
.css( { overflowY
: 'scroll', height
: Math
.max( 0, allotedHeight
) } );
4125 this.$clippable
.css( { height
: this.idealHeight
? this.idealHeight
- extraHeight
: '', overflowY
: '' } );
4128 // If we stopped clipping in at least one of the dimensions
4129 if ( ( this.clippedHorizontally
&& !clipWidth
) || ( this.clippedVertically
&& !clipHeight
) ) {
4130 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4133 this.clippedHorizontally
= clipWidth
;
4134 this.clippedVertically
= clipHeight
;
4140 * PopupWidget is a container for content. The popup is overlaid and positioned absolutely.
4141 * By default, each popup has an anchor that points toward its origin.
4142 * Please see the [OOjs UI documentation on Mediawiki] [1] for more information and examples.
4145 * // A popup widget.
4146 * var popup = new OO.ui.PopupWidget( {
4147 * $content: $( '<p>Hi there!</p>' ),
4152 * $( 'body' ).append( popup.$element );
4153 * // To display the popup, toggle the visibility to 'true'.
4154 * popup.toggle( true );
4156 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups
4159 * @extends OO.ui.Widget
4160 * @mixins OO.ui.mixin.LabelElement
4161 * @mixins OO.ui.mixin.ClippableElement
4164 * @param {Object} [config] Configuration options
4165 * @cfg {number} [width=320] Width of popup in pixels
4166 * @cfg {number} [height] Height of popup in pixels. Omit to use the automatic height.
4167 * @cfg {boolean} [anchor=true] Show anchor pointing to origin of popup
4168 * @cfg {string} [align='center'] Alignment of the popup: `center`, `force-left`, `force-right`, `backwards` or `forwards`.
4169 * If the popup is forced-left the popup body is leaning towards the left. For force-right alignment, the body of the
4170 * popup is leaning towards the right of the screen.
4171 * Using 'backwards' is a logical direction which will result in the popup leaning towards the beginning of the sentence
4172 * in the given language, which means it will flip to the correct positioning in right-to-left languages.
4173 * Using 'forward' will also result in a logical alignment where the body of the popup leans towards the end of the
4174 * sentence in the given language.
4175 * @cfg {jQuery} [$container] Constrain the popup to the boundaries of the specified container.
4176 * See the [OOjs UI docs on MediaWiki][3] for an example.
4177 * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#containerExample
4178 * @cfg {number} [containerPadding=10] Padding between the popup and its container, specified as a number of pixels.
4179 * @cfg {jQuery} [$content] Content to append to the popup's body
4180 * @cfg {jQuery} [$footer] Content to append to the popup's footer
4181 * @cfg {boolean} [autoClose=false] Automatically close the popup when it loses focus.
4182 * @cfg {jQuery} [$autoCloseIgnore] Elements that will not close the popup when clicked.
4183 * This config option is only relevant if #autoClose is set to `true`. See the [OOjs UI docs on MediaWiki][2]
4185 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#autocloseExample
4186 * @cfg {boolean} [head=false] Show a popup header that contains a #label (if specified) and close
4188 * @cfg {boolean} [padded=false] Add padding to the popup's body
4190 OO
.ui
.PopupWidget
= function OoUiPopupWidget( config
) {
4191 // Configuration initialization
4192 config
= config
|| {};
4194 // Parent constructor
4195 OO
.ui
.PopupWidget
.parent
.call( this, config
);
4197 // Properties (must be set before ClippableElement constructor call)
4198 this.$body
= $( '<div>' );
4199 this.$popup
= $( '<div>' );
4201 // Mixin constructors
4202 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4203 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, {
4204 $clippable
: this.$body
,
4205 $clippableContainer
: this.$popup
4209 this.$anchor
= $( '<div>' );
4210 // If undefined, will be computed lazily in updateDimensions()
4211 this.$container
= config
.$container
;
4212 this.containerPadding
= config
.containerPadding
!== undefined ? config
.containerPadding
: 10;
4213 this.autoClose
= !!config
.autoClose
;
4214 this.$autoCloseIgnore
= config
.$autoCloseIgnore
;
4215 this.transitionTimeout
= null;
4217 this.width
= config
.width
!== undefined ? config
.width
: 320;
4218 this.height
= config
.height
!== undefined ? config
.height
: null;
4219 this.setAlignment( config
.align
);
4220 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
4221 this.onDocumentKeyDownHandler
= this.onDocumentKeyDown
.bind( this );
4224 this.toggleAnchor( config
.anchor
=== undefined || config
.anchor
);
4225 this.$body
.addClass( 'oo-ui-popupWidget-body' );
4226 this.$anchor
.addClass( 'oo-ui-popupWidget-anchor' );
4228 .addClass( 'oo-ui-popupWidget-popup' )
4229 .append( this.$body
);
4231 .addClass( 'oo-ui-popupWidget' )
4232 .append( this.$popup
, this.$anchor
);
4233 // Move content, which was added to #$element by OO.ui.Widget, to the body
4234 // FIXME This is gross, we should use '$body' or something for the config
4235 if ( config
.$content
instanceof jQuery
) {
4236 this.$body
.append( config
.$content
);
4239 if ( config
.padded
) {
4240 this.$body
.addClass( 'oo-ui-popupWidget-body-padded' );
4243 if ( config
.head
) {
4244 this.closeButton
= new OO
.ui
.ButtonWidget( { framed
: false, icon
: 'close' } );
4245 this.closeButton
.connect( this, { click
: 'onCloseButtonClick' } );
4246 this.$head
= $( '<div>' )
4247 .addClass( 'oo-ui-popupWidget-head' )
4248 .append( this.$label
, this.closeButton
.$element
);
4249 this.$popup
.prepend( this.$head
);
4252 if ( config
.$footer
) {
4253 this.$footer
= $( '<div>' )
4254 .addClass( 'oo-ui-popupWidget-footer' )
4255 .append( config
.$footer
);
4256 this.$popup
.append( this.$footer
);
4259 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
4260 // that reference properties not initialized at that time of parent class construction
4261 // TODO: Find a better way to handle post-constructor setup
4262 this.visible
= false;
4263 this.$element
.addClass( 'oo-ui-element-hidden' );
4268 OO
.inheritClass( OO
.ui
.PopupWidget
, OO
.ui
.Widget
);
4269 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.LabelElement
);
4270 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.ClippableElement
);
4275 * Handles mouse down events.
4278 * @param {MouseEvent} e Mouse down event
4280 OO
.ui
.PopupWidget
.prototype.onMouseDown = function ( e
) {
4283 !$.contains( this.$element
[ 0 ], e
.target
) &&
4284 ( !this.$autoCloseIgnore
|| !this.$autoCloseIgnore
.has( e
.target
).length
)
4286 this.toggle( false );
4291 * Bind mouse down listener.
4295 OO
.ui
.PopupWidget
.prototype.bindMouseDownListener = function () {
4296 // Capture clicks outside popup
4297 this.getElementWindow().addEventListener( 'mousedown', this.onMouseDownHandler
, true );
4301 * Handles close button click events.
4305 OO
.ui
.PopupWidget
.prototype.onCloseButtonClick = function () {
4306 if ( this.isVisible() ) {
4307 this.toggle( false );
4312 * Unbind mouse down listener.
4316 OO
.ui
.PopupWidget
.prototype.unbindMouseDownListener = function () {
4317 this.getElementWindow().removeEventListener( 'mousedown', this.onMouseDownHandler
, true );
4321 * Handles key down events.
4324 * @param {KeyboardEvent} e Key down event
4326 OO
.ui
.PopupWidget
.prototype.onDocumentKeyDown = function ( e
) {
4328 e
.which
=== OO
.ui
.Keys
.ESCAPE
&&
4331 this.toggle( false );
4333 e
.stopPropagation();
4338 * Bind key down listener.
4342 OO
.ui
.PopupWidget
.prototype.bindKeyDownListener = function () {
4343 this.getElementWindow().addEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4347 * Unbind key down listener.
4351 OO
.ui
.PopupWidget
.prototype.unbindKeyDownListener = function () {
4352 this.getElementWindow().removeEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4356 * Show, hide, or toggle the visibility of the anchor.
4358 * @param {boolean} [show] Show anchor, omit to toggle
4360 OO
.ui
.PopupWidget
.prototype.toggleAnchor = function ( show
) {
4361 show
= show
=== undefined ? !this.anchored
: !!show
;
4363 if ( this.anchored
!== show
) {
4365 this.$element
.addClass( 'oo-ui-popupWidget-anchored' );
4367 this.$element
.removeClass( 'oo-ui-popupWidget-anchored' );
4369 this.anchored
= show
;
4374 * Check if the anchor is visible.
4376 * @return {boolean} Anchor is visible
4378 OO
.ui
.PopupWidget
.prototype.hasAnchor = function () {
4385 OO
.ui
.PopupWidget
.prototype.toggle = function ( show
) {
4387 show
= show
=== undefined ? !this.isVisible() : !!show
;
4389 change
= show
!== this.isVisible();
4392 OO
.ui
.PopupWidget
.parent
.prototype.toggle
.call( this, show
);
4396 if ( this.autoClose
) {
4397 this.bindMouseDownListener();
4398 this.bindKeyDownListener();
4400 this.updateDimensions();
4401 this.toggleClipping( true );
4403 this.toggleClipping( false );
4404 if ( this.autoClose
) {
4405 this.unbindMouseDownListener();
4406 this.unbindKeyDownListener();
4415 * Set the size of the popup.
4417 * Changing the size may also change the popup's position depending on the alignment.
4419 * @param {number} width Width in pixels
4420 * @param {number} height Height in pixels
4421 * @param {boolean} [transition=false] Use a smooth transition
4424 OO
.ui
.PopupWidget
.prototype.setSize = function ( width
, height
, transition
) {
4426 this.height
= height
!== undefined ? height
: null;
4427 if ( this.isVisible() ) {
4428 this.updateDimensions( transition
);
4433 * Update the size and position.
4435 * Only use this to keep the popup properly anchored. Use #setSize to change the size, and this will
4436 * be called automatically.
4438 * @param {boolean} [transition=false] Use a smooth transition
4441 OO
.ui
.PopupWidget
.prototype.updateDimensions = function ( transition
) {
4442 var popupOffset
, originOffset
, containerLeft
, containerWidth
, containerRight
,
4443 popupLeft
, popupRight
, overlapLeft
, overlapRight
, anchorWidth
,
4447 if ( !this.$container
) {
4448 // Lazy-initialize $container if not specified in constructor
4449 this.$container
= $( this.getClosestScrollableElementContainer() );
4452 // Set height and width before measuring things, since it might cause our measurements
4453 // to change (e.g. due to scrollbars appearing or disappearing)
4456 height
: this.height
!== null ? this.height
: 'auto'
4459 // If we are in RTL, we need to flip the alignment, unless it is center
4460 if ( align
=== 'forwards' || align
=== 'backwards' ) {
4461 if ( this.$container
.css( 'direction' ) === 'rtl' ) {
4462 align
= ( { forwards
: 'force-left', backwards
: 'force-right' } )[ this.align
];
4464 align
= ( { forwards
: 'force-right', backwards
: 'force-left' } )[ this.align
];
4469 // Compute initial popupOffset based on alignment
4470 popupOffset
= this.width
* ( { 'force-left': -1, center
: -0.5, 'force-right': 0 } )[ align
];
4472 // Figure out if this will cause the popup to go beyond the edge of the container
4473 originOffset
= this.$element
.offset().left
;
4474 containerLeft
= this.$container
.offset().left
;
4475 containerWidth
= this.$container
.innerWidth();
4476 containerRight
= containerLeft
+ containerWidth
;
4477 popupLeft
= popupOffset
- this.containerPadding
;
4478 popupRight
= popupOffset
+ this.containerPadding
+ this.width
+ this.containerPadding
;
4479 overlapLeft
= ( originOffset
+ popupLeft
) - containerLeft
;
4480 overlapRight
= containerRight
- ( originOffset
+ popupRight
);
4482 // Adjust offset to make the popup not go beyond the edge, if needed
4483 if ( overlapRight
< 0 ) {
4484 popupOffset
+= overlapRight
;
4485 } else if ( overlapLeft
< 0 ) {
4486 popupOffset
-= overlapLeft
;
4489 // Adjust offset to avoid anchor being rendered too close to the edge
4490 // $anchor.width() doesn't work with the pure CSS anchor (returns 0)
4491 // TODO: Find a measurement that works for CSS anchors and image anchors
4492 anchorWidth
= this.$anchor
[ 0 ].scrollWidth
* 2;
4493 if ( popupOffset
+ this.width
< anchorWidth
) {
4494 popupOffset
= anchorWidth
- this.width
;
4495 } else if ( -popupOffset
< anchorWidth
) {
4496 popupOffset
= -anchorWidth
;
4499 // Prevent transition from being interrupted
4500 clearTimeout( this.transitionTimeout
);
4502 // Enable transition
4503 this.$element
.addClass( 'oo-ui-popupWidget-transitioning' );
4506 // Position body relative to anchor
4507 this.$popup
.css( 'margin-left', popupOffset
);
4510 // Prevent transitioning after transition is complete
4511 this.transitionTimeout
= setTimeout( function () {
4512 widget
.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
4515 // Prevent transitioning immediately
4516 this.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
4519 // Reevaluate clipping state since we've relocated and resized the popup
4526 * Set popup alignment
4528 * @param {string} align Alignment of the popup, `center`, `force-left`, `force-right`,
4529 * `backwards` or `forwards`.
4531 OO
.ui
.PopupWidget
.prototype.setAlignment = function ( align
) {
4532 // Validate alignment and transform deprecated values
4533 if ( [ 'left', 'right', 'force-left', 'force-right', 'backwards', 'forwards', 'center' ].indexOf( align
) > -1 ) {
4534 this.align
= { left
: 'force-right', right
: 'force-left' }[ align
] || align
;
4536 this.align
= 'center';
4541 * Get popup alignment
4543 * @return {string} align Alignment of the popup, `center`, `force-left`, `force-right`,
4544 * `backwards` or `forwards`.
4546 OO
.ui
.PopupWidget
.prototype.getAlignment = function () {
4551 * PopupElement is mixed into other classes to generate a {@link OO.ui.PopupWidget popup widget}.
4552 * A popup is a container for content. It is overlaid and positioned absolutely. By default, each
4553 * popup has an anchor, which is an arrow-like protrusion that points toward the popup’s origin.
4554 * See {@link OO.ui.PopupWidget PopupWidget} for an example.
4560 * @param {Object} [config] Configuration options
4561 * @cfg {Object} [popup] Configuration to pass to popup
4562 * @cfg {boolean} [popup.autoClose=true] Popup auto-closes when it loses focus
4564 OO
.ui
.mixin
.PopupElement
= function OoUiMixinPopupElement( config
) {
4565 // Configuration initialization
4566 config
= config
|| {};
4569 this.popup
= new OO
.ui
.PopupWidget( $.extend(
4570 { autoClose
: true },
4572 { $autoCloseIgnore
: this.$element
}
4581 * @return {OO.ui.PopupWidget} Popup widget
4583 OO
.ui
.mixin
.PopupElement
.prototype.getPopup = function () {
4588 * PopupButtonWidgets toggle the visibility of a contained {@link OO.ui.PopupWidget PopupWidget},
4589 * which is used to display additional information or options.
4592 * // Example of a popup button.
4593 * var popupButton = new OO.ui.PopupButtonWidget( {
4594 * label: 'Popup button with options',
4597 * $content: $( '<p>Additional options here.</p>' ),
4599 * align: 'force-left'
4602 * // Append the button to the DOM.
4603 * $( 'body' ).append( popupButton.$element );
4606 * @extends OO.ui.ButtonWidget
4607 * @mixins OO.ui.mixin.PopupElement
4610 * @param {Object} [config] Configuration options
4612 OO
.ui
.PopupButtonWidget
= function OoUiPopupButtonWidget( config
) {
4613 // Parent constructor
4614 OO
.ui
.PopupButtonWidget
.parent
.call( this, config
);
4616 // Mixin constructors
4617 OO
.ui
.mixin
.PopupElement
.call( this, config
);
4620 this.connect( this, { click
: 'onAction' } );
4624 .addClass( 'oo-ui-popupButtonWidget' )
4625 .attr( 'aria-haspopup', 'true' )
4626 .append( this.popup
.$element
);
4631 OO
.inheritClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.ButtonWidget
);
4632 OO
.mixinClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.mixin
.PopupElement
);
4637 * Handle the button action being triggered.
4641 OO
.ui
.PopupButtonWidget
.prototype.onAction = function () {
4642 this.popup
.toggle();
4646 * Mixin for OO.ui.Widget subclasses to provide OO.ui.mixin.GroupElement.
4648 * Use together with OO.ui.mixin.ItemWidget to make disabled state inheritable.
4653 * @extends OO.ui.mixin.GroupElement
4656 * @param {Object} [config] Configuration options
4658 OO
.ui
.mixin
.GroupWidget
= function OoUiMixinGroupWidget( config
) {
4659 // Parent constructor
4660 OO
.ui
.mixin
.GroupWidget
.parent
.call( this, config
);
4665 OO
.inheritClass( OO
.ui
.mixin
.GroupWidget
, OO
.ui
.mixin
.GroupElement
);
4670 * Set the disabled state of the widget.
4672 * This will also update the disabled state of child widgets.
4674 * @param {boolean} disabled Disable widget
4677 OO
.ui
.mixin
.GroupWidget
.prototype.setDisabled = function ( disabled
) {
4681 // Note: Calling #setDisabled this way assumes this is mixed into an OO.ui.Widget
4682 OO
.ui
.Widget
.prototype.setDisabled
.call( this, disabled
);
4684 // During construction, #setDisabled is called before the OO.ui.mixin.GroupElement constructor
4686 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
4687 this.items
[ i
].updateDisabled();
4695 * Mixin for widgets used as items in widgets that mix in OO.ui.mixin.GroupWidget.
4697 * Item widgets have a reference to a OO.ui.mixin.GroupWidget while they are attached to the group. This
4698 * allows bidirectional communication.
4700 * Use together with OO.ui.mixin.GroupWidget to make disabled state inheritable.
4708 OO
.ui
.mixin
.ItemWidget
= function OoUiMixinItemWidget() {
4715 * Check if widget is disabled.
4717 * Checks parent if present, making disabled state inheritable.
4719 * @return {boolean} Widget is disabled
4721 OO
.ui
.mixin
.ItemWidget
.prototype.isDisabled = function () {
4722 return this.disabled
||
4723 ( this.elementGroup
instanceof OO
.ui
.Widget
&& this.elementGroup
.isDisabled() );
4727 * Set group element is in.
4729 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
4732 OO
.ui
.mixin
.ItemWidget
.prototype.setElementGroup = function ( group
) {
4734 // Note: Calling #setElementGroup this way assumes this is mixed into an OO.ui.Element
4735 OO
.ui
.Element
.prototype.setElementGroup
.call( this, group
);
4737 // Initialize item disabled states
4738 this.updateDisabled();
4744 * OptionWidgets are special elements that can be selected and configured with data. The
4745 * data is often unique for each option, but it does not have to be. OptionWidgets are used
4746 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
4747 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
4749 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
4752 * @extends OO.ui.Widget
4753 * @mixins OO.ui.mixin.LabelElement
4754 * @mixins OO.ui.mixin.FlaggedElement
4757 * @param {Object} [config] Configuration options
4759 OO
.ui
.OptionWidget
= function OoUiOptionWidget( config
) {
4760 // Configuration initialization
4761 config
= config
|| {};
4763 // Parent constructor
4764 OO
.ui
.OptionWidget
.parent
.call( this, config
);
4766 // Mixin constructors
4767 OO
.ui
.mixin
.ItemWidget
.call( this );
4768 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4769 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
4772 this.selected
= false;
4773 this.highlighted
= false;
4774 this.pressed
= false;
4778 .data( 'oo-ui-optionWidget', this )
4779 .attr( 'role', 'option' )
4780 .attr( 'aria-selected', 'false' )
4781 .addClass( 'oo-ui-optionWidget' )
4782 .append( this.$label
);
4787 OO
.inheritClass( OO
.ui
.OptionWidget
, OO
.ui
.Widget
);
4788 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.ItemWidget
);
4789 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.LabelElement
);
4790 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.FlaggedElement
);
4792 /* Static Properties */
4794 OO
.ui
.OptionWidget
.static.selectable
= true;
4796 OO
.ui
.OptionWidget
.static.highlightable
= true;
4798 OO
.ui
.OptionWidget
.static.pressable
= true;
4800 OO
.ui
.OptionWidget
.static.scrollIntoViewOnSelect
= false;
4805 * Check if the option can be selected.
4807 * @return {boolean} Item is selectable
4809 OO
.ui
.OptionWidget
.prototype.isSelectable = function () {
4810 return this.constructor.static.selectable
&& !this.isDisabled() && this.isVisible();
4814 * Check if the option can be highlighted. A highlight indicates that the option
4815 * may be selected when a user presses enter or clicks. Disabled items cannot
4818 * @return {boolean} Item is highlightable
4820 OO
.ui
.OptionWidget
.prototype.isHighlightable = function () {
4821 return this.constructor.static.highlightable
&& !this.isDisabled() && this.isVisible();
4825 * Check if the option can be pressed. The pressed state occurs when a user mouses
4826 * down on an item, but has not yet let go of the mouse.
4828 * @return {boolean} Item is pressable
4830 OO
.ui
.OptionWidget
.prototype.isPressable = function () {
4831 return this.constructor.static.pressable
&& !this.isDisabled() && this.isVisible();
4835 * Check if the option is selected.
4837 * @return {boolean} Item is selected
4839 OO
.ui
.OptionWidget
.prototype.isSelected = function () {
4840 return this.selected
;
4844 * Check if the option is highlighted. A highlight indicates that the
4845 * item may be selected when a user presses enter or clicks.
4847 * @return {boolean} Item is highlighted
4849 OO
.ui
.OptionWidget
.prototype.isHighlighted = function () {
4850 return this.highlighted
;
4854 * Check if the option is pressed. The pressed state occurs when a user mouses
4855 * down on an item, but has not yet let go of the mouse. The item may appear
4856 * selected, but it will not be selected until the user releases the mouse.
4858 * @return {boolean} Item is pressed
4860 OO
.ui
.OptionWidget
.prototype.isPressed = function () {
4861 return this.pressed
;
4865 * Set the option’s selected state. In general, all modifications to the selection
4866 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
4867 * method instead of this method.
4869 * @param {boolean} [state=false] Select option
4872 OO
.ui
.OptionWidget
.prototype.setSelected = function ( state
) {
4873 if ( this.constructor.static.selectable
) {
4874 this.selected
= !!state
;
4876 .toggleClass( 'oo-ui-optionWidget-selected', state
)
4877 .attr( 'aria-selected', state
.toString() );
4878 if ( state
&& this.constructor.static.scrollIntoViewOnSelect
) {
4879 this.scrollElementIntoView();
4881 this.updateThemeClasses();
4887 * Set the option’s highlighted state. In general, all programmatic
4888 * modifications to the highlight should be handled by the
4889 * SelectWidget’s {@link OO.ui.SelectWidget#highlightItem highlightItem( [item] )}
4890 * method instead of this method.
4892 * @param {boolean} [state=false] Highlight option
4895 OO
.ui
.OptionWidget
.prototype.setHighlighted = function ( state
) {
4896 if ( this.constructor.static.highlightable
) {
4897 this.highlighted
= !!state
;
4898 this.$element
.toggleClass( 'oo-ui-optionWidget-highlighted', state
);
4899 this.updateThemeClasses();
4905 * Set the option’s pressed state. In general, all
4906 * programmatic modifications to the pressed state should be handled by the
4907 * SelectWidget’s {@link OO.ui.SelectWidget#pressItem pressItem( [item] )}
4908 * method instead of this method.
4910 * @param {boolean} [state=false] Press option
4913 OO
.ui
.OptionWidget
.prototype.setPressed = function ( state
) {
4914 if ( this.constructor.static.pressable
) {
4915 this.pressed
= !!state
;
4916 this.$element
.toggleClass( 'oo-ui-optionWidget-pressed', state
);
4917 this.updateThemeClasses();
4923 * A SelectWidget is of a generic selection of options. The OOjs UI library contains several types of
4924 * select widgets, including {@link OO.ui.ButtonSelectWidget button selects},
4925 * {@link OO.ui.RadioSelectWidget radio selects}, and {@link OO.ui.MenuSelectWidget
4928 * This class should be used together with OO.ui.OptionWidget or OO.ui.DecoratedOptionWidget. For more
4929 * information, please see the [OOjs UI documentation on MediaWiki][1].
4932 * // Example of a select widget with three options
4933 * var select = new OO.ui.SelectWidget( {
4935 * new OO.ui.OptionWidget( {
4937 * label: 'Option One',
4939 * new OO.ui.OptionWidget( {
4941 * label: 'Option Two',
4943 * new OO.ui.OptionWidget( {
4945 * label: 'Option Three',
4949 * $( 'body' ).append( select.$element );
4951 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
4955 * @extends OO.ui.Widget
4956 * @mixins OO.ui.mixin.GroupWidget
4959 * @param {Object} [config] Configuration options
4960 * @cfg {OO.ui.OptionWidget[]} [items] An array of options to add to the select.
4961 * Options are created with {@link OO.ui.OptionWidget OptionWidget} classes. See
4962 * the [OOjs UI documentation on MediaWiki] [2] for examples.
4963 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
4965 OO
.ui
.SelectWidget
= function OoUiSelectWidget( config
) {
4966 // Configuration initialization
4967 config
= config
|| {};
4969 // Parent constructor
4970 OO
.ui
.SelectWidget
.parent
.call( this, config
);
4972 // Mixin constructors
4973 OO
.ui
.mixin
.GroupWidget
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
4976 this.pressed
= false;
4977 this.selecting
= null;
4978 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
4979 this.onMouseMoveHandler
= this.onMouseMove
.bind( this );
4980 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
4981 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
4982 this.keyPressBuffer
= '';
4983 this.keyPressBufferTimer
= null;
4984 this.blockMouseOverEvents
= 0;
4987 this.connect( this, {
4991 mousedown
: this.onMouseDown
.bind( this ),
4992 mouseover
: this.onMouseOver
.bind( this ),
4993 mouseleave
: this.onMouseLeave
.bind( this )
4998 .addClass( 'oo-ui-selectWidget oo-ui-selectWidget-depressed' )
4999 .attr( 'role', 'listbox' );
5000 if ( Array
.isArray( config
.items
) ) {
5001 this.addItems( config
.items
);
5007 OO
.inheritClass( OO
.ui
.SelectWidget
, OO
.ui
.Widget
);
5009 // Need to mixin base class as well
5010 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupElement
);
5011 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupWidget
);
5014 OO
.ui
.SelectWidget
.static.passAllFilter = function () {
5023 * A `highlight` event is emitted when the highlight is changed with the #highlightItem method.
5025 * @param {OO.ui.OptionWidget|null} item Highlighted item
5031 * A `press` event is emitted when the #pressItem method is used to programmatically modify the
5032 * pressed state of an option.
5034 * @param {OO.ui.OptionWidget|null} item Pressed item
5040 * A `select` event is emitted when the selection is modified programmatically with the #selectItem method.
5042 * @param {OO.ui.OptionWidget|null} item Selected item
5047 * A `choose` event is emitted when an item is chosen with the #chooseItem method.
5048 * @param {OO.ui.OptionWidget} item Chosen item
5054 * An `add` event is emitted when options are added to the select with the #addItems method.
5056 * @param {OO.ui.OptionWidget[]} items Added items
5057 * @param {number} index Index of insertion point
5063 * A `remove` event is emitted when options are removed from the select with the #clearItems
5064 * or #removeItems methods.
5066 * @param {OO.ui.OptionWidget[]} items Removed items
5072 * Handle mouse down events.
5075 * @param {jQuery.Event} e Mouse down event
5077 OO
.ui
.SelectWidget
.prototype.onMouseDown = function ( e
) {
5080 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
5081 this.togglePressed( true );
5082 item
= this.getTargetItem( e
);
5083 if ( item
&& item
.isSelectable() ) {
5084 this.pressItem( item
);
5085 this.selecting
= item
;
5086 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
5087 this.getElementDocument().addEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5094 * Handle mouse up events.
5097 * @param {MouseEvent} e Mouse up event
5099 OO
.ui
.SelectWidget
.prototype.onMouseUp = function ( e
) {
5102 this.togglePressed( false );
5103 if ( !this.selecting
) {
5104 item
= this.getTargetItem( e
);
5105 if ( item
&& item
.isSelectable() ) {
5106 this.selecting
= item
;
5109 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
&& this.selecting
) {
5110 this.pressItem( null );
5111 this.chooseItem( this.selecting
);
5112 this.selecting
= null;
5115 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
5116 this.getElementDocument().removeEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5122 * Handle mouse move events.
5125 * @param {MouseEvent} e Mouse move event
5127 OO
.ui
.SelectWidget
.prototype.onMouseMove = function ( e
) {
5130 if ( !this.isDisabled() && this.pressed
) {
5131 item
= this.getTargetItem( e
);
5132 if ( item
&& item
!== this.selecting
&& item
.isSelectable() ) {
5133 this.pressItem( item
);
5134 this.selecting
= item
;
5140 * Handle mouse over events.
5143 * @param {jQuery.Event} e Mouse over event
5145 OO
.ui
.SelectWidget
.prototype.onMouseOver = function ( e
) {
5147 if ( this.blockMouseOverEvents
) {
5150 if ( !this.isDisabled() ) {
5151 item
= this.getTargetItem( e
);
5152 this.highlightItem( item
&& item
.isHighlightable() ? item
: null );
5158 * Handle mouse leave events.
5161 * @param {jQuery.Event} e Mouse over event
5163 OO
.ui
.SelectWidget
.prototype.onMouseLeave = function () {
5164 if ( !this.isDisabled() ) {
5165 this.highlightItem( null );
5171 * Handle key down events.
5174 * @param {KeyboardEvent} e Key down event
5176 OO
.ui
.SelectWidget
.prototype.onKeyDown = function ( e
) {
5179 currentItem
= this.getHighlightedItem() || this.getSelectedItem();
5181 if ( !this.isDisabled() && this.isVisible() ) {
5182 switch ( e
.keyCode
) {
5183 case OO
.ui
.Keys
.ENTER
:
5184 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5185 // Was only highlighted, now let's select it. No-op if already selected.
5186 this.chooseItem( currentItem
);
5191 case OO
.ui
.Keys
.LEFT
:
5192 this.clearKeyPressBuffer();
5193 nextItem
= this.getRelativeSelectableItem( currentItem
, -1 );
5196 case OO
.ui
.Keys
.DOWN
:
5197 case OO
.ui
.Keys
.RIGHT
:
5198 this.clearKeyPressBuffer();
5199 nextItem
= this.getRelativeSelectableItem( currentItem
, 1 );
5202 case OO
.ui
.Keys
.ESCAPE
:
5203 case OO
.ui
.Keys
.TAB
:
5204 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5205 currentItem
.setHighlighted( false );
5207 this.unbindKeyDownListener();
5208 this.unbindKeyPressListener();
5209 // Don't prevent tabbing away / defocusing
5215 if ( nextItem
.constructor.static.highlightable
) {
5216 this.highlightItem( nextItem
);
5218 this.chooseItem( nextItem
);
5220 this.scrollItemIntoView( nextItem
);
5225 e
.stopPropagation();
5231 * Bind key down listener.
5235 OO
.ui
.SelectWidget
.prototype.bindKeyDownListener = function () {
5236 this.getElementWindow().addEventListener( 'keydown', this.onKeyDownHandler
, true );
5240 * Unbind key down listener.
5244 OO
.ui
.SelectWidget
.prototype.unbindKeyDownListener = function () {
5245 this.getElementWindow().removeEventListener( 'keydown', this.onKeyDownHandler
, true );
5249 * Scroll item into view, preventing spurious mouse highlight actions from happening.
5251 * @param {OO.ui.OptionWidget} item Item to scroll into view
5253 OO
.ui
.SelectWidget
.prototype.scrollItemIntoView = function ( item
) {
5255 // Chromium's Blink engine will generate spurious 'mouseover' events during programmatic scrolling
5256 // and around 100-150 ms after it is finished.
5257 this.blockMouseOverEvents
++;
5258 item
.scrollElementIntoView().done( function () {
5259 setTimeout( function () {
5260 widget
.blockMouseOverEvents
--;
5266 * Clear the key-press buffer
5270 OO
.ui
.SelectWidget
.prototype.clearKeyPressBuffer = function () {
5271 if ( this.keyPressBufferTimer
) {
5272 clearTimeout( this.keyPressBufferTimer
);
5273 this.keyPressBufferTimer
= null;
5275 this.keyPressBuffer
= '';
5279 * Handle key press events.
5282 * @param {KeyboardEvent} e Key press event
5284 OO
.ui
.SelectWidget
.prototype.onKeyPress = function ( e
) {
5285 var c
, filter
, item
;
5287 if ( !e
.charCode
) {
5288 if ( e
.keyCode
=== OO
.ui
.Keys
.BACKSPACE
&& this.keyPressBuffer
!== '' ) {
5289 this.keyPressBuffer
= this.keyPressBuffer
.substr( 0, this.keyPressBuffer
.length
- 1 );
5294 if ( String
.fromCodePoint
) {
5295 c
= String
.fromCodePoint( e
.charCode
);
5297 c
= String
.fromCharCode( e
.charCode
);
5300 if ( this.keyPressBufferTimer
) {
5301 clearTimeout( this.keyPressBufferTimer
);
5303 this.keyPressBufferTimer
= setTimeout( this.clearKeyPressBuffer
.bind( this ), 1500 );
5305 item
= this.getHighlightedItem() || this.getSelectedItem();
5307 if ( this.keyPressBuffer
=== c
) {
5308 // Common (if weird) special case: typing "xxxx" will cycle through all
5309 // the items beginning with "x".
5311 item
= this.getRelativeSelectableItem( item
, 1 );
5314 this.keyPressBuffer
+= c
;
5317 filter
= this.getItemMatcher( this.keyPressBuffer
, false );
5318 if ( !item
|| !filter( item
) ) {
5319 item
= this.getRelativeSelectableItem( item
, 1, filter
);
5322 if ( item
.constructor.static.highlightable
) {
5323 this.highlightItem( item
);
5325 this.chooseItem( item
);
5327 this.scrollItemIntoView( item
);
5331 e
.stopPropagation();
5335 * Get a matcher for the specific string
5338 * @param {string} s String to match against items
5339 * @param {boolean} [exact=false] Only accept exact matches
5340 * @return {Function} function ( OO.ui.OptionItem ) => boolean
5342 OO
.ui
.SelectWidget
.prototype.getItemMatcher = function ( s
, exact
) {
5345 if ( s
.normalize
) {
5348 s
= exact
? s
.trim() : s
.replace( /^\s+/, '' );
5349 re
= '^\\s*' + s
.replace( /([\\{}()|.?*+\-\^$\[\]])/g, '\\$1' ).replace( /\s+/g, '\\s+' );
5353 re
= new RegExp( re
, 'i' );
5354 return function ( item
) {
5355 var l
= item
.getLabel();
5356 if ( typeof l
!== 'string' ) {
5357 l
= item
.$label
.text();
5359 if ( l
.normalize
) {
5362 return re
.test( l
);
5367 * Bind key press listener.
5371 OO
.ui
.SelectWidget
.prototype.bindKeyPressListener = function () {
5372 this.getElementWindow().addEventListener( 'keypress', this.onKeyPressHandler
, true );
5376 * Unbind key down listener.
5378 * If you override this, be sure to call this.clearKeyPressBuffer() from your
5383 OO
.ui
.SelectWidget
.prototype.unbindKeyPressListener = function () {
5384 this.getElementWindow().removeEventListener( 'keypress', this.onKeyPressHandler
, true );
5385 this.clearKeyPressBuffer();
5389 * Visibility change handler
5392 * @param {boolean} visible
5394 OO
.ui
.SelectWidget
.prototype.onToggle = function ( visible
) {
5396 this.clearKeyPressBuffer();
5401 * Get the closest item to a jQuery.Event.
5404 * @param {jQuery.Event} e
5405 * @return {OO.ui.OptionWidget|null} Outline item widget, `null` if none was found
5407 OO
.ui
.SelectWidget
.prototype.getTargetItem = function ( e
) {
5408 return $( e
.target
).closest( '.oo-ui-optionWidget' ).data( 'oo-ui-optionWidget' ) || null;
5412 * Get selected item.
5414 * @return {OO.ui.OptionWidget|null} Selected item, `null` if no item is selected
5416 OO
.ui
.SelectWidget
.prototype.getSelectedItem = function () {
5419 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5420 if ( this.items
[ i
].isSelected() ) {
5421 return this.items
[ i
];
5428 * Get highlighted item.
5430 * @return {OO.ui.OptionWidget|null} Highlighted item, `null` if no item is highlighted
5432 OO
.ui
.SelectWidget
.prototype.getHighlightedItem = function () {
5435 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5436 if ( this.items
[ i
].isHighlighted() ) {
5437 return this.items
[ i
];
5444 * Toggle pressed state.
5446 * Press is a state that occurs when a user mouses down on an item, but
5447 * has not yet let go of the mouse. The item may appear selected, but it will not be selected
5448 * until the user releases the mouse.
5450 * @param {boolean} pressed An option is being pressed
5452 OO
.ui
.SelectWidget
.prototype.togglePressed = function ( pressed
) {
5453 if ( pressed
=== undefined ) {
5454 pressed
= !this.pressed
;
5456 if ( pressed
!== this.pressed
) {
5458 .toggleClass( 'oo-ui-selectWidget-pressed', pressed
)
5459 .toggleClass( 'oo-ui-selectWidget-depressed', !pressed
);
5460 this.pressed
= pressed
;
5465 * Highlight an option. If the `item` param is omitted, no options will be highlighted
5466 * and any existing highlight will be removed. The highlight is mutually exclusive.
5468 * @param {OO.ui.OptionWidget} [item] Item to highlight, omit for no highlight
5472 OO
.ui
.SelectWidget
.prototype.highlightItem = function ( item
) {
5473 var i
, len
, highlighted
,
5476 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5477 highlighted
= this.items
[ i
] === item
;
5478 if ( this.items
[ i
].isHighlighted() !== highlighted
) {
5479 this.items
[ i
].setHighlighted( highlighted
);
5484 this.emit( 'highlight', item
);
5491 * Fetch an item by its label.
5493 * @param {string} label Label of the item to select.
5494 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
5495 * @return {OO.ui.Element|null} Item with equivalent label, `null` if none exists
5497 OO
.ui
.SelectWidget
.prototype.getItemFromLabel = function ( label
, prefix
) {
5499 len
= this.items
.length
,
5500 filter
= this.getItemMatcher( label
, true );
5502 for ( i
= 0; i
< len
; i
++ ) {
5503 item
= this.items
[ i
];
5504 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5511 filter
= this.getItemMatcher( label
, false );
5512 for ( i
= 0; i
< len
; i
++ ) {
5513 item
= this.items
[ i
];
5514 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5530 * Programmatically select an option by its label. If the item does not exist,
5531 * all options will be deselected.
5533 * @param {string} [label] Label of the item to select.
5534 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
5538 OO
.ui
.SelectWidget
.prototype.selectItemByLabel = function ( label
, prefix
) {
5539 var itemFromLabel
= this.getItemFromLabel( label
, !!prefix
);
5540 if ( label
=== undefined || !itemFromLabel
) {
5541 return this.selectItem();
5543 return this.selectItem( itemFromLabel
);
5547 * Programmatically select an option by its data. If the `data` parameter is omitted,
5548 * or if the item does not exist, all options will be deselected.
5550 * @param {Object|string} [data] Value of the item to select, omit to deselect all
5554 OO
.ui
.SelectWidget
.prototype.selectItemByData = function ( data
) {
5555 var itemFromData
= this.getItemFromData( data
);
5556 if ( data
=== undefined || !itemFromData
) {
5557 return this.selectItem();
5559 return this.selectItem( itemFromData
);
5563 * Programmatically select an option by its reference. If the `item` parameter is omitted,
5564 * all options will be deselected.
5566 * @param {OO.ui.OptionWidget} [item] Item to select, omit to deselect all
5570 OO
.ui
.SelectWidget
.prototype.selectItem = function ( item
) {
5571 var i
, len
, selected
,
5574 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5575 selected
= this.items
[ i
] === item
;
5576 if ( this.items
[ i
].isSelected() !== selected
) {
5577 this.items
[ i
].setSelected( selected
);
5582 this.emit( 'select', item
);
5591 * Press is a state that occurs when a user mouses down on an item, but has not
5592 * yet let go of the mouse. The item may appear selected, but it will not be selected until the user
5593 * releases the mouse.
5595 * @param {OO.ui.OptionWidget} [item] Item to press, omit to depress all
5599 OO
.ui
.SelectWidget
.prototype.pressItem = function ( item
) {
5600 var i
, len
, pressed
,
5603 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5604 pressed
= this.items
[ i
] === item
;
5605 if ( this.items
[ i
].isPressed() !== pressed
) {
5606 this.items
[ i
].setPressed( pressed
);
5611 this.emit( 'press', item
);
5620 * Note that ‘choose’ should never be modified programmatically. A user can choose
5621 * an option with the keyboard or mouse and it becomes selected. To select an item programmatically,
5622 * use the #selectItem method.
5624 * This method is identical to #selectItem, but may vary in subclasses that take additional action
5625 * when users choose an item with the keyboard or mouse.
5627 * @param {OO.ui.OptionWidget} item Item to choose
5631 OO
.ui
.SelectWidget
.prototype.chooseItem = function ( item
) {
5633 this.selectItem( item
);
5634 this.emit( 'choose', item
);
5641 * Get an option by its position relative to the specified item (or to the start of the option array,
5642 * if item is `null`). The direction in which to search through the option array is specified with a
5643 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
5644 * `null` if there are no options in the array.
5646 * @param {OO.ui.OptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
5647 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
5648 * @param {Function} filter Only consider items for which this function returns
5649 * true. Function takes an OO.ui.OptionWidget and returns a boolean.
5650 * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no items in the select
5652 OO
.ui
.SelectWidget
.prototype.getRelativeSelectableItem = function ( item
, direction
, filter
) {
5653 var currentIndex
, nextIndex
, i
,
5654 increase
= direction
> 0 ? 1 : -1,
5655 len
= this.items
.length
;
5657 if ( !$.isFunction( filter
) ) {
5658 filter
= OO
.ui
.SelectWidget
.static.passAllFilter
;
5661 if ( item
instanceof OO
.ui
.OptionWidget
) {
5662 currentIndex
= this.items
.indexOf( item
);
5663 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
5665 // If no item is selected and moving forward, start at the beginning.
5666 // If moving backward, start at the end.
5667 nextIndex
= direction
> 0 ? 0 : len
- 1;
5670 for ( i
= 0; i
< len
; i
++ ) {
5671 item
= this.items
[ nextIndex
];
5672 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5675 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
5681 * Get the next selectable item or `null` if there are no selectable items.
5682 * Disabled options and menu-section markers and breaks are not selectable.
5684 * @return {OO.ui.OptionWidget|null} Item, `null` if there aren't any selectable items
5686 OO
.ui
.SelectWidget
.prototype.getFirstSelectableItem = function () {
5689 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5690 item
= this.items
[ i
];
5691 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() ) {
5700 * Add an array of options to the select. Optionally, an index number can be used to
5701 * specify an insertion point.
5703 * @param {OO.ui.OptionWidget[]} items Items to add
5704 * @param {number} [index] Index to insert items after
5708 OO
.ui
.SelectWidget
.prototype.addItems = function ( items
, index
) {
5710 OO
.ui
.mixin
.GroupWidget
.prototype.addItems
.call( this, items
, index
);
5712 // Always provide an index, even if it was omitted
5713 this.emit( 'add', items
, index
=== undefined ? this.items
.length
- items
.length
- 1 : index
);
5719 * Remove the specified array of options from the select. Options will be detached
5720 * from the DOM, not removed, so they can be reused later. To remove all options from
5721 * the select, you may wish to use the #clearItems method instead.
5723 * @param {OO.ui.OptionWidget[]} items Items to remove
5727 OO
.ui
.SelectWidget
.prototype.removeItems = function ( items
) {
5730 // Deselect items being removed
5731 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
5733 if ( item
.isSelected() ) {
5734 this.selectItem( null );
5739 OO
.ui
.mixin
.GroupWidget
.prototype.removeItems
.call( this, items
);
5741 this.emit( 'remove', items
);
5747 * Clear all options from the select. Options will be detached from the DOM, not removed,
5748 * so that they can be reused later. To remove a subset of options from the select, use
5749 * the #removeItems method.
5754 OO
.ui
.SelectWidget
.prototype.clearItems = function () {
5755 var items
= this.items
.slice();
5758 OO
.ui
.mixin
.GroupWidget
.prototype.clearItems
.call( this );
5761 this.selectItem( null );
5763 this.emit( 'remove', items
);
5769 * DecoratedOptionWidgets are {@link OO.ui.OptionWidget options} that can be configured
5770 * with an {@link OO.ui.mixin.IconElement icon} and/or {@link OO.ui.mixin.IndicatorElement indicator}.
5771 * This class is used with OO.ui.SelectWidget to create a selection of mutually exclusive
5772 * options. For more information about options and selects, please see the
5773 * [OOjs UI documentation on MediaWiki][1].
5776 * // Decorated options in a select widget
5777 * var select = new OO.ui.SelectWidget( {
5779 * new OO.ui.DecoratedOptionWidget( {
5781 * label: 'Option with icon',
5784 * new OO.ui.DecoratedOptionWidget( {
5786 * label: 'Option with indicator',
5791 * $( 'body' ).append( select.$element );
5793 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5796 * @extends OO.ui.OptionWidget
5797 * @mixins OO.ui.mixin.IconElement
5798 * @mixins OO.ui.mixin.IndicatorElement
5801 * @param {Object} [config] Configuration options
5803 OO
.ui
.DecoratedOptionWidget
= function OoUiDecoratedOptionWidget( config
) {
5804 // Parent constructor
5805 OO
.ui
.DecoratedOptionWidget
.parent
.call( this, config
);
5807 // Mixin constructors
5808 OO
.ui
.mixin
.IconElement
.call( this, config
);
5809 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
5813 .addClass( 'oo-ui-decoratedOptionWidget' )
5814 .prepend( this.$icon
)
5815 .append( this.$indicator
);
5820 OO
.inheritClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.OptionWidget
);
5821 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IconElement
);
5822 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IndicatorElement
);
5825 * MenuOptionWidget is an option widget that looks like a menu item. The class is used with
5826 * OO.ui.MenuSelectWidget to create a menu of mutually exclusive options. Please see
5827 * the [OOjs UI documentation on MediaWiki] [1] for more information.
5829 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
5832 * @extends OO.ui.DecoratedOptionWidget
5835 * @param {Object} [config] Configuration options
5837 OO
.ui
.MenuOptionWidget
= function OoUiMenuOptionWidget( config
) {
5838 // Configuration initialization
5839 config
= $.extend( { icon
: 'check' }, config
);
5841 // Parent constructor
5842 OO
.ui
.MenuOptionWidget
.parent
.call( this, config
);
5846 .attr( 'role', 'menuitem' )
5847 .addClass( 'oo-ui-menuOptionWidget' );
5852 OO
.inheritClass( OO
.ui
.MenuOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
5854 /* Static Properties */
5856 OO
.ui
.MenuOptionWidget
.static.scrollIntoViewOnSelect
= true;
5859 * MenuSectionOptionWidgets are used inside {@link OO.ui.MenuSelectWidget menu select widgets} to group one or more related
5860 * {@link OO.ui.MenuOptionWidget menu options}. MenuSectionOptionWidgets cannot be highlighted or selected.
5863 * var myDropdown = new OO.ui.DropdownWidget( {
5866 * new OO.ui.MenuSectionOptionWidget( {
5869 * new OO.ui.MenuOptionWidget( {
5871 * label: 'Welsh Corgi'
5873 * new OO.ui.MenuOptionWidget( {
5875 * label: 'Standard Poodle'
5877 * new OO.ui.MenuSectionOptionWidget( {
5880 * new OO.ui.MenuOptionWidget( {
5887 * $( 'body' ).append( myDropdown.$element );
5890 * @extends OO.ui.DecoratedOptionWidget
5893 * @param {Object} [config] Configuration options
5895 OO
.ui
.MenuSectionOptionWidget
= function OoUiMenuSectionOptionWidget( config
) {
5896 // Parent constructor
5897 OO
.ui
.MenuSectionOptionWidget
.parent
.call( this, config
);
5900 this.$element
.addClass( 'oo-ui-menuSectionOptionWidget' );
5905 OO
.inheritClass( OO
.ui
.MenuSectionOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
5907 /* Static Properties */
5909 OO
.ui
.MenuSectionOptionWidget
.static.selectable
= false;
5911 OO
.ui
.MenuSectionOptionWidget
.static.highlightable
= false;
5914 * MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains options and
5915 * is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget.
5916 * See {@link OO.ui.DropdownWidget DropdownWidget}, {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget},
5917 * and {@link OO.ui.mixin.LookupElement LookupElement} for examples of widgets that contain menus.
5918 * MenuSelectWidgets themselves are not instantiated directly, rather subclassed
5919 * and customized to be opened, closed, and displayed as needed.
5921 * By default, menus are clipped to the visible viewport and are not visible when a user presses the
5922 * mouse outside the menu.
5924 * Menus also have support for keyboard interaction:
5926 * - Enter/Return key: choose and select a menu option
5927 * - Up-arrow key: highlight the previous menu option
5928 * - Down-arrow key: highlight the next menu option
5929 * - Esc key: hide the menu
5931 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
5932 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5935 * @extends OO.ui.SelectWidget
5936 * @mixins OO.ui.mixin.ClippableElement
5939 * @param {Object} [config] Configuration options
5940 * @cfg {OO.ui.TextInputWidget} [input] Text input used to implement option highlighting for menu items that match
5941 * the text the user types. This config is used by {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget}
5942 * and {@link OO.ui.mixin.LookupElement LookupElement}
5943 * @cfg {jQuery} [$input] Text input used to implement option highlighting for menu items that match
5944 * the text the user types. This config is used by {@link OO.ui.CapsuleMultiSelectWidget CapsuleMultiSelectWidget}
5945 * @cfg {OO.ui.Widget} [widget] Widget associated with the menu's active state. If the user clicks the mouse
5946 * anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button
5947 * that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks
5948 * that button, unless the button (or its parent widget) is passed in here.
5949 * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed outside the menu.
5950 * @cfg {boolean} [filterFromInput=false] Filter the displayed options from the input
5952 OO
.ui
.MenuSelectWidget
= function OoUiMenuSelectWidget( config
) {
5953 // Configuration initialization
5954 config
= config
|| {};
5956 // Parent constructor
5957 OO
.ui
.MenuSelectWidget
.parent
.call( this, config
);
5959 // Mixin constructors
5960 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, { $clippable
: this.$group
} ) );
5963 this.autoHide
= config
.autoHide
=== undefined || !!config
.autoHide
;
5964 this.filterFromInput
= !!config
.filterFromInput
;
5965 this.$input
= config
.$input
? config
.$input
: config
.input
? config
.input
.$input
: null;
5966 this.$widget
= config
.widget
? config
.widget
.$element
: null;
5967 this.onDocumentMouseDownHandler
= this.onDocumentMouseDown
.bind( this );
5968 this.onInputEditHandler
= OO
.ui
.debounce( this.updateItemVisibility
.bind( this ), 100 );
5972 .addClass( 'oo-ui-menuSelectWidget' )
5973 .attr( 'role', 'menu' );
5975 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
5976 // that reference properties not initialized at that time of parent class construction
5977 // TODO: Find a better way to handle post-constructor setup
5978 this.visible
= false;
5979 this.$element
.addClass( 'oo-ui-element-hidden' );
5984 OO
.inheritClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.SelectWidget
);
5985 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.ClippableElement
);
5990 * Handles document mouse down events.
5993 * @param {MouseEvent} e Mouse down event
5995 OO
.ui
.MenuSelectWidget
.prototype.onDocumentMouseDown = function ( e
) {
5997 !OO
.ui
.contains( this.$element
[ 0 ], e
.target
, true ) &&
5998 ( !this.$widget
|| !OO
.ui
.contains( this.$widget
[ 0 ], e
.target
, true ) )
6000 this.toggle( false );
6007 OO
.ui
.MenuSelectWidget
.prototype.onKeyDown = function ( e
) {
6008 var currentItem
= this.getHighlightedItem() || this.getSelectedItem();
6010 if ( !this.isDisabled() && this.isVisible() ) {
6011 switch ( e
.keyCode
) {
6012 case OO
.ui
.Keys
.LEFT
:
6013 case OO
.ui
.Keys
.RIGHT
:
6014 // Do nothing if a text field is associated, arrow keys will be handled natively
6015 if ( !this.$input
) {
6016 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6019 case OO
.ui
.Keys
.ESCAPE
:
6020 case OO
.ui
.Keys
.TAB
:
6021 if ( currentItem
) {
6022 currentItem
.setHighlighted( false );
6024 this.toggle( false );
6025 // Don't prevent tabbing away, prevent defocusing
6026 if ( e
.keyCode
=== OO
.ui
.Keys
.ESCAPE
) {
6028 e
.stopPropagation();
6032 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6039 * Update menu item visibility after input changes.
6043 OO
.ui
.MenuSelectWidget
.prototype.updateItemVisibility = function () {
6045 len
= this.items
.length
,
6046 showAll
= !this.isVisible(),
6047 filter
= showAll
? null : this.getItemMatcher( this.$input
.val() );
6049 for ( i
= 0; i
< len
; i
++ ) {
6050 item
= this.items
[ i
];
6051 if ( item
instanceof OO
.ui
.OptionWidget
) {
6052 item
.toggle( showAll
|| filter( item
) );
6056 // Reevaluate clipping
6063 OO
.ui
.MenuSelectWidget
.prototype.bindKeyDownListener = function () {
6064 if ( this.$input
) {
6065 this.$input
.on( 'keydown', this.onKeyDownHandler
);
6067 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyDownListener
.call( this );
6074 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyDownListener = function () {
6075 if ( this.$input
) {
6076 this.$input
.off( 'keydown', this.onKeyDownHandler
);
6078 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyDownListener
.call( this );
6085 OO
.ui
.MenuSelectWidget
.prototype.bindKeyPressListener = function () {
6086 if ( this.$input
) {
6087 if ( this.filterFromInput
) {
6088 this.$input
.on( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6091 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyPressListener
.call( this );
6098 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyPressListener = function () {
6099 if ( this.$input
) {
6100 if ( this.filterFromInput
) {
6101 this.$input
.off( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6102 this.updateItemVisibility();
6105 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyPressListener
.call( this );
6112 * When a user chooses an item, the menu is closed.
6114 * Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard
6115 * or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.
6117 * @param {OO.ui.OptionWidget} item Item to choose
6120 OO
.ui
.MenuSelectWidget
.prototype.chooseItem = function ( item
) {
6121 OO
.ui
.MenuSelectWidget
.parent
.prototype.chooseItem
.call( this, item
);
6122 this.toggle( false );
6129 OO
.ui
.MenuSelectWidget
.prototype.addItems = function ( items
, index
) {
6131 OO
.ui
.MenuSelectWidget
.parent
.prototype.addItems
.call( this, items
, index
);
6133 // Reevaluate clipping
6142 OO
.ui
.MenuSelectWidget
.prototype.removeItems = function ( items
) {
6144 OO
.ui
.MenuSelectWidget
.parent
.prototype.removeItems
.call( this, items
);
6146 // Reevaluate clipping
6155 OO
.ui
.MenuSelectWidget
.prototype.clearItems = function () {
6157 OO
.ui
.MenuSelectWidget
.parent
.prototype.clearItems
.call( this );
6159 // Reevaluate clipping
6168 OO
.ui
.MenuSelectWidget
.prototype.toggle = function ( visible
) {
6171 visible
= ( visible
=== undefined ? !this.visible
: !!visible
) && !!this.items
.length
;
6172 change
= visible
!== this.isVisible();
6175 OO
.ui
.MenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
6179 this.bindKeyDownListener();
6180 this.bindKeyPressListener();
6182 this.toggleClipping( true );
6184 if ( this.getSelectedItem() ) {
6185 this.getSelectedItem().scrollElementIntoView( { duration
: 0 } );
6189 if ( this.autoHide
) {
6190 this.getElementDocument().addEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
6193 this.unbindKeyDownListener();
6194 this.unbindKeyPressListener();
6195 this.getElementDocument().removeEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
6196 this.toggleClipping( false );
6204 * DropdownWidgets are not menus themselves, rather they contain a menu of options created with
6205 * OO.ui.MenuOptionWidget. The DropdownWidget takes care of opening and displaying the menu so that
6206 * users can interact with it.
6208 * If you want to use this within a HTML form, such as a OO.ui.FormLayout, use
6209 * OO.ui.DropdownInputWidget instead.
6212 * // Example: A DropdownWidget with a menu that contains three options
6213 * var dropDown = new OO.ui.DropdownWidget( {
6214 * label: 'Dropdown menu: Select a menu option',
6217 * new OO.ui.MenuOptionWidget( {
6221 * new OO.ui.MenuOptionWidget( {
6225 * new OO.ui.MenuOptionWidget( {
6233 * $( 'body' ).append( dropDown.$element );
6235 * dropDown.getMenu().selectItemByData( 'b' );
6237 * dropDown.getMenu().getSelectedItem().getData(); // returns 'b'
6239 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
6241 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
6244 * @extends OO.ui.Widget
6245 * @mixins OO.ui.mixin.IconElement
6246 * @mixins OO.ui.mixin.IndicatorElement
6247 * @mixins OO.ui.mixin.LabelElement
6248 * @mixins OO.ui.mixin.TitledElement
6249 * @mixins OO.ui.mixin.TabIndexedElement
6252 * @param {Object} [config] Configuration options
6253 * @cfg {Object} [menu] Configuration options to pass to {@link OO.ui.FloatingMenuSelectWidget menu select widget}
6254 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
6255 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
6256 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
6258 OO
.ui
.DropdownWidget
= function OoUiDropdownWidget( config
) {
6259 // Configuration initialization
6260 config
= $.extend( { indicator
: 'down' }, config
);
6262 // Parent constructor
6263 OO
.ui
.DropdownWidget
.parent
.call( this, config
);
6265 // Properties (must be set before TabIndexedElement constructor call)
6266 this.$handle
= this.$( '<span>' );
6267 this.$overlay
= config
.$overlay
|| this.$element
;
6269 // Mixin constructors
6270 OO
.ui
.mixin
.IconElement
.call( this, config
);
6271 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
6272 OO
.ui
.mixin
.LabelElement
.call( this, config
);
6273 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
6274 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$handle
} ) );
6277 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend( {
6279 $container
: this.$element
6284 click
: this.onClick
.bind( this ),
6285 keydown
: this.onKeyDown
.bind( this )
6287 this.menu
.connect( this, { select
: 'onMenuSelect' } );
6291 .addClass( 'oo-ui-dropdownWidget-handle' )
6292 .append( this.$icon
, this.$label
, this.$indicator
);
6294 .addClass( 'oo-ui-dropdownWidget' )
6295 .append( this.$handle
);
6296 this.$overlay
.append( this.menu
.$element
);
6301 OO
.inheritClass( OO
.ui
.DropdownWidget
, OO
.ui
.Widget
);
6302 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IconElement
);
6303 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IndicatorElement
);
6304 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.LabelElement
);
6305 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TitledElement
);
6306 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6313 * @return {OO.ui.MenuSelectWidget} Menu of widget
6315 OO
.ui
.DropdownWidget
.prototype.getMenu = function () {
6320 * Handles menu select events.
6323 * @param {OO.ui.MenuOptionWidget} item Selected menu item
6325 OO
.ui
.DropdownWidget
.prototype.onMenuSelect = function ( item
) {
6329 this.setLabel( null );
6333 selectedLabel
= item
.getLabel();
6335 // If the label is a DOM element, clone it, because setLabel will append() it
6336 if ( selectedLabel
instanceof jQuery
) {
6337 selectedLabel
= selectedLabel
.clone();
6340 this.setLabel( selectedLabel
);
6344 * Handle mouse click events.
6347 * @param {jQuery.Event} e Mouse click event
6349 OO
.ui
.DropdownWidget
.prototype.onClick = function ( e
) {
6350 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
6357 * Handle key down events.
6360 * @param {jQuery.Event} e Key down event
6362 OO
.ui
.DropdownWidget
.prototype.onKeyDown = function ( e
) {
6364 !this.isDisabled() &&
6366 e
.which
=== OO
.ui
.Keys
.ENTER
||
6368 !this.menu
.isVisible() &&
6370 e
.which
=== OO
.ui
.Keys
.SPACE
||
6371 e
.which
=== OO
.ui
.Keys
.UP
||
6372 e
.which
=== OO
.ui
.Keys
.DOWN
6383 * RadioOptionWidget is an option widget that looks like a radio button.
6384 * The class is used with OO.ui.RadioSelectWidget to create a selection of radio options.
6385 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
6387 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
6390 * @extends OO.ui.OptionWidget
6393 * @param {Object} [config] Configuration options
6395 OO
.ui
.RadioOptionWidget
= function OoUiRadioOptionWidget( config
) {
6396 // Configuration initialization
6397 config
= config
|| {};
6399 // Properties (must be done before parent constructor which calls #setDisabled)
6400 this.radio
= new OO
.ui
.RadioInputWidget( { value
: config
.data
, tabIndex
: -1 } );
6402 // Parent constructor
6403 OO
.ui
.RadioOptionWidget
.parent
.call( this, config
);
6406 this.radio
.$input
.on( 'focus', this.onInputFocus
.bind( this ) );
6409 // Remove implicit role, we're handling it ourselves
6410 this.radio
.$input
.attr( 'role', 'presentation' );
6412 .addClass( 'oo-ui-radioOptionWidget' )
6413 .attr( 'role', 'radio' )
6414 .attr( 'aria-checked', 'false' )
6415 .removeAttr( 'aria-selected' )
6416 .prepend( this.radio
.$element
);
6421 OO
.inheritClass( OO
.ui
.RadioOptionWidget
, OO
.ui
.OptionWidget
);
6423 /* Static Properties */
6425 OO
.ui
.RadioOptionWidget
.static.highlightable
= false;
6427 OO
.ui
.RadioOptionWidget
.static.scrollIntoViewOnSelect
= true;
6429 OO
.ui
.RadioOptionWidget
.static.pressable
= false;
6431 OO
.ui
.RadioOptionWidget
.static.tagName
= 'label';
6436 * @param {jQuery.Event} e Focus event
6439 OO
.ui
.RadioOptionWidget
.prototype.onInputFocus = function () {
6440 this.radio
.$input
.blur();
6441 this.$element
.parent().focus();
6447 OO
.ui
.RadioOptionWidget
.prototype.setSelected = function ( state
) {
6448 OO
.ui
.RadioOptionWidget
.parent
.prototype.setSelected
.call( this, state
);
6450 this.radio
.setSelected( state
);
6452 .attr( 'aria-checked', state
.toString() )
6453 .removeAttr( 'aria-selected' );
6461 OO
.ui
.RadioOptionWidget
.prototype.setDisabled = function ( disabled
) {
6462 OO
.ui
.RadioOptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
6464 this.radio
.setDisabled( this.isDisabled() );
6470 * RadioSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains radio
6471 * options and is used together with OO.ui.RadioOptionWidget. The RadioSelectWidget provides
6472 * an interface for adding, removing and selecting options.
6473 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
6475 * If you want to use this within a HTML form, such as a OO.ui.FormLayout, use
6476 * OO.ui.RadioSelectInputWidget instead.
6479 * // A RadioSelectWidget with RadioOptions.
6480 * var option1 = new OO.ui.RadioOptionWidget( {
6482 * label: 'Selected radio option'
6485 * var option2 = new OO.ui.RadioOptionWidget( {
6487 * label: 'Unselected radio option'
6490 * var radioSelect=new OO.ui.RadioSelectWidget( {
6491 * items: [ option1, option2 ]
6494 * // Select 'option 1' using the RadioSelectWidget's selectItem() method.
6495 * radioSelect.selectItem( option1 );
6497 * $( 'body' ).append( radioSelect.$element );
6499 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6503 * @extends OO.ui.SelectWidget
6504 * @mixins OO.ui.mixin.TabIndexedElement
6507 * @param {Object} [config] Configuration options
6509 OO
.ui
.RadioSelectWidget
= function OoUiRadioSelectWidget( config
) {
6510 // Parent constructor
6511 OO
.ui
.RadioSelectWidget
.parent
.call( this, config
);
6513 // Mixin constructors
6514 OO
.ui
.mixin
.TabIndexedElement
.call( this, config
);
6518 focus
: this.bindKeyDownListener
.bind( this ),
6519 blur
: this.unbindKeyDownListener
.bind( this )
6524 .addClass( 'oo-ui-radioSelectWidget' )
6525 .attr( 'role', 'radiogroup' );
6530 OO
.inheritClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.SelectWidget
);
6531 OO
.mixinClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6534 * Element that will stick under a specified container, even when it is inserted elsewhere in the
6535 * document (for example, in a OO.ui.Window's $overlay).
6537 * The elements's position is automatically calculated and maintained when window is resized or the
6538 * page is scrolled. If you reposition the container manually, you have to call #position to make
6539 * sure the element is still placed correctly.
6541 * As positioning is only possible when both the element and the container are attached to the DOM
6542 * and visible, it's only done after you call #togglePositioning. You might want to do this inside
6543 * the #toggle method to display a floating popup, for example.
6549 * @param {Object} [config] Configuration options
6550 * @cfg {jQuery} [$floatable] Node to position, assigned to #$floatable, omit to use #$element
6551 * @cfg {jQuery} [$floatableContainer] Node to position below
6553 OO
.ui
.mixin
.FloatableElement
= function OoUiMixinFloatableElement( config
) {
6554 // Configuration initialization
6555 config
= config
|| {};
6558 this.$floatable
= null;
6559 this.$floatableContainer
= null;
6560 this.$floatableWindow
= null;
6561 this.$floatableClosestScrollable
= null;
6562 this.onFloatableScrollHandler
= this.position
.bind( this );
6563 this.onFloatableWindowResizeHandler
= this.position
.bind( this );
6566 this.setFloatableContainer( config
.$floatableContainer
);
6567 this.setFloatableElement( config
.$floatable
|| this.$element
);
6573 * Set floatable element.
6575 * If an element is already set, it will be cleaned up before setting up the new element.
6577 * @param {jQuery} $floatable Element to make floatable
6579 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableElement = function ( $floatable
) {
6580 if ( this.$floatable
) {
6581 this.$floatable
.removeClass( 'oo-ui-floatableElement-floatable' );
6582 this.$floatable
.css( { left
: '', top
: '' } );
6585 this.$floatable
= $floatable
.addClass( 'oo-ui-floatableElement-floatable' );
6590 * Set floatable container.
6592 * The element will be always positioned under the specified container.
6594 * @param {jQuery|null} $floatableContainer Container to keep visible, or null to unset
6596 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableContainer = function ( $floatableContainer
) {
6597 this.$floatableContainer
= $floatableContainer
;
6598 if ( this.$floatable
) {
6604 * Toggle positioning.
6606 * Do not turn positioning on until after the element is attached to the DOM and visible.
6608 * @param {boolean} [positioning] Enable positioning, omit to toggle
6611 OO
.ui
.mixin
.FloatableElement
.prototype.togglePositioning = function ( positioning
) {
6612 var closestScrollableOfContainer
, closestScrollableOfFloatable
;
6614 positioning
= positioning
=== undefined ? !this.positioning
: !!positioning
;
6616 if ( this.positioning
!== positioning
) {
6617 this.positioning
= positioning
;
6619 closestScrollableOfContainer
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatableContainer
[ 0 ] );
6620 closestScrollableOfFloatable
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatable
[ 0 ] );
6621 this.needsCustomPosition
= closestScrollableOfContainer
!== closestScrollableOfFloatable
;
6622 // If the scrollable is the root, we have to listen to scroll events
6623 // on the window because of browser inconsistencies.
6624 if ( $( closestScrollableOfContainer
).is( 'html, body' ) ) {
6625 closestScrollableOfContainer
= OO
.ui
.Element
.static.getWindow( closestScrollableOfContainer
);
6628 if ( positioning
) {
6629 this.$floatableWindow
= $( this.getElementWindow() );
6630 this.$floatableWindow
.on( 'resize', this.onFloatableWindowResizeHandler
);
6632 this.$floatableClosestScrollable
= $( closestScrollableOfContainer
);
6633 this.$floatableClosestScrollable
.on( 'scroll', this.onFloatableScrollHandler
);
6635 // Initial position after visible
6638 if ( this.$floatableWindow
) {
6639 this.$floatableWindow
.off( 'resize', this.onFloatableWindowResizeHandler
);
6640 this.$floatableWindow
= null;
6643 if ( this.$floatableClosestScrollable
) {
6644 this.$floatableClosestScrollable
.off( 'scroll', this.onFloatableScrollHandler
);
6645 this.$floatableClosestScrollable
= null;
6648 this.$floatable
.css( { left
: '', top
: '' } );
6656 * Check whether the bottom edge of the given element is within the viewport of the given container.
6659 * @param {jQuery} $element
6660 * @param {jQuery} $container
6663 OO
.ui
.mixin
.FloatableElement
.prototype.isElementInViewport = function ( $element
, $container
) {
6664 var elemRect
, contRect
,
6665 topEdgeInBounds
= false,
6666 leftEdgeInBounds
= false,
6667 bottomEdgeInBounds
= false,
6668 rightEdgeInBounds
= false;
6670 elemRect
= $element
[ 0 ].getBoundingClientRect();
6671 if ( $container
[ 0 ] === window
) {
6675 right
: document
.documentElement
.clientWidth
,
6676 bottom
: document
.documentElement
.clientHeight
6679 contRect
= $container
[ 0 ].getBoundingClientRect();
6682 if ( elemRect
.top
>= contRect
.top
&& elemRect
.top
<= contRect
.bottom
) {
6683 topEdgeInBounds
= true;
6685 if ( elemRect
.left
>= contRect
.left
&& elemRect
.left
<= contRect
.right
) {
6686 leftEdgeInBounds
= true;
6688 if ( elemRect
.bottom
>= contRect
.top
&& elemRect
.bottom
<= contRect
.bottom
) {
6689 bottomEdgeInBounds
= true;
6691 if ( elemRect
.right
>= contRect
.left
&& elemRect
.right
<= contRect
.right
) {
6692 rightEdgeInBounds
= true;
6695 // We only care that any part of the bottom edge is visible
6696 return bottomEdgeInBounds
&& ( leftEdgeInBounds
|| rightEdgeInBounds
);
6700 * Position the floatable below its container.
6702 * This should only be done when both of them are attached to the DOM and visible.
6706 OO
.ui
.mixin
.FloatableElement
.prototype.position = function () {
6709 if ( !this.positioning
) {
6713 if ( !this.isElementInViewport( this.$floatableContainer
, this.$floatableClosestScrollable
) ) {
6714 this.$floatable
.addClass( 'oo-ui-floatableElement-hidden' );
6717 this.$floatable
.removeClass( 'oo-ui-floatableElement-hidden' );
6720 if ( !this.needsCustomPosition
) {
6724 pos
= OO
.ui
.Element
.static.getRelativePosition( this.$floatableContainer
, this.$floatable
.offsetParent() );
6726 // Position under container
6727 pos
.top
+= this.$floatableContainer
.height();
6728 this.$floatable
.css( pos
);
6730 // We updated the position, so re-evaluate the clipping state.
6731 // (ClippableElement does not listen to 'scroll' events on $floatableContainer's parent, and so
6732 // will not notice the need to update itself.)
6733 // TODO: This is terrible, we shouldn't need to know about ClippableElement at all here. Why does
6734 // it not listen to the right events in the right places?
6743 * FloatingMenuSelectWidget is a menu that will stick under a specified
6744 * container, even when it is inserted elsewhere in the document (for example,
6745 * in a OO.ui.Window's $overlay). This is sometimes necessary to prevent the
6746 * menu from being clipped too aggresively.
6748 * The menu's position is automatically calculated and maintained when the menu
6749 * is toggled or the window is resized.
6751 * See OO.ui.ComboBoxInputWidget for an example of a widget that uses this class.
6754 * @extends OO.ui.MenuSelectWidget
6755 * @mixins OO.ui.mixin.FloatableElement
6758 * @param {OO.ui.Widget} [inputWidget] Widget to provide the menu for.
6759 * Deprecated, omit this parameter and specify `$container` instead.
6760 * @param {Object} [config] Configuration options
6761 * @cfg {jQuery} [$container=inputWidget.$element] Element to render menu under
6763 OO
.ui
.FloatingMenuSelectWidget
= function OoUiFloatingMenuSelectWidget( inputWidget
, config
) {
6764 // Allow 'inputWidget' parameter and config for backwards compatibility
6765 if ( OO
.isPlainObject( inputWidget
) && config
=== undefined ) {
6766 config
= inputWidget
;
6767 inputWidget
= config
.inputWidget
;
6770 // Configuration initialization
6771 config
= config
|| {};
6773 // Parent constructor
6774 OO
.ui
.FloatingMenuSelectWidget
.parent
.call( this, config
);
6776 // Properties (must be set before mixin constructors)
6777 this.inputWidget
= inputWidget
; // For backwards compatibility
6778 this.$container
= config
.$container
|| this.inputWidget
.$element
;
6780 // Mixins constructors
6781 OO
.ui
.mixin
.FloatableElement
.call( this, $.extend( {}, config
, { $floatableContainer
: this.$container
} ) );
6784 this.$element
.addClass( 'oo-ui-floatingMenuSelectWidget' );
6785 // For backwards compatibility
6786 this.$element
.addClass( 'oo-ui-textInputMenuSelectWidget' );
6791 OO
.inheritClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.MenuSelectWidget
);
6792 OO
.mixinClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.mixin
.FloatableElement
);
6794 // For backwards compatibility
6795 OO
.ui
.TextInputMenuSelectWidget
= OO
.ui
.FloatingMenuSelectWidget
;
6802 OO
.ui
.FloatingMenuSelectWidget
.prototype.toggle = function ( visible
) {
6804 visible
= visible
=== undefined ? !this.isVisible() : !!visible
;
6805 change
= visible
!== this.isVisible();
6807 if ( change
&& visible
) {
6808 // Make sure the width is set before the parent method runs.
6809 this.setIdealSize( this.$container
.width() );
6813 // This will call this.clip(), which is nonsensical since we're not positioned yet...
6814 OO
.ui
.FloatingMenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
6817 this.togglePositioning( this.isVisible() );
6824 * InputWidget is the base class for all input widgets, which
6825 * include {@link OO.ui.TextInputWidget text inputs}, {@link OO.ui.CheckboxInputWidget checkbox inputs},
6826 * {@link OO.ui.RadioInputWidget radio inputs}, and {@link OO.ui.ButtonInputWidget button inputs}.
6827 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
6829 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
6833 * @extends OO.ui.Widget
6834 * @mixins OO.ui.mixin.FlaggedElement
6835 * @mixins OO.ui.mixin.TabIndexedElement
6836 * @mixins OO.ui.mixin.TitledElement
6837 * @mixins OO.ui.mixin.AccessKeyedElement
6840 * @param {Object} [config] Configuration options
6841 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
6842 * @cfg {string} [value=''] The value of the input.
6843 * @cfg {string} [dir] The directionality of the input (ltr/rtl).
6844 * @cfg {Function} [inputFilter] The name of an input filter function. Input filters modify the value of an input
6845 * before it is accepted.
6847 OO
.ui
.InputWidget
= function OoUiInputWidget( config
) {
6848 // Configuration initialization
6849 config
= config
|| {};
6851 // Parent constructor
6852 OO
.ui
.InputWidget
.parent
.call( this, config
);
6855 // See #reusePreInfuseDOM about config.$input
6856 this.$input
= config
.$input
|| this.getInputElement( config
);
6858 this.inputFilter
= config
.inputFilter
;
6860 // Mixin constructors
6861 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
6862 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$input
} ) );
6863 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
6864 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$input
} ) );
6867 this.$input
.on( 'keydown mouseup cut paste change input select', this.onEdit
.bind( this ) );
6871 .addClass( 'oo-ui-inputWidget-input' )
6872 .attr( 'name', config
.name
)
6873 .prop( 'disabled', this.isDisabled() );
6875 .addClass( 'oo-ui-inputWidget' )
6876 .append( this.$input
);
6877 this.setValue( config
.value
);
6879 this.setDir( config
.dir
);
6885 OO
.inheritClass( OO
.ui
.InputWidget
, OO
.ui
.Widget
);
6886 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.FlaggedElement
);
6887 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6888 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TitledElement
);
6889 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
6891 /* Static Properties */
6893 OO
.ui
.InputWidget
.static.supportsSimpleLabel
= true;
6895 /* Static Methods */
6900 OO
.ui
.InputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
6901 config
= OO
.ui
.InputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
6902 // Reusing $input lets browsers preserve inputted values across page reloads (T114134)
6903 config
.$input
= $( node
).find( '.oo-ui-inputWidget-input' );
6910 OO
.ui
.InputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
6911 var state
= OO
.ui
.InputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
6912 state
.value
= config
.$input
.val();
6913 // Might be better in TabIndexedElement, but it's awkward to do there because mixins are awkward
6914 state
.focus
= config
.$input
.is( ':focus' );
6923 * A change event is emitted when the value of the input changes.
6925 * @param {string} value
6931 * Get input element.
6933 * Subclasses of OO.ui.InputWidget use the `config` parameter to produce different elements in
6934 * different circumstances. The element must have a `value` property (like form elements).
6937 * @param {Object} config Configuration options
6938 * @return {jQuery} Input element
6940 OO
.ui
.InputWidget
.prototype.getInputElement = function () {
6941 return $( '<input>' );
6945 * Handle potentially value-changing events.
6948 * @param {jQuery.Event} e Key down, mouse up, cut, paste, change, input, or select event
6950 OO
.ui
.InputWidget
.prototype.onEdit = function () {
6952 if ( !this.isDisabled() ) {
6953 // Allow the stack to clear so the value will be updated
6954 setTimeout( function () {
6955 widget
.setValue( widget
.$input
.val() );
6961 * Get the value of the input.
6963 * @return {string} Input value
6965 OO
.ui
.InputWidget
.prototype.getValue = function () {
6966 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
6967 // it, and we won't know unless they're kind enough to trigger a 'change' event.
6968 var value
= this.$input
.val();
6969 if ( this.value
!== value
) {
6970 this.setValue( value
);
6976 * Set the directionality of the input, either RTL (right-to-left) or LTR (left-to-right).
6978 * @deprecated since v0.13.1; use #setDir directly
6979 * @param {boolean} isRTL Directionality is right-to-left
6982 OO
.ui
.InputWidget
.prototype.setRTL = function ( isRTL
) {
6983 this.setDir( isRTL
? 'rtl' : 'ltr' );
6988 * Set the directionality of the input.
6990 * @param {string} dir Text directionality: 'ltr', 'rtl' or 'auto'
6993 OO
.ui
.InputWidget
.prototype.setDir = function ( dir
) {
6994 this.$input
.prop( 'dir', dir
);
6999 * Set the value of the input.
7001 * @param {string} value New value
7005 OO
.ui
.InputWidget
.prototype.setValue = function ( value
) {
7006 value
= this.cleanUpValue( value
);
7007 // Update the DOM if it has changed. Note that with cleanUpValue, it
7008 // is possible for the DOM value to change without this.value changing.
7009 if ( this.$input
.val() !== value
) {
7010 this.$input
.val( value
);
7012 if ( this.value
!== value
) {
7014 this.emit( 'change', this.value
);
7020 * Clean up incoming value.
7022 * Ensures value is a string, and converts undefined and null to empty string.
7025 * @param {string} value Original value
7026 * @return {string} Cleaned up value
7028 OO
.ui
.InputWidget
.prototype.cleanUpValue = function ( value
) {
7029 if ( value
=== undefined || value
=== null ) {
7031 } else if ( this.inputFilter
) {
7032 return this.inputFilter( String( value
) );
7034 return String( value
);
7039 * Simulate the behavior of clicking on a label bound to this input. This method is only called by
7040 * {@link OO.ui.LabelWidget LabelWidget} and {@link OO.ui.FieldLayout FieldLayout}. It should not be
7043 OO
.ui
.InputWidget
.prototype.simulateLabelClick = function () {
7044 if ( !this.isDisabled() ) {
7045 if ( this.$input
.is( ':checkbox, :radio' ) ) {
7046 this.$input
.click();
7048 if ( this.$input
.is( ':input' ) ) {
7049 this.$input
[ 0 ].focus();
7057 OO
.ui
.InputWidget
.prototype.setDisabled = function ( state
) {
7058 OO
.ui
.InputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7059 if ( this.$input
) {
7060 this.$input
.prop( 'disabled', this.isDisabled() );
7070 OO
.ui
.InputWidget
.prototype.focus = function () {
7071 this.$input
[ 0 ].focus();
7080 OO
.ui
.InputWidget
.prototype.blur = function () {
7081 this.$input
[ 0 ].blur();
7088 OO
.ui
.InputWidget
.prototype.restorePreInfuseState = function ( state
) {
7089 OO
.ui
.InputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7090 if ( state
.value
!== undefined && state
.value
!== this.getValue() ) {
7091 this.setValue( state
.value
);
7093 if ( state
.focus
) {
7099 * ButtonInputWidget is used to submit HTML forms and is intended to be used within
7100 * a OO.ui.FormLayout. If you do not need the button to work with HTML forms, you probably
7101 * want to use OO.ui.ButtonWidget instead. Button input widgets can be rendered as either an
7102 * HTML `<button/>` (the default) or an HTML `<input/>` tags. See the
7103 * [OOjs UI documentation on MediaWiki] [1] for more information.
7106 * // A ButtonInputWidget rendered as an HTML button, the default.
7107 * var button = new OO.ui.ButtonInputWidget( {
7108 * label: 'Input button',
7112 * $( 'body' ).append( button.$element );
7114 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs#Button_inputs
7117 * @extends OO.ui.InputWidget
7118 * @mixins OO.ui.mixin.ButtonElement
7119 * @mixins OO.ui.mixin.IconElement
7120 * @mixins OO.ui.mixin.IndicatorElement
7121 * @mixins OO.ui.mixin.LabelElement
7122 * @mixins OO.ui.mixin.TitledElement
7125 * @param {Object} [config] Configuration options
7126 * @cfg {string} [type='button'] The value of the HTML `'type'` attribute: 'button', 'submit' or 'reset'.
7127 * @cfg {boolean} [useInputTag=false] Use an `<input/>` tag instead of a `<button/>` tag, the default.
7128 * Widgets configured to be an `<input/>` do not support {@link #icon icons} and {@link #indicator indicators},
7129 * non-plaintext {@link #label labels}, or {@link #value values}. In general, useInputTag should only
7130 * be set to `true` when there’s need to support IE 6 in a form with multiple buttons.
7132 OO
.ui
.ButtonInputWidget
= function OoUiButtonInputWidget( config
) {
7133 // Configuration initialization
7134 config
= $.extend( { type
: 'button', useInputTag
: false }, config
);
7136 // See InputWidget#reusePreInfuseDOM about config.$input
7137 if ( config
.$input
) {
7138 config
.$input
.empty();
7141 // Properties (must be set before parent constructor, which calls #setValue)
7142 this.useInputTag
= config
.useInputTag
;
7144 // Parent constructor
7145 OO
.ui
.ButtonInputWidget
.parent
.call( this, config
);
7147 // Mixin constructors
7148 OO
.ui
.mixin
.ButtonElement
.call( this, $.extend( {}, config
, { $button
: this.$input
} ) );
7149 OO
.ui
.mixin
.IconElement
.call( this, config
);
7150 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7151 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7152 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
7155 if ( !config
.useInputTag
) {
7156 this.$input
.append( this.$icon
, this.$label
, this.$indicator
);
7158 this.$element
.addClass( 'oo-ui-buttonInputWidget' );
7163 OO
.inheritClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.InputWidget
);
7164 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.ButtonElement
);
7165 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IconElement
);
7166 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
7167 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.LabelElement
);
7168 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.TitledElement
);
7170 /* Static Properties */
7173 * Disable generating `<label>` elements for buttons. One would very rarely need additional label
7174 * for a button, and it's already a big clickable target, and it causes unexpected rendering.
7176 OO
.ui
.ButtonInputWidget
.static.supportsSimpleLabel
= false;
7184 OO
.ui
.ButtonInputWidget
.prototype.getInputElement = function ( config
) {
7186 type
= [ 'button', 'submit', 'reset' ].indexOf( config
.type
) !== -1 ? config
.type
: 'button';
7187 return $( '<' + ( config
.useInputTag
? 'input' : 'button' ) + ' type="' + type
+ '">' );
7193 * If #useInputTag is `true`, the label is set as the `value` of the `<input/>` tag.
7195 * @param {jQuery|string|Function|null} label Label nodes, text, a function that returns nodes or
7196 * text, or `null` for no label
7199 OO
.ui
.ButtonInputWidget
.prototype.setLabel = function ( label
) {
7200 if ( typeof label
=== 'function' ) {
7201 label
= OO
.ui
.resolveMsg( label
);
7204 if ( this.useInputTag
) {
7205 // Discard non-plaintext labels
7206 if ( typeof label
!== 'string' ) {
7210 this.$input
.val( label
);
7213 return OO
.ui
.mixin
.LabelElement
.prototype.setLabel
.call( this, label
);
7217 * Set the value of the input.
7219 * This method is disabled for button inputs configured as {@link #useInputTag <input/> tags}, as
7220 * they do not support {@link #value values}.
7222 * @param {string} value New value
7225 OO
.ui
.ButtonInputWidget
.prototype.setValue = function ( value
) {
7226 if ( !this.useInputTag
) {
7227 OO
.ui
.ButtonInputWidget
.parent
.prototype.setValue
.call( this, value
);
7233 * CheckboxInputWidgets, like HTML checkboxes, can be selected and/or configured with a value.
7234 * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
7235 * in {@link OO.ui.FieldLayout field layouts} that use the {@link OO.ui.FieldLayout#align inline}
7236 * alignment. For more information, please see the [OOjs UI documentation on MediaWiki][1].
7238 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
7241 * // An example of selected, unselected, and disabled checkbox inputs
7242 * var checkbox1=new OO.ui.CheckboxInputWidget( {
7246 * var checkbox2=new OO.ui.CheckboxInputWidget( {
7249 * var checkbox3=new OO.ui.CheckboxInputWidget( {
7253 * // Create a fieldset layout with fields for each checkbox.
7254 * var fieldset = new OO.ui.FieldsetLayout( {
7255 * label: 'Checkboxes'
7257 * fieldset.addItems( [
7258 * new OO.ui.FieldLayout( checkbox1, { label: 'Selected checkbox', align: 'inline' } ),
7259 * new OO.ui.FieldLayout( checkbox2, { label: 'Unselected checkbox', align: 'inline' } ),
7260 * new OO.ui.FieldLayout( checkbox3, { label: 'Disabled checkbox', align: 'inline' } ),
7262 * $( 'body' ).append( fieldset.$element );
7264 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7267 * @extends OO.ui.InputWidget
7270 * @param {Object} [config] Configuration options
7271 * @cfg {boolean} [selected=false] Select the checkbox initially. By default, the checkbox is not selected.
7273 OO
.ui
.CheckboxInputWidget
= function OoUiCheckboxInputWidget( config
) {
7274 // Configuration initialization
7275 config
= config
|| {};
7277 // Parent constructor
7278 OO
.ui
.CheckboxInputWidget
.parent
.call( this, config
);
7282 .addClass( 'oo-ui-checkboxInputWidget' )
7283 // Required for pretty styling in MediaWiki theme
7284 .append( $( '<span>' ) );
7285 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
7290 OO
.inheritClass( OO
.ui
.CheckboxInputWidget
, OO
.ui
.InputWidget
);
7292 /* Static Methods */
7297 OO
.ui
.CheckboxInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7298 var state
= OO
.ui
.CheckboxInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7299 state
.checked
= config
.$input
.prop( 'checked' );
7309 OO
.ui
.CheckboxInputWidget
.prototype.getInputElement = function () {
7310 return $( '<input>' ).attr( 'type', 'checkbox' );
7316 OO
.ui
.CheckboxInputWidget
.prototype.onEdit = function () {
7318 if ( !this.isDisabled() ) {
7319 // Allow the stack to clear so the value will be updated
7320 setTimeout( function () {
7321 widget
.setSelected( widget
.$input
.prop( 'checked' ) );
7327 * Set selection state of this checkbox.
7329 * @param {boolean} state `true` for selected
7332 OO
.ui
.CheckboxInputWidget
.prototype.setSelected = function ( state
) {
7334 if ( this.selected
!== state
) {
7335 this.selected
= state
;
7336 this.$input
.prop( 'checked', this.selected
);
7337 this.emit( 'change', this.selected
);
7343 * Check if this checkbox is selected.
7345 * @return {boolean} Checkbox is selected
7347 OO
.ui
.CheckboxInputWidget
.prototype.isSelected = function () {
7348 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
7349 // it, and we won't know unless they're kind enough to trigger a 'change' event.
7350 var selected
= this.$input
.prop( 'checked' );
7351 if ( this.selected
!== selected
) {
7352 this.setSelected( selected
);
7354 return this.selected
;
7360 OO
.ui
.CheckboxInputWidget
.prototype.restorePreInfuseState = function ( state
) {
7361 OO
.ui
.CheckboxInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7362 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
7363 this.setSelected( state
.checked
);
7368 * DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget} intended to be used
7369 * within a HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
7370 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
7371 * more information about input widgets.
7373 * A DropdownInputWidget always has a value (one of the options is always selected), unless there
7374 * are no options. If no `value` configuration option is provided, the first option is selected.
7375 * If you need a state representing no value (no option being selected), use a DropdownWidget.
7377 * This and OO.ui.RadioSelectInputWidget support the same configuration options.
7380 * // Example: A DropdownInputWidget with three options
7381 * var dropdownInput = new OO.ui.DropdownInputWidget( {
7383 * { data: 'a', label: 'First' },
7384 * { data: 'b', label: 'Second'},
7385 * { data: 'c', label: 'Third' }
7388 * $( 'body' ).append( dropdownInput.$element );
7390 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7393 * @extends OO.ui.InputWidget
7394 * @mixins OO.ui.mixin.TitledElement
7397 * @param {Object} [config] Configuration options
7398 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
7399 * @cfg {Object} [dropdown] Configuration options for {@link OO.ui.DropdownWidget DropdownWidget}
7401 OO
.ui
.DropdownInputWidget
= function OoUiDropdownInputWidget( config
) {
7402 // Configuration initialization
7403 config
= config
|| {};
7405 // See InputWidget#reusePreInfuseDOM about config.$input
7406 if ( config
.$input
) {
7407 config
.$input
.addClass( 'oo-ui-element-hidden' );
7410 // Properties (must be done before parent constructor which calls #setDisabled)
7411 this.dropdownWidget
= new OO
.ui
.DropdownWidget( config
.dropdown
);
7413 // Parent constructor
7414 OO
.ui
.DropdownInputWidget
.parent
.call( this, config
);
7416 // Mixin constructors
7417 OO
.ui
.mixin
.TitledElement
.call( this, config
);
7420 this.dropdownWidget
.getMenu().connect( this, { select
: 'onMenuSelect' } );
7423 this.setOptions( config
.options
|| [] );
7425 .addClass( 'oo-ui-dropdownInputWidget' )
7426 .append( this.dropdownWidget
.$element
);
7431 OO
.inheritClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.InputWidget
);
7432 OO
.mixinClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.mixin
.TitledElement
);
7440 OO
.ui
.DropdownInputWidget
.prototype.getInputElement = function () {
7441 return $( '<input>' ).attr( 'type', 'hidden' );
7445 * Handles menu select events.
7448 * @param {OO.ui.MenuOptionWidget} item Selected menu item
7450 OO
.ui
.DropdownInputWidget
.prototype.onMenuSelect = function ( item
) {
7451 this.setValue( item
.getData() );
7457 OO
.ui
.DropdownInputWidget
.prototype.setValue = function ( value
) {
7458 value
= this.cleanUpValue( value
);
7459 this.dropdownWidget
.getMenu().selectItemByData( value
);
7460 OO
.ui
.DropdownInputWidget
.parent
.prototype.setValue
.call( this, value
);
7467 OO
.ui
.DropdownInputWidget
.prototype.setDisabled = function ( state
) {
7468 this.dropdownWidget
.setDisabled( state
);
7469 OO
.ui
.DropdownInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7474 * Set the options available for this input.
7476 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
7479 OO
.ui
.DropdownInputWidget
.prototype.setOptions = function ( options
) {
7481 value
= this.getValue(),
7484 // Rebuild the dropdown menu
7485 this.dropdownWidget
.getMenu()
7487 .addItems( options
.map( function ( opt
) {
7488 var optValue
= widget
.cleanUpValue( opt
.data
);
7489 return new OO
.ui
.MenuOptionWidget( {
7491 label
: opt
.label
!== undefined ? opt
.label
: optValue
7495 // Restore the previous value, or reset to something sensible
7496 if ( this.dropdownWidget
.getMenu().getItemFromData( value
) ) {
7497 // Previous value is still available, ensure consistency with the dropdown
7498 this.setValue( value
);
7500 // No longer valid, reset
7501 if ( options
.length
) {
7502 this.setValue( options
[ 0 ].data
);
7512 OO
.ui
.DropdownInputWidget
.prototype.focus = function () {
7513 this.dropdownWidget
.getMenu().toggle( true );
7520 OO
.ui
.DropdownInputWidget
.prototype.blur = function () {
7521 this.dropdownWidget
.getMenu().toggle( false );
7526 * RadioInputWidget creates a single radio button. Because radio buttons are usually used as a set,
7527 * in most cases you will want to use a {@link OO.ui.RadioSelectWidget radio select}
7528 * with {@link OO.ui.RadioOptionWidget radio options} instead of this class. For more information,
7529 * please see the [OOjs UI documentation on MediaWiki][1].
7531 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
7534 * // An example of selected, unselected, and disabled radio inputs
7535 * var radio1 = new OO.ui.RadioInputWidget( {
7539 * var radio2 = new OO.ui.RadioInputWidget( {
7542 * var radio3 = new OO.ui.RadioInputWidget( {
7546 * // Create a fieldset layout with fields for each radio button.
7547 * var fieldset = new OO.ui.FieldsetLayout( {
7548 * label: 'Radio inputs'
7550 * fieldset.addItems( [
7551 * new OO.ui.FieldLayout( radio1, { label: 'Selected', align: 'inline' } ),
7552 * new OO.ui.FieldLayout( radio2, { label: 'Unselected', align: 'inline' } ),
7553 * new OO.ui.FieldLayout( radio3, { label: 'Disabled', align: 'inline' } ),
7555 * $( 'body' ).append( fieldset.$element );
7557 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7560 * @extends OO.ui.InputWidget
7563 * @param {Object} [config] Configuration options
7564 * @cfg {boolean} [selected=false] Select the radio button initially. By default, the radio button is not selected.
7566 OO
.ui
.RadioInputWidget
= function OoUiRadioInputWidget( config
) {
7567 // Configuration initialization
7568 config
= config
|| {};
7570 // Parent constructor
7571 OO
.ui
.RadioInputWidget
.parent
.call( this, config
);
7575 .addClass( 'oo-ui-radioInputWidget' )
7576 // Required for pretty styling in MediaWiki theme
7577 .append( $( '<span>' ) );
7578 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
7583 OO
.inheritClass( OO
.ui
.RadioInputWidget
, OO
.ui
.InputWidget
);
7585 /* Static Methods */
7590 OO
.ui
.RadioInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7591 var state
= OO
.ui
.RadioInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7592 state
.checked
= config
.$input
.prop( 'checked' );
7602 OO
.ui
.RadioInputWidget
.prototype.getInputElement = function () {
7603 return $( '<input>' ).attr( 'type', 'radio' );
7609 OO
.ui
.RadioInputWidget
.prototype.onEdit = function () {
7610 // RadioInputWidget doesn't track its state.
7614 * Set selection state of this radio button.
7616 * @param {boolean} state `true` for selected
7619 OO
.ui
.RadioInputWidget
.prototype.setSelected = function ( state
) {
7620 // RadioInputWidget doesn't track its state.
7621 this.$input
.prop( 'checked', state
);
7626 * Check if this radio button is selected.
7628 * @return {boolean} Radio is selected
7630 OO
.ui
.RadioInputWidget
.prototype.isSelected = function () {
7631 return this.$input
.prop( 'checked' );
7637 OO
.ui
.RadioInputWidget
.prototype.restorePreInfuseState = function ( state
) {
7638 OO
.ui
.RadioInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7639 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
7640 this.setSelected( state
.checked
);
7645 * RadioSelectInputWidget is a {@link OO.ui.RadioSelectWidget RadioSelectWidget} intended to be used
7646 * within a HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
7647 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
7648 * more information about input widgets.
7650 * This and OO.ui.DropdownInputWidget support the same configuration options.
7653 * // Example: A RadioSelectInputWidget with three options
7654 * var radioSelectInput = new OO.ui.RadioSelectInputWidget( {
7656 * { data: 'a', label: 'First' },
7657 * { data: 'b', label: 'Second'},
7658 * { data: 'c', label: 'Third' }
7661 * $( 'body' ).append( radioSelectInput.$element );
7663 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7666 * @extends OO.ui.InputWidget
7669 * @param {Object} [config] Configuration options
7670 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
7672 OO
.ui
.RadioSelectInputWidget
= function OoUiRadioSelectInputWidget( config
) {
7673 // Configuration initialization
7674 config
= config
|| {};
7676 // Properties (must be done before parent constructor which calls #setDisabled)
7677 this.radioSelectWidget
= new OO
.ui
.RadioSelectWidget();
7679 // Parent constructor
7680 OO
.ui
.RadioSelectInputWidget
.parent
.call( this, config
);
7683 this.radioSelectWidget
.connect( this, { select
: 'onMenuSelect' } );
7686 this.setOptions( config
.options
|| [] );
7688 .addClass( 'oo-ui-radioSelectInputWidget' )
7689 .append( this.radioSelectWidget
.$element
);
7694 OO
.inheritClass( OO
.ui
.RadioSelectInputWidget
, OO
.ui
.InputWidget
);
7696 /* Static Properties */
7698 OO
.ui
.RadioSelectInputWidget
.static.supportsSimpleLabel
= false;
7700 /* Static Methods */
7705 OO
.ui
.RadioSelectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7706 var state
= OO
.ui
.RadioSelectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7707 state
.value
= $( node
).find( '.oo-ui-radioInputWidget .oo-ui-inputWidget-input:checked' ).val();
7717 OO
.ui
.RadioSelectInputWidget
.prototype.getInputElement = function () {
7718 return $( '<input>' ).attr( 'type', 'hidden' );
7722 * Handles menu select events.
7725 * @param {OO.ui.RadioOptionWidget} item Selected menu item
7727 OO
.ui
.RadioSelectInputWidget
.prototype.onMenuSelect = function ( item
) {
7728 this.setValue( item
.getData() );
7734 OO
.ui
.RadioSelectInputWidget
.prototype.setValue = function ( value
) {
7735 value
= this.cleanUpValue( value
);
7736 this.radioSelectWidget
.selectItemByData( value
);
7737 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setValue
.call( this, value
);
7744 OO
.ui
.RadioSelectInputWidget
.prototype.setDisabled = function ( state
) {
7745 this.radioSelectWidget
.setDisabled( state
);
7746 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7751 * Set the options available for this input.
7753 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
7756 OO
.ui
.RadioSelectInputWidget
.prototype.setOptions = function ( options
) {
7758 value
= this.getValue(),
7761 // Rebuild the radioSelect menu
7762 this.radioSelectWidget
7764 .addItems( options
.map( function ( opt
) {
7765 var optValue
= widget
.cleanUpValue( opt
.data
);
7766 return new OO
.ui
.RadioOptionWidget( {
7768 label
: opt
.label
!== undefined ? opt
.label
: optValue
7772 // Restore the previous value, or reset to something sensible
7773 if ( this.radioSelectWidget
.getItemFromData( value
) ) {
7774 // Previous value is still available, ensure consistency with the radioSelect
7775 this.setValue( value
);
7777 // No longer valid, reset
7778 if ( options
.length
) {
7779 this.setValue( options
[ 0 ].data
);
7787 * TextInputWidgets, like HTML text inputs, can be configured with options that customize the
7788 * size of the field as well as its presentation. In addition, these widgets can be configured
7789 * with {@link OO.ui.mixin.IconElement icons}, {@link OO.ui.mixin.IndicatorElement indicators}, an optional
7790 * validation-pattern (used to determine if an input value is valid or not) and an input filter,
7791 * which modifies incoming values rather than validating them.
7792 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
7794 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
7797 * // Example of a text input widget
7798 * var textInput = new OO.ui.TextInputWidget( {
7799 * value: 'Text input'
7801 * $( 'body' ).append( textInput.$element );
7803 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7806 * @extends OO.ui.InputWidget
7807 * @mixins OO.ui.mixin.IconElement
7808 * @mixins OO.ui.mixin.IndicatorElement
7809 * @mixins OO.ui.mixin.PendingElement
7810 * @mixins OO.ui.mixin.LabelElement
7813 * @param {Object} [config] Configuration options
7814 * @cfg {string} [type='text'] The value of the HTML `type` attribute: 'text', 'password', 'search',
7815 * 'email', 'url' or 'date'. Ignored if `multiline` is true.
7817 * Some values of `type` result in additional behaviors:
7819 * - `search`: implies `icon: 'search'` and `indicator: 'clear'`; when clicked, the indicator
7820 * empties the text field
7821 * @cfg {string} [placeholder] Placeholder text
7822 * @cfg {boolean} [autofocus=false] Use an HTML `autofocus` attribute to
7823 * instruct the browser to focus this widget.
7824 * @cfg {boolean} [readOnly=false] Prevent changes to the value of the text input.
7825 * @cfg {number} [maxLength] Maximum number of characters allowed in the input.
7826 * @cfg {boolean} [multiline=false] Allow multiple lines of text
7827 * @cfg {number} [rows] If multiline, number of visible lines in textarea. If used with `autosize`,
7828 * specifies minimum number of rows to display.
7829 * @cfg {boolean} [autosize=false] Automatically resize the text input to fit its content.
7830 * Use the #maxRows config to specify a maximum number of displayed rows.
7831 * @cfg {boolean} [maxRows] Maximum number of rows to display when #autosize is set to true.
7832 * Defaults to the maximum of `10` and `2 * rows`, or `10` if `rows` isn't provided.
7833 * @cfg {string} [labelPosition='after'] The position of the inline label relative to that of
7834 * the value or placeholder text: `'before'` or `'after'`
7835 * @cfg {boolean} [required=false] Mark the field as required. Implies `indicator: 'required'`.
7836 * @cfg {boolean} [autocomplete=true] Should the browser support autocomplete for this field
7837 * @cfg {RegExp|Function|string} [validate] Validation pattern: when string, a symbolic name of a
7838 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer'
7839 * (the value must contain only numbers); when RegExp, a regular expression that must match the
7840 * value for it to be considered valid; when Function, a function receiving the value as parameter
7841 * that must return true, or promise resolving to true, for it to be considered valid.
7843 OO
.ui
.TextInputWidget
= function OoUiTextInputWidget( config
) {
7844 // Configuration initialization
7845 config
= $.extend( {
7847 labelPosition
: 'after'
7849 if ( config
.type
=== 'search' ) {
7850 if ( config
.icon
=== undefined ) {
7851 config
.icon
= 'search';
7853 // indicator: 'clear' is set dynamically later, depending on value
7855 if ( config
.required
) {
7856 if ( config
.indicator
=== undefined ) {
7857 config
.indicator
= 'required';
7861 // Parent constructor
7862 OO
.ui
.TextInputWidget
.parent
.call( this, config
);
7864 // Mixin constructors
7865 OO
.ui
.mixin
.IconElement
.call( this, config
);
7866 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7867 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$input
} ) );
7868 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7871 this.type
= this.getSaneType( config
);
7872 this.readOnly
= false;
7873 this.multiline
= !!config
.multiline
;
7874 this.autosize
= !!config
.autosize
;
7875 this.minRows
= config
.rows
!== undefined ? config
.rows
: '';
7876 this.maxRows
= config
.maxRows
|| Math
.max( 2 * ( this.minRows
|| 0 ), 10 );
7877 this.validate
= null;
7878 this.styleHeight
= null;
7879 this.scrollWidth
= null;
7881 // Clone for resizing
7882 if ( this.autosize
) {
7883 this.$clone
= this.$input
7885 .insertAfter( this.$input
)
7886 .attr( 'aria-hidden', 'true' )
7887 .addClass( 'oo-ui-element-hidden' );
7890 this.setValidation( config
.validate
);
7891 this.setLabelPosition( config
.labelPosition
);
7895 keypress
: this.onKeyPress
.bind( this ),
7896 blur
: this.onBlur
.bind( this )
7899 focus
: this.onElementAttach
.bind( this )
7901 this.$icon
.on( 'mousedown', this.onIconMouseDown
.bind( this ) );
7902 this.$indicator
.on( 'mousedown', this.onIndicatorMouseDown
.bind( this ) );
7903 this.on( 'labelChange', this.updatePosition
.bind( this ) );
7904 this.connect( this, {
7906 disable
: 'onDisable'
7911 .addClass( 'oo-ui-textInputWidget oo-ui-textInputWidget-type-' + this.type
)
7912 .append( this.$icon
, this.$indicator
);
7913 this.setReadOnly( !!config
.readOnly
);
7914 this.updateSearchIndicator();
7915 if ( config
.placeholder
!== undefined ) {
7916 this.$input
.attr( 'placeholder', config
.placeholder
);
7918 if ( config
.maxLength
!== undefined ) {
7919 this.$input
.attr( 'maxlength', config
.maxLength
);
7921 if ( config
.autofocus
) {
7922 this.$input
.attr( 'autofocus', 'autofocus' );
7924 if ( config
.required
) {
7925 this.$input
.attr( 'required', 'required' );
7926 this.$input
.attr( 'aria-required', 'true' );
7928 if ( config
.autocomplete
=== false ) {
7929 this.$input
.attr( 'autocomplete', 'off' );
7930 // Turning off autocompletion also disables "form caching" when the user navigates to a
7931 // different page and then clicks "Back". Re-enable it when leaving. Borrowed from jQuery UI.
7933 beforeunload: function () {
7934 this.$input
.removeAttr( 'autocomplete' );
7936 pageshow: function () {
7937 // Browsers don't seem to actually fire this event on "Back", they instead just reload the
7938 // whole page... it shouldn't hurt, though.
7939 this.$input
.attr( 'autocomplete', 'off' );
7943 if ( this.multiline
&& config
.rows
) {
7944 this.$input
.attr( 'rows', config
.rows
);
7946 if ( this.label
|| config
.autosize
) {
7947 this.installParentChangeDetector();
7953 OO
.inheritClass( OO
.ui
.TextInputWidget
, OO
.ui
.InputWidget
);
7954 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IconElement
);
7955 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
7956 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.PendingElement
);
7957 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.LabelElement
);
7959 /* Static Properties */
7961 OO
.ui
.TextInputWidget
.static.validationPatterns
= {
7966 /* Static Methods */
7971 OO
.ui
.TextInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7972 var state
= OO
.ui
.TextInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7973 if ( config
.multiline
) {
7974 state
.scrollTop
= config
.$input
.scrollTop();
7982 * An `enter` event is emitted when the user presses 'enter' inside the text box.
7984 * Not emitted if the input is multiline.
7990 * A `resize` event is emitted when autosize is set and the widget resizes
7998 * Handle icon mouse down events.
8001 * @param {jQuery.Event} e Mouse down event
8004 OO
.ui
.TextInputWidget
.prototype.onIconMouseDown = function ( e
) {
8005 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8006 this.$input
[ 0 ].focus();
8012 * Handle indicator mouse down events.
8015 * @param {jQuery.Event} e Mouse down event
8018 OO
.ui
.TextInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
8019 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8020 if ( this.type
=== 'search' ) {
8021 // Clear the text field
8022 this.setValue( '' );
8024 this.$input
[ 0 ].focus();
8030 * Handle key press events.
8033 * @param {jQuery.Event} e Key press event
8034 * @fires enter If enter key is pressed and input is not multiline
8036 OO
.ui
.TextInputWidget
.prototype.onKeyPress = function ( e
) {
8037 if ( e
.which
=== OO
.ui
.Keys
.ENTER
&& !this.multiline
) {
8038 this.emit( 'enter', e
);
8043 * Handle blur events.
8046 * @param {jQuery.Event} e Blur event
8048 OO
.ui
.TextInputWidget
.prototype.onBlur = function () {
8049 this.setValidityFlag();
8053 * Handle element attach events.
8056 * @param {jQuery.Event} e Element attach event
8058 OO
.ui
.TextInputWidget
.prototype.onElementAttach = function () {
8059 // Any previously calculated size is now probably invalid if we reattached elsewhere
8060 this.valCache
= null;
8062 this.positionLabel();
8066 * Handle change events.
8068 * @param {string} value
8071 OO
.ui
.TextInputWidget
.prototype.onChange = function () {
8072 this.updateSearchIndicator();
8073 this.setValidityFlag();
8078 * Handle disable events.
8080 * @param {boolean} disabled Element is disabled
8083 OO
.ui
.TextInputWidget
.prototype.onDisable = function () {
8084 this.updateSearchIndicator();
8088 * Check if the input is {@link #readOnly read-only}.
8092 OO
.ui
.TextInputWidget
.prototype.isReadOnly = function () {
8093 return this.readOnly
;
8097 * Set the {@link #readOnly read-only} state of the input.
8099 * @param {boolean} state Make input read-only
8102 OO
.ui
.TextInputWidget
.prototype.setReadOnly = function ( state
) {
8103 this.readOnly
= !!state
;
8104 this.$input
.prop( 'readOnly', this.readOnly
);
8105 this.updateSearchIndicator();
8110 * Support function for making #onElementAttach work across browsers.
8112 * This whole function could be replaced with one line of code using the DOMNodeInsertedIntoDocument
8113 * event, but it's not supported by Firefox and allegedly deprecated, so we only use it as fallback.
8115 * Due to MutationObserver performance woes, #onElementAttach is only somewhat reliably called the
8116 * first time that the element gets attached to the documented.
8118 OO
.ui
.TextInputWidget
.prototype.installParentChangeDetector = function () {
8119 var mutationObserver
, onRemove
, topmostNode
, fakeParentNode
,
8120 MutationObserver
= window
.MutationObserver
|| window
.WebKitMutationObserver
|| window
.MozMutationObserver
,
8123 if ( MutationObserver
) {
8124 // The new way. If only it wasn't so ugly.
8126 if ( this.$element
.closest( 'html' ).length
) {
8127 // Widget is attached already, do nothing. This breaks the functionality of this function when
8128 // the widget is detached and reattached. Alas, doing this correctly with MutationObserver
8129 // would require observation of the whole document, which would hurt performance of other,
8130 // more important code.
8134 // Find topmost node in the tree
8135 topmostNode
= this.$element
[ 0 ];
8136 while ( topmostNode
.parentNode
) {
8137 topmostNode
= topmostNode
.parentNode
;
8140 // We have no way to detect the $element being attached somewhere without observing the entire
8141 // DOM with subtree modifications, which would hurt performance. So we cheat: we hook to the
8142 // parent node of $element, and instead detect when $element is removed from it (and thus
8143 // probably attached somewhere else). If there is no parent, we create a "fake" one. If it
8144 // doesn't get attached, we end up back here and create the parent.
8146 mutationObserver
= new MutationObserver( function ( mutations
) {
8147 var i
, j
, removedNodes
;
8148 for ( i
= 0; i
< mutations
.length
; i
++ ) {
8149 removedNodes
= mutations
[ i
].removedNodes
;
8150 for ( j
= 0; j
< removedNodes
.length
; j
++ ) {
8151 if ( removedNodes
[ j
] === topmostNode
) {
8152 setTimeout( onRemove
, 0 );
8159 onRemove = function () {
8160 // If the node was attached somewhere else, report it
8161 if ( widget
.$element
.closest( 'html' ).length
) {
8162 widget
.onElementAttach();
8164 mutationObserver
.disconnect();
8165 widget
.installParentChangeDetector();
8168 // Create a fake parent and observe it
8169 fakeParentNode
= $( '<div>' ).append( topmostNode
)[ 0 ];
8170 mutationObserver
.observe( fakeParentNode
, { childList
: true } );
8172 // Using the DOMNodeInsertedIntoDocument event is much nicer and less magical, and works for
8173 // detachment and reattachment, but it's not supported by Firefox and allegedly deprecated.
8174 this.$element
.on( 'DOMNodeInsertedIntoDocument', this.onElementAttach
.bind( this ) );
8179 * Automatically adjust the size of the text input.
8181 * This only affects #multiline inputs that are {@link #autosize autosized}.
8186 OO
.ui
.TextInputWidget
.prototype.adjustSize = function () {
8187 var scrollHeight
, innerHeight
, outerHeight
, maxInnerHeight
, measurementError
,
8188 idealHeight
, newHeight
, scrollWidth
, property
;
8190 if ( this.multiline
&& this.$input
.val() !== this.valCache
) {
8191 if ( this.autosize
) {
8193 .val( this.$input
.val() )
8194 .attr( 'rows', this.minRows
)
8195 // Set inline height property to 0 to measure scroll height
8196 .css( 'height', 0 );
8198 this.$clone
.removeClass( 'oo-ui-element-hidden' );
8200 this.valCache
= this.$input
.val();
8202 scrollHeight
= this.$clone
[ 0 ].scrollHeight
;
8204 // Remove inline height property to measure natural heights
8205 this.$clone
.css( 'height', '' );
8206 innerHeight
= this.$clone
.innerHeight();
8207 outerHeight
= this.$clone
.outerHeight();
8209 // Measure max rows height
8211 .attr( 'rows', this.maxRows
)
8212 .css( 'height', 'auto' )
8214 maxInnerHeight
= this.$clone
.innerHeight();
8216 // Difference between reported innerHeight and scrollHeight with no scrollbars present.
8217 // This is sometimes non-zero on Blink-based browsers, depending on zoom level.
8218 measurementError
= maxInnerHeight
- this.$clone
[ 0 ].scrollHeight
;
8219 idealHeight
= Math
.min( maxInnerHeight
, scrollHeight
+ measurementError
);
8221 this.$clone
.addClass( 'oo-ui-element-hidden' );
8223 // Only apply inline height when expansion beyond natural height is needed
8224 // Use the difference between the inner and outer height as a buffer
8225 newHeight
= idealHeight
> innerHeight
? idealHeight
+ ( outerHeight
- innerHeight
) : '';
8226 if ( newHeight
!== this.styleHeight
) {
8227 this.$input
.css( 'height', newHeight
);
8228 this.styleHeight
= newHeight
;
8229 this.emit( 'resize' );
8232 scrollWidth
= this.$input
[ 0 ].offsetWidth
- this.$input
[ 0 ].clientWidth
;
8233 if ( scrollWidth
!== this.scrollWidth
) {
8234 property
= this.$element
.css( 'direction' ) === 'rtl' ? 'left' : 'right';
8236 this.$label
.css( { right
: '', left
: '' } );
8237 this.$indicator
.css( { right
: '', left
: '' } );
8239 if ( scrollWidth
) {
8240 this.$indicator
.css( property
, scrollWidth
);
8241 if ( this.labelPosition
=== 'after' ) {
8242 this.$label
.css( property
, scrollWidth
);
8246 this.scrollWidth
= scrollWidth
;
8247 this.positionLabel();
8257 OO
.ui
.TextInputWidget
.prototype.getInputElement = function ( config
) {
8258 return config
.multiline
?
8260 $( '<input>' ).attr( 'type', this.getSaneType( config
) );
8264 * Get sanitized value for 'type' for given config.
8266 * @param {Object} config Configuration options
8267 * @return {string|null}
8270 OO
.ui
.TextInputWidget
.prototype.getSaneType = function ( config
) {
8271 var type
= [ 'text', 'password', 'search', 'email', 'url', 'date' ].indexOf( config
.type
) !== -1 ?
8274 return config
.multiline
? 'multiline' : type
;
8278 * Check if the input supports multiple lines.
8282 OO
.ui
.TextInputWidget
.prototype.isMultiline = function () {
8283 return !!this.multiline
;
8287 * Check if the input automatically adjusts its size.
8291 OO
.ui
.TextInputWidget
.prototype.isAutosizing = function () {
8292 return !!this.autosize
;
8296 * Focus the input and select a specified range within the text.
8298 * @param {number} from Select from offset
8299 * @param {number} [to] Select to offset, defaults to from
8302 OO
.ui
.TextInputWidget
.prototype.selectRange = function ( from, to
) {
8303 var isBackwards
, start
, end
,
8304 input
= this.$input
[ 0 ];
8308 isBackwards
= to
< from;
8309 start
= isBackwards
? to
: from;
8310 end
= isBackwards
? from : to
;
8315 input
.setSelectionRange( start
, end
, isBackwards
? 'backward' : 'forward' );
8317 // IE throws an exception if you call setSelectionRange on a unattached DOM node.
8318 // Rather than expensively check if the input is attached every time, just check
8319 // if it was the cause of an error being thrown. If not, rethrow the error.
8320 if ( this.getElementDocument().body
.contains( input
) ) {
8328 * Get an object describing the current selection range in a directional manner
8330 * @return {Object} Object containing 'from' and 'to' offsets
8332 OO
.ui
.TextInputWidget
.prototype.getRange = function () {
8333 var input
= this.$input
[ 0 ],
8334 start
= input
.selectionStart
,
8335 end
= input
.selectionEnd
,
8336 isBackwards
= input
.selectionDirection
=== 'backward';
8339 from: isBackwards
? end
: start
,
8340 to
: isBackwards
? start
: end
8345 * Get the length of the text input value.
8347 * This could differ from the length of #getValue if the
8348 * value gets filtered
8350 * @return {number} Input length
8352 OO
.ui
.TextInputWidget
.prototype.getInputLength = function () {
8353 return this.$input
[ 0 ].value
.length
;
8357 * Focus the input and select the entire text.
8361 OO
.ui
.TextInputWidget
.prototype.select = function () {
8362 return this.selectRange( 0, this.getInputLength() );
8366 * Focus the input and move the cursor to the start.
8370 OO
.ui
.TextInputWidget
.prototype.moveCursorToStart = function () {
8371 return this.selectRange( 0 );
8375 * Focus the input and move the cursor to the end.
8379 OO
.ui
.TextInputWidget
.prototype.moveCursorToEnd = function () {
8380 return this.selectRange( this.getInputLength() );
8384 * Insert new content into the input.
8386 * @param {string} content Content to be inserted
8389 OO
.ui
.TextInputWidget
.prototype.insertContent = function ( content
) {
8391 range
= this.getRange(),
8392 value
= this.getValue();
8394 start
= Math
.min( range
.from, range
.to
);
8395 end
= Math
.max( range
.from, range
.to
);
8397 this.setValue( value
.slice( 0, start
) + content
+ value
.slice( end
) );
8398 this.selectRange( start
+ content
.length
);
8403 * Insert new content either side of a selection.
8405 * @param {string} pre Content to be inserted before the selection
8406 * @param {string} post Content to be inserted after the selection
8409 OO
.ui
.TextInputWidget
.prototype.encapsulateContent = function ( pre
, post
) {
8411 range
= this.getRange(),
8412 offset
= pre
.length
;
8414 start
= Math
.min( range
.from, range
.to
);
8415 end
= Math
.max( range
.from, range
.to
);
8417 this.selectRange( start
).insertContent( pre
);
8418 this.selectRange( offset
+ end
).insertContent( post
);
8420 this.selectRange( offset
+ start
, offset
+ end
);
8425 * Set the validation pattern.
8427 * The validation pattern is either a regular expression, a function, or the symbolic name of a
8428 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer' (the
8429 * value must contain only numbers).
8431 * @param {RegExp|Function|string|null} validate Regular expression, function, or the symbolic name
8432 * of a pattern (either ‘integer’ or ‘non-empty’) defined by the class.
8434 OO
.ui
.TextInputWidget
.prototype.setValidation = function ( validate
) {
8435 if ( validate
instanceof RegExp
|| validate
instanceof Function
) {
8436 this.validate
= validate
;
8438 this.validate
= this.constructor.static.validationPatterns
[ validate
] || /.*/;
8443 * Sets the 'invalid' flag appropriately.
8445 * @param {boolean} [isValid] Optionally override validation result
8447 OO
.ui
.TextInputWidget
.prototype.setValidityFlag = function ( isValid
) {
8449 setFlag = function ( valid
) {
8451 widget
.$input
.attr( 'aria-invalid', 'true' );
8453 widget
.$input
.removeAttr( 'aria-invalid' );
8455 widget
.setFlags( { invalid
: !valid
} );
8458 if ( isValid
!== undefined ) {
8461 this.getValidity().then( function () {
8470 * Check if a value is valid.
8472 * This method returns a promise that resolves with a boolean `true` if the current value is
8473 * considered valid according to the supplied {@link #validate validation pattern}.
8475 * @deprecated since v0.12.3
8476 * @return {jQuery.Promise} A promise that resolves to a boolean `true` if the value is valid.
8478 OO
.ui
.TextInputWidget
.prototype.isValid = function () {
8481 if ( this.validate
instanceof Function
) {
8482 result
= this.validate( this.getValue() );
8483 if ( result
&& $.isFunction( result
.promise
) ) {
8484 return result
.promise();
8486 return $.Deferred().resolve( !!result
).promise();
8489 return $.Deferred().resolve( !!this.getValue().match( this.validate
) ).promise();
8494 * Get the validity of current value.
8496 * This method returns a promise that resolves if the value is valid and rejects if
8497 * it isn't. Uses the {@link #validate validation pattern} to check for validity.
8499 * @return {jQuery.Promise} A promise that resolves if the value is valid, rejects if not.
8501 OO
.ui
.TextInputWidget
.prototype.getValidity = function () {
8504 function rejectOrResolve( valid
) {
8506 return $.Deferred().resolve().promise();
8508 return $.Deferred().reject().promise();
8512 if ( this.validate
instanceof Function
) {
8513 result
= this.validate( this.getValue() );
8514 if ( result
&& $.isFunction( result
.promise
) ) {
8515 return result
.promise().then( function ( valid
) {
8516 return rejectOrResolve( valid
);
8519 return rejectOrResolve( result
);
8522 return rejectOrResolve( this.getValue().match( this.validate
) );
8527 * Set the position of the inline label relative to that of the value: `‘before’` or `‘after’`.
8529 * @param {string} labelPosition Label position, 'before' or 'after'
8532 OO
.ui
.TextInputWidget
.prototype.setLabelPosition = function ( labelPosition
) {
8533 this.labelPosition
= labelPosition
;
8535 // If there is no label and we only change the position, #updatePosition is a no-op,
8536 // but it takes really a lot of work to do nothing.
8537 this.updatePosition();
8543 * Update the position of the inline label.
8545 * This method is called by #setLabelPosition, and can also be called on its own if
8546 * something causes the label to be mispositioned.
8550 OO
.ui
.TextInputWidget
.prototype.updatePosition = function () {
8551 var after
= this.labelPosition
=== 'after';
8554 .toggleClass( 'oo-ui-textInputWidget-labelPosition-after', !!this.label
&& after
)
8555 .toggleClass( 'oo-ui-textInputWidget-labelPosition-before', !!this.label
&& !after
);
8557 this.valCache
= null;
8558 this.scrollWidth
= null;
8560 this.positionLabel();
8566 * Update the 'clear' indicator displayed on type: 'search' text fields, hiding it when the field is
8567 * already empty or when it's not editable.
8569 OO
.ui
.TextInputWidget
.prototype.updateSearchIndicator = function () {
8570 if ( this.type
=== 'search' ) {
8571 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
8572 this.setIndicator( null );
8574 this.setIndicator( 'clear' );
8580 * Position the label by setting the correct padding on the input.
8585 OO
.ui
.TextInputWidget
.prototype.positionLabel = function () {
8586 var after
, rtl
, property
;
8589 // Clear old values if present
8591 'padding-right': '',
8596 this.$element
.append( this.$label
);
8598 this.$label
.detach();
8602 after
= this.labelPosition
=== 'after';
8603 rtl
= this.$element
.css( 'direction' ) === 'rtl';
8604 property
= after
=== rtl
? 'padding-left' : 'padding-right';
8606 this.$input
.css( property
, this.$label
.outerWidth( true ) + ( after
? this.scrollWidth
: 0 ) );
8614 OO
.ui
.TextInputWidget
.prototype.restorePreInfuseState = function ( state
) {
8615 OO
.ui
.TextInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8616 if ( state
.scrollTop
!== undefined ) {
8617 this.$input
.scrollTop( state
.scrollTop
);
8622 * ComboBoxInputWidgets combine a {@link OO.ui.TextInputWidget text input} (where a value
8623 * can be entered manually) and a {@link OO.ui.MenuSelectWidget menu of options} (from which
8624 * a value can be chosen instead). Users can choose options from the combo box in one of two ways:
8626 * - by typing a value in the text input field. If the value exactly matches the value of a menu
8627 * option, that option will appear to be selected.
8628 * - by choosing a value from the menu. The value of the chosen option will then appear in the text
8631 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
8633 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
8636 * // Example: A ComboBoxInputWidget.
8637 * var comboBox = new OO.ui.ComboBoxInputWidget( {
8638 * label: 'ComboBoxInputWidget',
8639 * value: 'Option 1',
8642 * new OO.ui.MenuOptionWidget( {
8644 * label: 'Option One'
8646 * new OO.ui.MenuOptionWidget( {
8648 * label: 'Option Two'
8650 * new OO.ui.MenuOptionWidget( {
8652 * label: 'Option Three'
8654 * new OO.ui.MenuOptionWidget( {
8656 * label: 'Option Four'
8658 * new OO.ui.MenuOptionWidget( {
8660 * label: 'Option Five'
8665 * $( 'body' ).append( comboBox.$element );
8667 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
8670 * @extends OO.ui.TextInputWidget
8673 * @param {Object} [config] Configuration options
8674 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8675 * @cfg {Object} [menu] Configuration options to pass to the {@link OO.ui.FloatingMenuSelectWidget menu select widget}.
8676 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
8677 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
8678 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
8680 OO
.ui
.ComboBoxInputWidget
= function OoUiComboBoxInputWidget( config
) {
8681 // Configuration initialization
8682 config
= $.extend( {
8685 // For backwards-compatibility with ComboBoxWidget config
8686 $.extend( config
, config
.input
);
8688 // Parent constructor
8689 OO
.ui
.ComboBoxInputWidget
.parent
.call( this, config
);
8692 this.$overlay
= config
.$overlay
|| this.$element
;
8693 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend(
8697 $container
: this.$element
,
8698 disabled
: this.isDisabled()
8702 // For backwards-compatibility with ComboBoxWidget
8706 this.$indicator
.on( {
8707 click
: this.onIndicatorClick
.bind( this ),
8708 keypress
: this.onIndicatorKeyPress
.bind( this )
8710 this.connect( this, {
8711 change
: 'onInputChange',
8712 enter
: 'onInputEnter'
8714 this.menu
.connect( this, {
8715 choose
: 'onMenuChoose',
8716 add
: 'onMenuItemsChange',
8717 remove
: 'onMenuItemsChange'
8723 'aria-autocomplete': 'list'
8725 // Do not override options set via config.menu.items
8726 if ( config
.options
!== undefined ) {
8727 this.setOptions( config
.options
);
8729 // Extra class for backwards-compatibility with ComboBoxWidget
8730 this.$element
.addClass( 'oo-ui-comboBoxInputWidget oo-ui-comboBoxWidget' );
8731 this.$overlay
.append( this.menu
.$element
);
8732 this.onMenuItemsChange();
8737 OO
.inheritClass( OO
.ui
.ComboBoxInputWidget
, OO
.ui
.TextInputWidget
);
8742 * Get the combobox's menu.
8744 * @return {OO.ui.FloatingMenuSelectWidget} Menu widget
8746 OO
.ui
.ComboBoxInputWidget
.prototype.getMenu = function () {
8751 * Get the combobox's text input widget.
8753 * @return {OO.ui.TextInputWidget} Text input widget
8755 OO
.ui
.ComboBoxInputWidget
.prototype.getInput = function () {
8760 * Handle input change events.
8763 * @param {string} value New value
8765 OO
.ui
.ComboBoxInputWidget
.prototype.onInputChange = function ( value
) {
8766 var match
= this.menu
.getItemFromData( value
);
8768 this.menu
.selectItem( match
);
8769 if ( this.menu
.getHighlightedItem() ) {
8770 this.menu
.highlightItem( match
);
8773 if ( !this.isDisabled() ) {
8774 this.menu
.toggle( true );
8779 * Handle mouse click events.
8782 * @param {jQuery.Event} e Mouse click event
8784 OO
.ui
.ComboBoxInputWidget
.prototype.onIndicatorClick = function ( e
) {
8785 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8787 this.$input
[ 0 ].focus();
8793 * Handle key press events.
8796 * @param {jQuery.Event} e Key press event
8798 OO
.ui
.ComboBoxInputWidget
.prototype.onIndicatorKeyPress = function ( e
) {
8799 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
8801 this.$input
[ 0 ].focus();
8807 * Handle input enter events.
8811 OO
.ui
.ComboBoxInputWidget
.prototype.onInputEnter = function () {
8812 if ( !this.isDisabled() ) {
8813 this.menu
.toggle( false );
8818 * Handle menu choose events.
8821 * @param {OO.ui.OptionWidget} item Chosen item
8823 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuChoose = function ( item
) {
8824 this.setValue( item
.getData() );
8828 * Handle menu item change events.
8832 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuItemsChange = function () {
8833 var match
= this.menu
.getItemFromData( this.getValue() );
8834 this.menu
.selectItem( match
);
8835 if ( this.menu
.getHighlightedItem() ) {
8836 this.menu
.highlightItem( match
);
8838 this.$element
.toggleClass( 'oo-ui-comboBoxInputWidget-empty', this.menu
.isEmpty() );
8844 OO
.ui
.ComboBoxInputWidget
.prototype.setDisabled = function ( disabled
) {
8846 OO
.ui
.ComboBoxInputWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
8849 this.menu
.setDisabled( this.isDisabled() );
8856 * Set the options available for this input.
8858 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
8861 OO
.ui
.ComboBoxInputWidget
.prototype.setOptions = function ( options
) {
8864 .addItems( options
.map( function ( opt
) {
8865 return new OO
.ui
.MenuOptionWidget( {
8867 label
: opt
.label
!== undefined ? opt
.label
: opt
.data
8876 * @deprecated since 0.13.2; use OO.ui.ComboBoxInputWidget instead
8878 OO
.ui
.ComboBoxWidget
= OO
.ui
.ComboBoxInputWidget
;
8881 * FieldLayouts are used with OO.ui.FieldsetLayout. Each FieldLayout requires a field-widget,
8882 * which is a widget that is specified by reference before any optional configuration settings.
8884 * Field layouts can be configured with help text and/or labels. Labels are aligned in one of four ways:
8886 * - **left**: The label is placed before the field-widget and aligned with the left margin.
8887 * A left-alignment is used for forms with many fields.
8888 * - **right**: The label is placed before the field-widget and aligned to the right margin.
8889 * A right-alignment is used for long but familiar forms which users tab through,
8890 * verifying the current field with a quick glance at the label.
8891 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
8892 * that users fill out from top to bottom.
8893 * - **inline**: The label is placed after the field-widget and aligned to the left.
8894 * An inline-alignment is best used with checkboxes or radio buttons.
8896 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout.
8897 * Please see the [OOjs UI documentation on MediaWiki] [1] for examples and more information.
8899 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
8902 * @extends OO.ui.Layout
8903 * @mixins OO.ui.mixin.LabelElement
8904 * @mixins OO.ui.mixin.TitledElement
8907 * @param {OO.ui.Widget} fieldWidget Field widget
8908 * @param {Object} [config] Configuration options
8909 * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top' or 'inline'
8910 * @cfg {Array} [errors] Error messages about the widget, which will be displayed below the widget.
8911 * The array may contain strings or OO.ui.HtmlSnippet instances.
8912 * @cfg {Array} [notices] Notices about the widget, which will be displayed below the widget.
8913 * The array may contain strings or OO.ui.HtmlSnippet instances.
8914 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
8915 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
8916 * For important messages, you are advised to use `notices`, as they are always shown.
8918 * @throws {Error} An error is thrown if no widget is specified
8920 OO
.ui
.FieldLayout
= function OoUiFieldLayout( fieldWidget
, config
) {
8921 var hasInputWidget
, div
;
8923 // Allow passing positional parameters inside the config object
8924 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
8925 config
= fieldWidget
;
8926 fieldWidget
= config
.fieldWidget
;
8929 // Make sure we have required constructor arguments
8930 if ( fieldWidget
=== undefined ) {
8931 throw new Error( 'Widget not found' );
8934 hasInputWidget
= fieldWidget
.constructor.static.supportsSimpleLabel
;
8936 // Configuration initialization
8937 config
= $.extend( { align
: 'left' }, config
);
8939 // Parent constructor
8940 OO
.ui
.FieldLayout
.parent
.call( this, config
);
8942 // Mixin constructors
8943 OO
.ui
.mixin
.LabelElement
.call( this, config
);
8944 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
8947 this.fieldWidget
= fieldWidget
;
8950 this.$field
= $( '<div>' );
8951 this.$messages
= $( '<ul>' );
8952 this.$body
= $( '<' + ( hasInputWidget
? 'label' : 'div' ) + '>' );
8954 if ( config
.help
) {
8955 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
8956 classes
: [ 'oo-ui-fieldLayout-help' ],
8962 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
8963 div
.html( config
.help
.toString() );
8965 div
.text( config
.help
);
8967 this.popupButtonWidget
.getPopup().$body
.append(
8968 div
.addClass( 'oo-ui-fieldLayout-help-content' )
8970 this.$help
= this.popupButtonWidget
.$element
;
8972 this.$help
= $( [] );
8976 if ( hasInputWidget
) {
8977 this.$label
.on( 'click', this.onLabelClick
.bind( this ) );
8979 this.fieldWidget
.connect( this, { disable
: 'onFieldDisable' } );
8983 .addClass( 'oo-ui-fieldLayout' )
8984 .append( this.$help
, this.$body
);
8985 this.$body
.addClass( 'oo-ui-fieldLayout-body' );
8986 this.$messages
.addClass( 'oo-ui-fieldLayout-messages' );
8988 .addClass( 'oo-ui-fieldLayout-field' )
8989 .toggleClass( 'oo-ui-fieldLayout-disable', this.fieldWidget
.isDisabled() )
8990 .append( this.fieldWidget
.$element
);
8992 this.setErrors( config
.errors
|| [] );
8993 this.setNotices( config
.notices
|| [] );
8994 this.setAlignment( config
.align
);
8999 OO
.inheritClass( OO
.ui
.FieldLayout
, OO
.ui
.Layout
);
9000 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.LabelElement
);
9001 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.TitledElement
);
9006 * Handle field disable events.
9009 * @param {boolean} value Field is disabled
9011 OO
.ui
.FieldLayout
.prototype.onFieldDisable = function ( value
) {
9012 this.$element
.toggleClass( 'oo-ui-fieldLayout-disabled', value
);
9016 * Handle label mouse click events.
9019 * @param {jQuery.Event} e Mouse click event
9021 OO
.ui
.FieldLayout
.prototype.onLabelClick = function () {
9022 this.fieldWidget
.simulateLabelClick();
9027 * Get the widget contained by the field.
9029 * @return {OO.ui.Widget} Field widget
9031 OO
.ui
.FieldLayout
.prototype.getField = function () {
9032 return this.fieldWidget
;
9037 * @param {string} kind 'error' or 'notice'
9038 * @param {string|OO.ui.HtmlSnippet} text
9041 OO
.ui
.FieldLayout
.prototype.makeMessage = function ( kind
, text
) {
9042 var $listItem
, $icon
, message
;
9043 $listItem
= $( '<li>' );
9044 if ( kind
=== 'error' ) {
9045 $icon
= new OO
.ui
.IconWidget( { icon
: 'alert', flags
: [ 'warning' ] } ).$element
;
9046 } else if ( kind
=== 'notice' ) {
9047 $icon
= new OO
.ui
.IconWidget( { icon
: 'info' } ).$element
;
9051 message
= new OO
.ui
.LabelWidget( { label
: text
} );
9053 .append( $icon
, message
.$element
)
9054 .addClass( 'oo-ui-fieldLayout-messages-' + kind
);
9059 * Set the field alignment mode.
9062 * @param {string} value Alignment mode, either 'left', 'right', 'top' or 'inline'
9065 OO
.ui
.FieldLayout
.prototype.setAlignment = function ( value
) {
9066 if ( value
!== this.align
) {
9067 // Default to 'left'
9068 if ( [ 'left', 'right', 'top', 'inline' ].indexOf( value
) === -1 ) {
9072 if ( value
=== 'inline' ) {
9073 this.$body
.append( this.$field
, this.$label
);
9075 this.$body
.append( this.$label
, this.$field
);
9077 // Set classes. The following classes can be used here:
9078 // * oo-ui-fieldLayout-align-left
9079 // * oo-ui-fieldLayout-align-right
9080 // * oo-ui-fieldLayout-align-top
9081 // * oo-ui-fieldLayout-align-inline
9083 this.$element
.removeClass( 'oo-ui-fieldLayout-align-' + this.align
);
9085 this.$element
.addClass( 'oo-ui-fieldLayout-align-' + value
);
9093 * Set the list of error messages.
9095 * @param {Array} errors Error messages about the widget, which will be displayed below the widget.
9096 * The array may contain strings or OO.ui.HtmlSnippet instances.
9099 OO
.ui
.FieldLayout
.prototype.setErrors = function ( errors
) {
9100 this.errors
= errors
.slice();
9101 this.updateMessages();
9106 * Set the list of notice messages.
9108 * @param {Array} notices Notices about the widget, which will be displayed below the widget.
9109 * The array may contain strings or OO.ui.HtmlSnippet instances.
9112 OO
.ui
.FieldLayout
.prototype.setNotices = function ( notices
) {
9113 this.notices
= notices
.slice();
9114 this.updateMessages();
9119 * Update the rendering of error and notice messages.
9123 OO
.ui
.FieldLayout
.prototype.updateMessages = function () {
9125 this.$messages
.empty();
9127 if ( this.errors
.length
|| this.notices
.length
) {
9128 this.$body
.after( this.$messages
);
9130 this.$messages
.remove();
9134 for ( i
= 0; i
< this.notices
.length
; i
++ ) {
9135 this.$messages
.append( this.makeMessage( 'notice', this.notices
[ i
] ) );
9137 for ( i
= 0; i
< this.errors
.length
; i
++ ) {
9138 this.$messages
.append( this.makeMessage( 'error', this.errors
[ i
] ) );
9143 * ActionFieldLayouts are used with OO.ui.FieldsetLayout. The layout consists of a field-widget, a button,
9144 * and an optional label and/or help text. The field-widget (e.g., a {@link OO.ui.TextInputWidget TextInputWidget}),
9145 * is required and is specified before any optional configuration settings.
9147 * Labels can be aligned in one of four ways:
9149 * - **left**: The label is placed before the field-widget and aligned with the left margin.
9150 * A left-alignment is used for forms with many fields.
9151 * - **right**: The label is placed before the field-widget and aligned to the right margin.
9152 * A right-alignment is used for long but familiar forms which users tab through,
9153 * verifying the current field with a quick glance at the label.
9154 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
9155 * that users fill out from top to bottom.
9156 * - **inline**: The label is placed after the field-widget and aligned to the left.
9157 * An inline-alignment is best used with checkboxes or radio buttons.
9159 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout when help
9160 * text is specified.
9163 * // Example of an ActionFieldLayout
9164 * var actionFieldLayout = new OO.ui.ActionFieldLayout(
9165 * new OO.ui.TextInputWidget( {
9166 * placeholder: 'Field widget'
9168 * new OO.ui.ButtonWidget( {
9172 * label: 'An ActionFieldLayout. This label is aligned top',
9174 * help: 'This is help text'
9178 * $( 'body' ).append( actionFieldLayout.$element );
9181 * @extends OO.ui.FieldLayout
9184 * @param {OO.ui.Widget} fieldWidget Field widget
9185 * @param {OO.ui.ButtonWidget} buttonWidget Button widget
9187 OO
.ui
.ActionFieldLayout
= function OoUiActionFieldLayout( fieldWidget
, buttonWidget
, config
) {
9188 // Allow passing positional parameters inside the config object
9189 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
9190 config
= fieldWidget
;
9191 fieldWidget
= config
.fieldWidget
;
9192 buttonWidget
= config
.buttonWidget
;
9195 // Parent constructor
9196 OO
.ui
.ActionFieldLayout
.parent
.call( this, fieldWidget
, config
);
9199 this.buttonWidget
= buttonWidget
;
9200 this.$button
= $( '<div>' );
9201 this.$input
= $( '<div>' );
9205 .addClass( 'oo-ui-actionFieldLayout' );
9207 .addClass( 'oo-ui-actionFieldLayout-button' )
9208 .append( this.buttonWidget
.$element
);
9210 .addClass( 'oo-ui-actionFieldLayout-input' )
9211 .append( this.fieldWidget
.$element
);
9213 .append( this.$input
, this.$button
);
9218 OO
.inheritClass( OO
.ui
.ActionFieldLayout
, OO
.ui
.FieldLayout
);
9221 * FieldsetLayouts are composed of one or more {@link OO.ui.FieldLayout FieldLayouts},
9222 * which each contain an individual widget and, optionally, a label. Each Fieldset can be
9223 * configured with a label as well. For more information and examples,
9224 * please see the [OOjs UI documentation on MediaWiki][1].
9227 * // Example of a fieldset layout
9228 * var input1 = new OO.ui.TextInputWidget( {
9229 * placeholder: 'A text input field'
9232 * var input2 = new OO.ui.TextInputWidget( {
9233 * placeholder: 'A text input field'
9236 * var fieldset = new OO.ui.FieldsetLayout( {
9237 * label: 'Example of a fieldset layout'
9240 * fieldset.addItems( [
9241 * new OO.ui.FieldLayout( input1, {
9242 * label: 'Field One'
9244 * new OO.ui.FieldLayout( input2, {
9245 * label: 'Field Two'
9248 * $( 'body' ).append( fieldset.$element );
9250 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
9253 * @extends OO.ui.Layout
9254 * @mixins OO.ui.mixin.IconElement
9255 * @mixins OO.ui.mixin.LabelElement
9256 * @mixins OO.ui.mixin.GroupElement
9259 * @param {Object} [config] Configuration options
9260 * @cfg {OO.ui.FieldLayout[]} [items] An array of fields to add to the fieldset. See OO.ui.FieldLayout for more information about fields.
9262 OO
.ui
.FieldsetLayout
= function OoUiFieldsetLayout( config
) {
9263 // Configuration initialization
9264 config
= config
|| {};
9266 // Parent constructor
9267 OO
.ui
.FieldsetLayout
.parent
.call( this, config
);
9269 // Mixin constructors
9270 OO
.ui
.mixin
.IconElement
.call( this, config
);
9271 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9272 OO
.ui
.mixin
.GroupElement
.call( this, config
);
9274 if ( config
.help
) {
9275 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
9276 classes
: [ 'oo-ui-fieldsetLayout-help' ],
9281 this.popupButtonWidget
.getPopup().$body
.append(
9283 .text( config
.help
)
9284 .addClass( 'oo-ui-fieldsetLayout-help-content' )
9286 this.$help
= this.popupButtonWidget
.$element
;
9288 this.$help
= $( [] );
9293 .addClass( 'oo-ui-fieldsetLayout' )
9294 .prepend( this.$help
, this.$icon
, this.$label
, this.$group
);
9295 if ( Array
.isArray( config
.items
) ) {
9296 this.addItems( config
.items
);
9302 OO
.inheritClass( OO
.ui
.FieldsetLayout
, OO
.ui
.Layout
);
9303 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.IconElement
);
9304 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.LabelElement
);
9305 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.GroupElement
);
9308 * FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts} when you intend to use browser-based
9309 * form submission for the fields instead of handling them in JavaScript. Form layouts can be configured with an
9310 * HTML form action, an encoding type, and a method using the #action, #enctype, and #method configs, respectively.
9311 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
9313 * Only widgets from the {@link OO.ui.InputWidget InputWidget} family support form submission. It
9314 * includes standard form elements like {@link OO.ui.CheckboxInputWidget checkboxes}, {@link
9315 * OO.ui.RadioInputWidget radio buttons} and {@link OO.ui.TextInputWidget text fields}, as well as
9316 * some fancier controls. Some controls have both regular and InputWidget variants, for example
9317 * OO.ui.DropdownWidget and OO.ui.DropdownInputWidget – only the latter support form submission and
9318 * often have simplified APIs to match the capabilities of HTML forms.
9319 * See the [OOjs UI Inputs documentation on MediaWiki] [2] for more information about InputWidgets.
9321 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Forms
9322 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
9325 * // Example of a form layout that wraps a fieldset layout
9326 * var input1 = new OO.ui.TextInputWidget( {
9327 * placeholder: 'Username'
9329 * var input2 = new OO.ui.TextInputWidget( {
9330 * placeholder: 'Password',
9333 * var submit = new OO.ui.ButtonInputWidget( {
9337 * var fieldset = new OO.ui.FieldsetLayout( {
9338 * label: 'A form layout'
9340 * fieldset.addItems( [
9341 * new OO.ui.FieldLayout( input1, {
9342 * label: 'Username',
9345 * new OO.ui.FieldLayout( input2, {
9346 * label: 'Password',
9349 * new OO.ui.FieldLayout( submit )
9351 * var form = new OO.ui.FormLayout( {
9352 * items: [ fieldset ],
9353 * action: '/api/formhandler',
9356 * $( 'body' ).append( form.$element );
9359 * @extends OO.ui.Layout
9360 * @mixins OO.ui.mixin.GroupElement
9363 * @param {Object} [config] Configuration options
9364 * @cfg {string} [method] HTML form `method` attribute
9365 * @cfg {string} [action] HTML form `action` attribute
9366 * @cfg {string} [enctype] HTML form `enctype` attribute
9367 * @cfg {OO.ui.FieldsetLayout[]} [items] Fieldset layouts to add to the form layout.
9369 OO
.ui
.FormLayout
= function OoUiFormLayout( config
) {
9372 // Configuration initialization
9373 config
= config
|| {};
9375 // Parent constructor
9376 OO
.ui
.FormLayout
.parent
.call( this, config
);
9378 // Mixin constructors
9379 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
9382 this.$element
.on( 'submit', this.onFormSubmit
.bind( this ) );
9384 // Make sure the action is safe
9385 action
= config
.action
;
9386 if ( action
!== undefined && !OO
.ui
.isSafeUrl( action
) ) {
9387 action
= './' + action
;
9392 .addClass( 'oo-ui-formLayout' )
9394 method
: config
.method
,
9396 enctype
: config
.enctype
9398 if ( Array
.isArray( config
.items
) ) {
9399 this.addItems( config
.items
);
9405 OO
.inheritClass( OO
.ui
.FormLayout
, OO
.ui
.Layout
);
9406 OO
.mixinClass( OO
.ui
.FormLayout
, OO
.ui
.mixin
.GroupElement
);
9411 * A 'submit' event is emitted when the form is submitted.
9416 /* Static Properties */
9418 OO
.ui
.FormLayout
.static.tagName
= 'form';
9423 * Handle form submit events.
9426 * @param {jQuery.Event} e Submit event
9429 OO
.ui
.FormLayout
.prototype.onFormSubmit = function () {
9430 if ( this.emit( 'submit' ) ) {
9436 * PanelLayouts expand to cover the entire area of their parent. They can be configured with scrolling, padding,
9437 * and a frame, and are often used together with {@link OO.ui.StackLayout StackLayouts}.
9440 * // Example of a panel layout
9441 * var panel = new OO.ui.PanelLayout( {
9445 * $content: $( '<p>A panel layout with padding and a frame.</p>' )
9447 * $( 'body' ).append( panel.$element );
9450 * @extends OO.ui.Layout
9453 * @param {Object} [config] Configuration options
9454 * @cfg {boolean} [scrollable=false] Allow vertical scrolling
9455 * @cfg {boolean} [padded=false] Add padding between the content and the edges of the panel.
9456 * @cfg {boolean} [expanded=true] Expand the panel to fill the entire parent element.
9457 * @cfg {boolean} [framed=false] Render the panel with a frame to visually separate it from outside content.
9459 OO
.ui
.PanelLayout
= function OoUiPanelLayout( config
) {
9460 // Configuration initialization
9461 config
= $.extend( {
9468 // Parent constructor
9469 OO
.ui
.PanelLayout
.parent
.call( this, config
);
9472 this.$element
.addClass( 'oo-ui-panelLayout' );
9473 if ( config
.scrollable
) {
9474 this.$element
.addClass( 'oo-ui-panelLayout-scrollable' );
9476 if ( config
.padded
) {
9477 this.$element
.addClass( 'oo-ui-panelLayout-padded' );
9479 if ( config
.expanded
) {
9480 this.$element
.addClass( 'oo-ui-panelLayout-expanded' );
9482 if ( config
.framed
) {
9483 this.$element
.addClass( 'oo-ui-panelLayout-framed' );
9489 OO
.inheritClass( OO
.ui
.PanelLayout
, OO
.ui
.Layout
);
9494 * Focus the panel layout
9496 * The default implementation just focuses the first focusable element in the panel
9498 OO
.ui
.PanelLayout
.prototype.focus = function () {
9499 OO
.ui
.findFocusable( this.$element
).focus();
9503 * HorizontalLayout arranges its contents in a single line (using `display: inline-block` for its
9504 * items), with small margins between them. Convenient when you need to put a number of block-level
9505 * widgets on a single line next to each other.
9507 * Note that inline elements, such as OO.ui.ButtonWidgets, do not need this wrapper.
9510 * // HorizontalLayout with a text input and a label
9511 * var layout = new OO.ui.HorizontalLayout( {
9513 * new OO.ui.LabelWidget( { label: 'Label' } ),
9514 * new OO.ui.TextInputWidget( { value: 'Text' } )
9517 * $( 'body' ).append( layout.$element );
9520 * @extends OO.ui.Layout
9521 * @mixins OO.ui.mixin.GroupElement
9524 * @param {Object} [config] Configuration options
9525 * @cfg {OO.ui.Widget[]|OO.ui.Layout[]} [items] Widgets or other layouts to add to the layout.
9527 OO
.ui
.HorizontalLayout
= function OoUiHorizontalLayout( config
) {
9528 // Configuration initialization
9529 config
= config
|| {};
9531 // Parent constructor
9532 OO
.ui
.HorizontalLayout
.parent
.call( this, config
);
9534 // Mixin constructors
9535 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
9538 this.$element
.addClass( 'oo-ui-horizontalLayout' );
9539 if ( Array
.isArray( config
.items
) ) {
9540 this.addItems( config
.items
);
9546 OO
.inheritClass( OO
.ui
.HorizontalLayout
, OO
.ui
.Layout
);
9547 OO
.mixinClass( OO
.ui
.HorizontalLayout
, OO
.ui
.mixin
.GroupElement
);