3 * https://www.mediawiki.org/wiki/OOUI
5 * Copyright 2011–2018 OOUI Team and other contributors.
6 * Released under the MIT license
7 * http://oojs.mit-license.org
9 * Date: 2018-10-08T22:42:55Z
16 * Namespace for all classes, static methods and static properties.
48 * Constants for MouseEvent.which
52 OO
.ui
.MouseButtons
= {
65 * Generate a unique ID for element
69 OO
.ui
.generateElementId = function () {
71 return 'ooui-' + OO
.ui
.elementId
;
75 * Check if an element is focusable.
76 * Inspired by :focusable in jQueryUI v1.11.4 - 2015-04-14
78 * @param {jQuery} $element Element to test
79 * @return {boolean} Element is focusable
81 OO
.ui
.isFocusableElement = function ( $element
) {
83 element
= $element
[ 0 ];
85 // Anything disabled is not focusable
86 if ( element
.disabled
) {
90 // Check if the element is visible
92 // This is quicker than calling $element.is( ':visible' )
93 $.expr
.pseudos
.visible( element
) &&
94 // Check that all parents are visible
95 !$element
.parents().addBack().filter( function () {
96 return $.css( this, 'visibility' ) === 'hidden';
102 // Check if the element is ContentEditable, which is the string 'true'
103 if ( element
.contentEditable
=== 'true' ) {
107 // Anything with a non-negative numeric tabIndex is focusable.
108 // Use .prop to avoid browser bugs
109 if ( $element
.prop( 'tabIndex' ) >= 0 ) {
113 // Some element types are naturally focusable
114 // (indexOf is much faster than regex in Chrome and about the
115 // same in FF: https://jsperf.com/regex-vs-indexof-array2)
116 nodeName
= element
.nodeName
.toLowerCase();
117 if ( [ 'input', 'select', 'textarea', 'button', 'object' ].indexOf( nodeName
) !== -1 ) {
121 // Links and areas are focusable if they have an href
122 if ( ( nodeName
=== 'a' || nodeName
=== 'area' ) && $element
.attr( 'href' ) !== undefined ) {
130 * Find a focusable child
132 * @param {jQuery} $container Container to search in
133 * @param {boolean} [backwards] Search backwards
134 * @return {jQuery} Focusable child, or an empty jQuery object if none found
136 OO
.ui
.findFocusable = function ( $container
, backwards
) {
137 var $focusable
= $( [] ),
138 // $focusableCandidates is a superset of things that
139 // could get matched by isFocusableElement
140 $focusableCandidates
= $container
141 .find( 'input, select, textarea, button, object, a, area, [contenteditable], [tabindex]' );
144 $focusableCandidates
= Array
.prototype.reverse
.call( $focusableCandidates
);
147 $focusableCandidates
.each( function () {
148 var $this = $( this );
149 if ( OO
.ui
.isFocusableElement( $this ) ) {
158 * Get the user's language and any fallback languages.
160 * These language codes are used to localize user interface elements in the user's language.
162 * In environments that provide a localization system, this function should be overridden to
163 * return the user's language(s). The default implementation returns English (en) only.
165 * @return {string[]} Language codes, in descending order of priority
167 OO
.ui
.getUserLanguages = function () {
172 * Get a value in an object keyed by language code.
174 * @param {Object.<string,Mixed>} obj Object keyed by language code
175 * @param {string|null} [lang] Language code, if omitted or null defaults to any user language
176 * @param {string} [fallback] Fallback code, used if no matching language can be found
177 * @return {Mixed} Local value
179 OO
.ui
.getLocalValue = function ( obj
, lang
, fallback
) {
182 // Requested language
186 // Known user language
187 langs
= OO
.ui
.getUserLanguages();
188 for ( i
= 0, len
= langs
.length
; i
< len
; i
++ ) {
195 if ( obj
[ fallback
] ) {
196 return obj
[ fallback
];
198 // First existing language
199 for ( lang
in obj
) {
207 * Check if a node is contained within another node
209 * Similar to jQuery#contains except a list of containers can be supplied
210 * and a boolean argument allows you to include the container in the match list
212 * @param {HTMLElement|HTMLElement[]} containers Container node(s) to search in
213 * @param {HTMLElement} contained Node to find
214 * @param {boolean} [matchContainers] Include the container(s) in the list of nodes to match, otherwise only match descendants
215 * @return {boolean} The node is in the list of target nodes
217 OO
.ui
.contains = function ( containers
, contained
, matchContainers
) {
219 if ( !Array
.isArray( containers
) ) {
220 containers
= [ containers
];
222 for ( i
= containers
.length
- 1; i
>= 0; i
-- ) {
223 if ( ( matchContainers
&& contained
=== containers
[ i
] ) || $.contains( containers
[ i
], contained
) ) {
231 * Return a function, that, as long as it continues to be invoked, will not
232 * be triggered. The function will be called after it stops being called for
233 * N milliseconds. If `immediate` is passed, trigger the function on the
234 * leading edge, instead of the trailing.
236 * Ported from: http://underscorejs.org/underscore.js
238 * @param {Function} func Function to debounce
239 * @param {number} [wait=0] Wait period in milliseconds
240 * @param {boolean} [immediate] Trigger on leading edge
241 * @return {Function} Debounced function
243 OO
.ui
.debounce = function ( func
, wait
, immediate
) {
248 later = function () {
251 func
.apply( context
, args
);
254 if ( immediate
&& !timeout
) {
255 func
.apply( context
, args
);
257 if ( !timeout
|| wait
) {
258 clearTimeout( timeout
);
259 timeout
= setTimeout( later
, wait
);
265 * Puts a console warning with provided message.
267 * @param {string} message Message
269 OO
.ui
.warnDeprecation = function ( message
) {
270 if ( OO
.getProp( window
, 'console', 'warn' ) !== undefined ) {
271 // eslint-disable-next-line no-console
272 console
.warn( message
);
277 * Returns a function, that, when invoked, will only be triggered at most once
278 * during a given window of time. If called again during that window, it will
279 * wait until the window ends and then trigger itself again.
281 * As it's not knowable to the caller whether the function will actually run
282 * when the wrapper is called, return values from the function are entirely
285 * @param {Function} func Function to throttle
286 * @param {number} wait Throttle window length, in milliseconds
287 * @return {Function} Throttled function
289 OO
.ui
.throttle = function ( func
, wait
) {
290 var context
, args
, timeout
,
294 previous
= OO
.ui
.now();
295 func
.apply( context
, args
);
298 // Check how long it's been since the last time the function was
299 // called, and whether it's more or less than the requested throttle
300 // period. If it's less, run the function immediately. If it's more,
301 // set a timeout for the remaining time -- but don't replace an
302 // existing timeout, since that'd indefinitely prolong the wait.
303 var remaining
= wait
- ( OO
.ui
.now() - previous
);
306 if ( remaining
<= 0 ) {
307 // Note: unless wait was ridiculously large, this means we'll
308 // automatically run the first time the function was called in a
309 // given period. (If you provide a wait period larger than the
310 // current Unix timestamp, you *deserve* unexpected behavior.)
311 clearTimeout( timeout
);
313 } else if ( !timeout
) {
314 timeout
= setTimeout( run
, remaining
);
320 * A (possibly faster) way to get the current timestamp as an integer
322 * @return {number} Current timestamp, in milliseconds since the Unix epoch
324 OO
.ui
.now
= Date
.now
|| function () {
325 return new Date().getTime();
329 * Reconstitute a JavaScript object corresponding to a widget created by
330 * the PHP implementation.
332 * This is an alias for `OO.ui.Element.static.infuse()`.
334 * @param {string|HTMLElement|jQuery} idOrNode
335 * A DOM id (if a string) or node for the widget to infuse.
336 * @param {Object} [config] Configuration options
337 * @return {OO.ui.Element}
338 * The `OO.ui.Element` corresponding to this (infusable) document node.
340 OO
.ui
.infuse = function ( idOrNode
, config
) {
341 return OO
.ui
.Element
.static.infuse( idOrNode
, config
);
346 * Message store for the default implementation of OO.ui.msg
348 * Environments that provide a localization system should not use this, but should override
349 * OO.ui.msg altogether.
354 // Tool tip for a button that moves items in a list down one place
355 'ooui-outline-control-move-down': 'Move item down',
356 // Tool tip for a button that moves items in a list up one place
357 'ooui-outline-control-move-up': 'Move item up',
358 // Tool tip for a button that removes items from a list
359 'ooui-outline-control-remove': 'Remove item',
360 // Label for the toolbar group that contains a list of all other available tools
361 'ooui-toolbar-more': 'More',
362 // Label for the fake tool that expands the full list of tools in a toolbar group
363 'ooui-toolgroup-expand': 'More',
364 // Label for the fake tool that collapses the full list of tools in a toolbar group
365 'ooui-toolgroup-collapse': 'Fewer',
366 // Default label for the tooltip for the button that removes a tag item
367 'ooui-item-remove': 'Remove',
368 // Default label for the accept button of a confirmation dialog
369 'ooui-dialog-message-accept': 'OK',
370 // Default label for the reject button of a confirmation dialog
371 'ooui-dialog-message-reject': 'Cancel',
372 // Title for process dialog error description
373 'ooui-dialog-process-error': 'Something went wrong',
374 // Label for process dialog dismiss error button, visible when describing errors
375 'ooui-dialog-process-dismiss': 'Dismiss',
376 // Label for process dialog retry action button, visible when describing only recoverable errors
377 'ooui-dialog-process-retry': 'Try again',
378 // Label for process dialog retry action button, visible when describing only warnings
379 'ooui-dialog-process-continue': 'Continue',
380 // Label for the file selection widget's select file button
381 'ooui-selectfile-button-select': 'Select a file',
382 // Label for the file selection widget if file selection is not supported
383 'ooui-selectfile-not-supported': 'File selection is not supported',
384 // Label for the file selection widget when no file is currently selected
385 'ooui-selectfile-placeholder': 'No file is selected',
386 // Label for the file selection widget's drop target
387 'ooui-selectfile-dragdrop-placeholder': 'Drop file here'
391 * Get a localized message.
393 * After the message key, message parameters may optionally be passed. In the default implementation,
394 * any occurrences of $1 are replaced with the first parameter, $2 with the second parameter, etc.
395 * Alternative implementations of OO.ui.msg may use any substitution system they like, as long as
396 * they support unnamed, ordered message parameters.
398 * In environments that provide a localization system, this function should be overridden to
399 * return the message translated in the user's language. The default implementation always returns
400 * English messages. An example of doing this with [jQuery.i18n](https://github.com/wikimedia/jquery.i18n)
404 * var i, iLen, button,
405 * messagePath = 'oojs-ui/dist/i18n/',
406 * languages = [ $.i18n().locale, 'ur', 'en' ],
409 * for ( i = 0, iLen = languages.length; i < iLen; i++ ) {
410 * languageMap[ languages[ i ] ] = messagePath + languages[ i ].toLowerCase() + '.json';
413 * $.i18n().load( languageMap ).done( function() {
414 * // Replace the built-in `msg` only once we've loaded the internationalization.
415 * // OOUI uses `OO.ui.deferMsg` for all initially-loaded messages. So long as
416 * // you put off creating any widgets until this promise is complete, no English
417 * // will be displayed.
418 * OO.ui.msg = $.i18n;
420 * // A button displaying "OK" in the default locale
421 * button = new OO.ui.ButtonWidget( {
422 * label: OO.ui.msg( 'ooui-dialog-message-accept' ),
425 * $( 'body' ).append( button.$element );
427 * // A button displaying "OK" in Urdu
428 * $.i18n().locale = 'ur';
429 * button = new OO.ui.ButtonWidget( {
430 * label: OO.ui.msg( 'ooui-dialog-message-accept' ),
433 * $( 'body' ).append( button.$element );
436 * @param {string} key Message key
437 * @param {...Mixed} [params] Message parameters
438 * @return {string} Translated message with parameters substituted
440 OO
.ui
.msg = function ( key
) {
441 var message
= messages
[ key
],
442 params
= Array
.prototype.slice
.call( arguments
, 1 );
443 if ( typeof message
=== 'string' ) {
444 // Perform $1 substitution
445 message
= message
.replace( /\$(\d+)/g, function ( unused
, n
) {
446 var i
= parseInt( n
, 10 );
447 return params
[ i
- 1 ] !== undefined ? params
[ i
- 1 ] : '$' + n
;
450 // Return placeholder if message not found
451 message
= '[' + key
+ ']';
458 * Package a message and arguments for deferred resolution.
460 * Use this when you are statically specifying a message and the message may not yet be present.
462 * @param {string} key Message key
463 * @param {...Mixed} [params] Message parameters
464 * @return {Function} Function that returns the resolved message when executed
466 OO
.ui
.deferMsg = function () {
467 var args
= arguments
;
469 return OO
.ui
.msg
.apply( OO
.ui
, args
);
476 * If the message is a function it will be executed, otherwise it will pass through directly.
478 * @param {Function|string} msg Deferred message, or message text
479 * @return {string} Resolved message
481 OO
.ui
.resolveMsg = function ( msg
) {
482 if ( $.isFunction( msg
) ) {
489 * @param {string} url
492 OO
.ui
.isSafeUrl = function ( url
) {
493 // Keep this function in sync with php/Tag.php
494 var i
, protocolWhitelist
;
496 function stringStartsWith( haystack
, needle
) {
497 return haystack
.substr( 0, needle
.length
) === needle
;
500 protocolWhitelist
= [
501 'bitcoin', 'ftp', 'ftps', 'geo', 'git', 'gopher', 'http', 'https', 'irc', 'ircs',
502 'magnet', 'mailto', 'mms', 'news', 'nntp', 'redis', 'sftp', 'sip', 'sips', 'sms', 'ssh',
503 'svn', 'tel', 'telnet', 'urn', 'worldwind', 'xmpp'
510 for ( i
= 0; i
< protocolWhitelist
.length
; i
++ ) {
511 if ( stringStartsWith( url
, protocolWhitelist
[ i
] + ':' ) ) {
516 // This matches '//' too
517 if ( stringStartsWith( url
, '/' ) || stringStartsWith( url
, './' ) ) {
520 if ( stringStartsWith( url
, '?' ) || stringStartsWith( url
, '#' ) ) {
528 * Check if the user has a 'mobile' device.
530 * For our purposes this means the user is primarily using an
531 * on-screen keyboard, touch input instead of a mouse and may
532 * have a physically small display.
534 * It is left up to implementors to decide how to compute this
535 * so the default implementation always returns false.
537 * @return {boolean} User is on a mobile device
539 OO
.ui
.isMobile = function () {
544 * Get the additional spacing that should be taken into account when displaying elements that are
545 * clipped to the viewport, e.g. dropdown menus and popups. This is meant to be overridden to avoid
546 * such menus overlapping any fixed headers/toolbars/navigation used by the site.
548 * @return {Object} Object with the properties 'top', 'right', 'bottom', 'left', each representing
549 * the extra spacing from that edge of viewport (in pixels)
551 OO
.ui
.getViewportSpacing = function () {
561 * Get the default overlay, which is used by various widgets when they are passed `$overlay: true`.
562 * See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
564 * @return {jQuery} Default overlay node
566 OO
.ui
.getDefaultOverlay = function () {
567 if ( !OO
.ui
.$defaultOverlay
) {
568 OO
.ui
.$defaultOverlay
= $( '<div>' ).addClass( 'oo-ui-defaultOverlay' );
569 $( 'body' ).append( OO
.ui
.$defaultOverlay
);
571 return OO
.ui
.$defaultOverlay
;
579 * Namespace for OOUI mixins.
581 * Mixins are named according to the type of object they are intended to
582 * be mixed in to. For example, OO.ui.mixin.GroupElement is intended to be
583 * mixed in to an instance of OO.ui.Element, and OO.ui.mixin.GroupWidget
584 * is intended to be mixed in to an instance of OO.ui.Widget.
592 * Each Element represents a rendering in the DOM—a button or an icon, for example, or anything
593 * that is visible to a user. Unlike {@link OO.ui.Widget widgets}, plain elements usually do not have events
594 * connected to them and can't be interacted with.
600 * @param {Object} [config] Configuration options
601 * @cfg {string[]} [classes] The names of the CSS classes to apply to the element. CSS styles are added
602 * to the top level (e.g., the outermost div) of the element. See the [OOUI documentation on MediaWiki][2]
604 * [2]: https://www.mediawiki.org/wiki/OOUI/Widgets/Buttons_and_Switches#cssExample
605 * @cfg {string} [id] The HTML id attribute used in the rendered tag.
606 * @cfg {string} [text] Text to insert
607 * @cfg {Array} [content] An array of content elements to append (after #text).
608 * Strings will be html-escaped; use an OO.ui.HtmlSnippet to append raw HTML.
609 * Instances of OO.ui.Element will have their $element appended.
610 * @cfg {jQuery} [$content] Content elements to append (after #text).
611 * @cfg {jQuery} [$element] Wrapper element. Defaults to a new element with #getTagName.
612 * @cfg {Mixed} [data] Custom data of any type or combination of types (e.g., string, number, array, object).
613 * Data can also be specified with the #setData method.
615 OO
.ui
.Element
= function OoUiElement( config
) {
616 if ( OO
.ui
.isDemo
) {
617 this.initialConfig
= config
;
619 // Configuration initialization
620 config
= config
|| {};
624 this.elementId
= null;
626 this.data
= config
.data
;
627 this.$element
= config
.$element
||
628 $( document
.createElement( this.getTagName() ) );
629 this.elementGroup
= null;
632 if ( Array
.isArray( config
.classes
) ) {
633 this.$element
.addClass( config
.classes
);
636 this.setElementId( config
.id
);
639 this.$element
.text( config
.text
);
641 if ( config
.content
) {
642 // The `content` property treats plain strings as text; use an
643 // HtmlSnippet to append HTML content. `OO.ui.Element`s get their
644 // appropriate $element appended.
645 this.$element
.append( config
.content
.map( function ( v
) {
646 if ( typeof v
=== 'string' ) {
647 // Escape string so it is properly represented in HTML.
648 return document
.createTextNode( v
);
649 } else if ( v
instanceof OO
.ui
.HtmlSnippet
) {
652 } else if ( v
instanceof OO
.ui
.Element
) {
658 if ( config
.$content
) {
659 // The `$content` property treats plain strings as HTML.
660 this.$element
.append( config
.$content
);
666 OO
.initClass( OO
.ui
.Element
);
668 /* Static Properties */
671 * The name of the HTML tag used by the element.
673 * The static value may be ignored if the #getTagName method is overridden.
679 OO
.ui
.Element
.static.tagName
= 'div';
684 * Reconstitute a JavaScript object corresponding to a widget created
685 * by the PHP implementation.
687 * @param {string|HTMLElement|jQuery} idOrNode
688 * A DOM id (if a string) or node for the widget to infuse.
689 * @param {Object} [config] Configuration options
690 * @return {OO.ui.Element}
691 * The `OO.ui.Element` corresponding to this (infusable) document node.
692 * For `Tag` objects emitted on the HTML side (used occasionally for content)
693 * the value returned is a newly-created Element wrapping around the existing
696 OO
.ui
.Element
.static.infuse = function ( idOrNode
, config
) {
697 var obj
= OO
.ui
.Element
.static.unsafeInfuse( idOrNode
, config
, false );
698 // Verify that the type matches up.
699 // FIXME: uncomment after T89721 is fixed, see T90929.
701 if ( !( obj instanceof this['class'] ) ) {
702 throw new Error( 'Infusion type mismatch!' );
709 * Implementation helper for `infuse`; skips the type check and has an
710 * extra property so that only the top-level invocation touches the DOM.
713 * @param {string|HTMLElement|jQuery} idOrNode
714 * @param {Object} [config] Configuration options
715 * @param {jQuery.Promise} [domPromise] A promise that will be resolved
716 * when the top-level widget of this infusion is inserted into DOM,
717 * replacing the original node; only used internally.
718 * @return {OO.ui.Element}
720 OO
.ui
.Element
.static.unsafeInfuse = function ( idOrNode
, config
, domPromise
) {
721 // look for a cached result of a previous infusion.
722 var id
, $elem
, error
, data
, cls
, parts
, parent
, obj
, top
, state
, infusedChildren
;
723 if ( typeof idOrNode
=== 'string' ) {
725 $elem
= $( document
.getElementById( id
) );
727 $elem
= $( idOrNode
);
728 id
= $elem
.attr( 'id' );
730 if ( !$elem
.length
) {
731 if ( typeof idOrNode
=== 'string' ) {
732 error
= 'Widget not found: ' + idOrNode
;
733 } else if ( idOrNode
&& idOrNode
.selector
) {
734 error
= 'Widget not found: ' + idOrNode
.selector
;
736 error
= 'Widget not found';
738 throw new Error( error
);
740 if ( $elem
[ 0 ].oouiInfused
) {
741 $elem
= $elem
[ 0 ].oouiInfused
;
743 data
= $elem
.data( 'ooui-infused' );
746 if ( data
=== true ) {
747 throw new Error( 'Circular dependency! ' + id
);
750 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
751 state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
752 // restore dynamic state after the new element is re-inserted into DOM under infused parent
753 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
754 infusedChildren
= $elem
.data( 'ooui-infused-children' );
755 if ( infusedChildren
&& infusedChildren
.length
) {
756 infusedChildren
.forEach( function ( data
) {
757 var state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
758 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
764 data
= $elem
.attr( 'data-ooui' );
766 throw new Error( 'No infusion data found: ' + id
);
769 data
= JSON
.parse( data
);
773 if ( !( data
&& data
._
) ) {
774 throw new Error( 'No valid infusion data found: ' + id
);
776 if ( data
._
=== 'Tag' ) {
777 // Special case: this is a raw Tag; wrap existing node, don't rebuild.
778 return new OO
.ui
.Element( $.extend( {}, config
, { $element
: $elem
} ) );
780 parts
= data
._
.split( '.' );
781 cls
= OO
.getProp
.apply( OO
, [ window
].concat( parts
) );
782 if ( cls
=== undefined ) {
783 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
786 // Verify that we're creating an OO.ui.Element instance
789 while ( parent
!== undefined ) {
790 if ( parent
=== OO
.ui
.Element
) {
795 parent
= parent
.parent
;
798 if ( parent
!== OO
.ui
.Element
) {
799 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
804 domPromise
= top
.promise();
806 $elem
.data( 'ooui-infused', true ); // prevent loops
807 data
.id
= id
; // implicit
808 infusedChildren
= [];
809 data
= OO
.copy( data
, null, function deserialize( value
) {
811 if ( OO
.isPlainObject( value
) ) {
813 infused
= OO
.ui
.Element
.static.unsafeInfuse( value
.tag
, config
, domPromise
);
814 infusedChildren
.push( infused
);
815 // Flatten the structure
816 infusedChildren
.push
.apply( infusedChildren
, infused
.$element
.data( 'ooui-infused-children' ) || [] );
817 infused
.$element
.removeData( 'ooui-infused-children' );
820 if ( value
.html
!== undefined ) {
821 return new OO
.ui
.HtmlSnippet( value
.html
);
825 // allow widgets to reuse parts of the DOM
826 data
= cls
.static.reusePreInfuseDOM( $elem
[ 0 ], data
);
827 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
828 state
= cls
.static.gatherPreInfuseState( $elem
[ 0 ], data
);
830 // eslint-disable-next-line new-cap
831 obj
= new cls( $.extend( {}, config
, data
) );
832 // If anyone is holding a reference to the old DOM element,
833 // let's allow them to OO.ui.infuse() it and do what they expect, see T105828.
834 // Do not use jQuery.data(), as using it on detached nodes leaks memory in 1.x line by design.
835 $elem
[ 0 ].oouiInfused
= obj
.$element
;
836 // now replace old DOM with this new DOM.
838 // An efficient constructor might be able to reuse the entire DOM tree of the original element,
839 // so only mutate the DOM if we need to.
840 if ( $elem
[ 0 ] !== obj
.$element
[ 0 ] ) {
841 $elem
.replaceWith( obj
.$element
);
845 obj
.$element
.data( 'ooui-infused', obj
);
846 obj
.$element
.data( 'ooui-infused-children', infusedChildren
);
847 // set the 'data-ooui' attribute so we can identify infused widgets
848 obj
.$element
.attr( 'data-ooui', '' );
849 // restore dynamic state after the new element is inserted into DOM
850 domPromise
.done( obj
.restorePreInfuseState
.bind( obj
, state
) );
855 * Pick out parts of `node`'s DOM to be reused when infusing a widget.
857 * This method **must not** make any changes to the DOM, only find interesting pieces and add them
858 * to `config` (which should then be returned). Actual DOM juggling should then be done by the
859 * constructor, which will be given the enhanced config.
862 * @param {HTMLElement} node
863 * @param {Object} config
866 OO
.ui
.Element
.static.reusePreInfuseDOM = function ( node
, config
) {
871 * Gather the dynamic state (focus, value of form inputs, scroll position, etc.) of an HTML DOM node
872 * (and its children) that represent an Element of the same class and the given configuration,
873 * generated by the PHP implementation.
875 * This method is called just before `node` is detached from the DOM. The return value of this
876 * function will be passed to #restorePreInfuseState after the newly created widget's #$element
877 * is inserted into DOM to replace `node`.
880 * @param {HTMLElement} node
881 * @param {Object} config
884 OO
.ui
.Element
.static.gatherPreInfuseState = function () {
889 * Get a jQuery function within a specific document.
892 * @param {jQuery|HTMLElement|HTMLDocument|Window} context Context to bind the function to
893 * @param {jQuery} [$iframe] HTML iframe element that contains the document, omit if document is
895 * @return {Function} Bound jQuery function
897 OO
.ui
.Element
.static.getJQuery = function ( context
, $iframe
) {
898 function wrapper( selector
) {
899 return $( selector
, wrapper
.context
);
902 wrapper
.context
= this.getDocument( context
);
905 wrapper
.$iframe
= $iframe
;
912 * Get the document of an element.
915 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Object to get the document for
916 * @return {HTMLDocument|null} Document object
918 OO
.ui
.Element
.static.getDocument = function ( obj
) {
919 // jQuery - selections created "offscreen" won't have a context, so .context isn't reliable
920 return ( obj
[ 0 ] && obj
[ 0 ].ownerDocument
) ||
921 // Empty jQuery selections might have a context
928 ( obj
.nodeType
=== Node
.DOCUMENT_NODE
&& obj
) ||
933 * Get the window of an element or document.
936 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the window for
937 * @return {Window} Window object
939 OO
.ui
.Element
.static.getWindow = function ( obj
) {
940 var doc
= this.getDocument( obj
);
941 return doc
.defaultView
;
945 * Get the direction of an element or document.
948 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the direction for
949 * @return {string} Text direction, either 'ltr' or 'rtl'
951 OO
.ui
.Element
.static.getDir = function ( obj
) {
954 if ( obj
instanceof jQuery
) {
957 isDoc
= obj
.nodeType
=== Node
.DOCUMENT_NODE
;
958 isWin
= obj
.document
!== undefined;
959 if ( isDoc
|| isWin
) {
965 return $( obj
).css( 'direction' );
969 * Get the offset between two frames.
971 * TODO: Make this function not use recursion.
974 * @param {Window} from Window of the child frame
975 * @param {Window} [to=window] Window of the parent frame
976 * @param {Object} [offset] Offset to start with, used internally
977 * @return {Object} Offset object, containing left and top properties
979 OO
.ui
.Element
.static.getFrameOffset = function ( from, to
, offset
) {
980 var i
, len
, frames
, frame
, rect
;
986 offset
= { top
: 0, left
: 0 };
988 if ( from.parent
=== from ) {
992 // Get iframe element
993 frames
= from.parent
.document
.getElementsByTagName( 'iframe' );
994 for ( i
= 0, len
= frames
.length
; i
< len
; i
++ ) {
995 if ( frames
[ i
].contentWindow
=== from ) {
1001 // Recursively accumulate offset values
1003 rect
= frame
.getBoundingClientRect();
1004 offset
.left
+= rect
.left
;
1005 offset
.top
+= rect
.top
;
1006 if ( from !== to
) {
1007 this.getFrameOffset( from.parent
, offset
);
1014 * Get the offset between two elements.
1016 * The two elements may be in a different frame, but in that case the frame $element is in must
1017 * be contained in the frame $anchor is in.
1020 * @param {jQuery} $element Element whose position to get
1021 * @param {jQuery} $anchor Element to get $element's position relative to
1022 * @return {Object} Translated position coordinates, containing top and left properties
1024 OO
.ui
.Element
.static.getRelativePosition = function ( $element
, $anchor
) {
1025 var iframe
, iframePos
,
1026 pos
= $element
.offset(),
1027 anchorPos
= $anchor
.offset(),
1028 elementDocument
= this.getDocument( $element
),
1029 anchorDocument
= this.getDocument( $anchor
);
1031 // If $element isn't in the same document as $anchor, traverse up
1032 while ( elementDocument
!== anchorDocument
) {
1033 iframe
= elementDocument
.defaultView
.frameElement
;
1035 throw new Error( '$element frame is not contained in $anchor frame' );
1037 iframePos
= $( iframe
).offset();
1038 pos
.left
+= iframePos
.left
;
1039 pos
.top
+= iframePos
.top
;
1040 elementDocument
= iframe
.ownerDocument
;
1042 pos
.left
-= anchorPos
.left
;
1043 pos
.top
-= anchorPos
.top
;
1048 * Get element border sizes.
1051 * @param {HTMLElement} el Element to measure
1052 * @return {Object} Dimensions object with `top`, `left`, `bottom` and `right` properties
1054 OO
.ui
.Element
.static.getBorders = function ( el
) {
1055 var doc
= el
.ownerDocument
,
1056 win
= doc
.defaultView
,
1057 style
= win
.getComputedStyle( el
, null ),
1059 top
= parseFloat( style
? style
.borderTopWidth
: $el
.css( 'borderTopWidth' ) ) || 0,
1060 left
= parseFloat( style
? style
.borderLeftWidth
: $el
.css( 'borderLeftWidth' ) ) || 0,
1061 bottom
= parseFloat( style
? style
.borderBottomWidth
: $el
.css( 'borderBottomWidth' ) ) || 0,
1062 right
= parseFloat( style
? style
.borderRightWidth
: $el
.css( 'borderRightWidth' ) ) || 0;
1073 * Get dimensions of an element or window.
1076 * @param {HTMLElement|Window} el Element to measure
1077 * @return {Object} Dimensions object with `borders`, `scroll`, `scrollbar` and `rect` properties
1079 OO
.ui
.Element
.static.getDimensions = function ( el
) {
1081 doc
= el
.ownerDocument
|| el
.document
,
1082 win
= doc
.defaultView
;
1084 if ( win
=== el
|| el
=== doc
.documentElement
) {
1087 borders
: { top
: 0, left
: 0, bottom
: 0, right
: 0 },
1089 top
: $win
.scrollTop(),
1090 left
: $win
.scrollLeft()
1092 scrollbar
: { right
: 0, bottom
: 0 },
1096 bottom
: $win
.innerHeight(),
1097 right
: $win
.innerWidth()
1103 borders
: this.getBorders( el
),
1105 top
: $el
.scrollTop(),
1106 left
: $el
.scrollLeft()
1109 right
: $el
.innerWidth() - el
.clientWidth
,
1110 bottom
: $el
.innerHeight() - el
.clientHeight
1112 rect
: el
.getBoundingClientRect()
1118 * Get the number of pixels that an element's content is scrolled to the left.
1120 * Adapted from <https://github.com/othree/jquery.rtl-scroll-type>.
1121 * Original code copyright 2012 Wei-Ko Kao, licensed under the MIT License.
1123 * This function smooths out browser inconsistencies (nicely described in the README at
1124 * <https://github.com/othree/jquery.rtl-scroll-type>) and produces a result consistent
1125 * with Firefox's 'scrollLeft', which seems the sanest.
1129 * @param {HTMLElement|Window} el Element to measure
1130 * @return {number} Scroll position from the left.
1131 * If the element's direction is LTR, this is a positive number between `0` (initial scroll position)
1132 * and `el.scrollWidth - el.clientWidth` (furthest possible scroll position).
1133 * If the element's direction is RTL, this is a negative number between `0` (initial scroll position)
1134 * and `-el.scrollWidth + el.clientWidth` (furthest possible scroll position).
1136 OO
.ui
.Element
.static.getScrollLeft
= ( function () {
1137 var rtlScrollType
= null;
1140 var $definer
= $( '<div dir="rtl" style="font-size: 14px; width: 1px; height: 1px; position: absolute; top: -1000px; overflow: scroll">A</div>' ),
1141 definer
= $definer
[ 0 ];
1143 $definer
.appendTo( 'body' );
1144 if ( definer
.scrollLeft
> 0 ) {
1146 rtlScrollType
= 'default';
1148 definer
.scrollLeft
= 1;
1149 if ( definer
.scrollLeft
=== 0 ) {
1150 // Firefox, old Opera
1151 rtlScrollType
= 'negative';
1153 // Internet Explorer, Edge
1154 rtlScrollType
= 'reverse';
1160 return function getScrollLeft( el
) {
1161 var isRoot
= el
.window
=== el
||
1162 el
=== el
.ownerDocument
.body
||
1163 el
=== el
.ownerDocument
.documentElement
,
1164 scrollLeft
= isRoot
? $( window
).scrollLeft() : el
.scrollLeft
,
1165 // All browsers use the correct scroll type ('negative') on the root, so don't
1166 // do any fixups when looking at the root element
1167 direction
= isRoot
? 'ltr' : $( el
).css( 'direction' );
1169 if ( direction
=== 'rtl' ) {
1170 if ( rtlScrollType
=== null ) {
1173 if ( rtlScrollType
=== 'reverse' ) {
1174 scrollLeft
= -scrollLeft
;
1175 } else if ( rtlScrollType
=== 'default' ) {
1176 scrollLeft
= scrollLeft
- el
.scrollWidth
+ el
.clientWidth
;
1185 * Get the root scrollable element of given element's document.
1187 * On Blink-based browsers (Chrome etc.), `document.documentElement` can't be used to get or set
1188 * the scrollTop property; instead we have to use `document.body`. Changing and testing the value
1189 * lets us use 'body' or 'documentElement' based on what is working.
1191 * https://code.google.com/p/chromium/issues/detail?id=303131
1194 * @param {HTMLElement} el Element to find root scrollable parent for
1195 * @return {HTMLElement} Scrollable parent, `document.body` or `document.documentElement`
1196 * depending on browser
1198 OO
.ui
.Element
.static.getRootScrollableElement = function ( el
) {
1199 var scrollTop
, body
;
1201 if ( OO
.ui
.scrollableElement
=== undefined ) {
1202 body
= el
.ownerDocument
.body
;
1203 scrollTop
= body
.scrollTop
;
1206 // In some browsers (observed in Chrome 56 on Linux Mint 18.1),
1207 // body.scrollTop doesn't become exactly 1, but a fractional value like 0.76
1208 if ( Math
.round( body
.scrollTop
) === 1 ) {
1209 body
.scrollTop
= scrollTop
;
1210 OO
.ui
.scrollableElement
= 'body';
1212 OO
.ui
.scrollableElement
= 'documentElement';
1216 return el
.ownerDocument
[ OO
.ui
.scrollableElement
];
1220 * Get closest scrollable container.
1222 * Traverses up until either a scrollable element or the root is reached, in which case the root
1223 * scrollable element will be returned (see #getRootScrollableElement).
1226 * @param {HTMLElement} el Element to find scrollable container for
1227 * @param {string} [dimension] Dimension of scrolling to look for; `x`, `y` or omit for either
1228 * @return {HTMLElement} Closest scrollable container
1230 OO
.ui
.Element
.static.getClosestScrollableContainer = function ( el
, dimension
) {
1232 // Browsers do not correctly return the computed value of 'overflow' when 'overflow-x' and
1233 // 'overflow-y' have different values, so we need to check the separate properties.
1234 props
= [ 'overflow-x', 'overflow-y' ],
1235 $parent
= $( el
).parent();
1237 if ( dimension
=== 'x' || dimension
=== 'y' ) {
1238 props
= [ 'overflow-' + dimension
];
1241 // Special case for the document root (which doesn't really have any scrollable container, since
1242 // it is the ultimate scrollable container, but this is probably saner than null or exception)
1243 if ( $( el
).is( 'html, body' ) ) {
1244 return this.getRootScrollableElement( el
);
1247 while ( $parent
.length
) {
1248 if ( $parent
[ 0 ] === this.getRootScrollableElement( el
) ) {
1249 return $parent
[ 0 ];
1253 val
= $parent
.css( props
[ i
] );
1254 // We assume that elements with 'overflow' (in any direction) set to 'hidden' will never be
1255 // scrolled in that direction, but they can actually be scrolled programatically. The user can
1256 // unintentionally perform a scroll in such case even if the application doesn't scroll
1257 // programatically, e.g. when jumping to an anchor, or when using built-in find functionality.
1258 // This could cause funny issues...
1259 if ( val
=== 'auto' || val
=== 'scroll' ) {
1260 return $parent
[ 0 ];
1263 $parent
= $parent
.parent();
1265 // The element is unattached... return something mostly sane
1266 return this.getRootScrollableElement( el
);
1270 * Scroll element into view.
1273 * @param {HTMLElement} el Element to scroll into view
1274 * @param {Object} [config] Configuration options
1275 * @param {string} [config.duration='fast'] jQuery animation duration value
1276 * @param {string} [config.direction] Scroll in only one direction, e.g. 'x' or 'y', omit
1277 * to scroll in both directions
1278 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1280 OO
.ui
.Element
.static.scrollIntoView = function ( el
, config
) {
1281 var position
, animations
, container
, $container
, elementDimensions
, containerDimensions
, $window
,
1282 deferred
= $.Deferred();
1284 // Configuration initialization
1285 config
= config
|| {};
1288 container
= this.getClosestScrollableContainer( el
, config
.direction
);
1289 $container
= $( container
);
1290 elementDimensions
= this.getDimensions( el
);
1291 containerDimensions
= this.getDimensions( container
);
1292 $window
= $( this.getWindow( el
) );
1294 // Compute the element's position relative to the container
1295 if ( $container
.is( 'html, body' ) ) {
1296 // If the scrollable container is the root, this is easy
1298 top
: elementDimensions
.rect
.top
,
1299 bottom
: $window
.innerHeight() - elementDimensions
.rect
.bottom
,
1300 left
: elementDimensions
.rect
.left
,
1301 right
: $window
.innerWidth() - elementDimensions
.rect
.right
1304 // Otherwise, we have to subtract el's coordinates from container's coordinates
1306 top
: elementDimensions
.rect
.top
- ( containerDimensions
.rect
.top
+ containerDimensions
.borders
.top
),
1307 bottom
: containerDimensions
.rect
.bottom
- containerDimensions
.borders
.bottom
- containerDimensions
.scrollbar
.bottom
- elementDimensions
.rect
.bottom
,
1308 left
: elementDimensions
.rect
.left
- ( containerDimensions
.rect
.left
+ containerDimensions
.borders
.left
),
1309 right
: containerDimensions
.rect
.right
- containerDimensions
.borders
.right
- containerDimensions
.scrollbar
.right
- elementDimensions
.rect
.right
1313 if ( !config
.direction
|| config
.direction
=== 'y' ) {
1314 if ( position
.top
< 0 ) {
1315 animations
.scrollTop
= containerDimensions
.scroll
.top
+ position
.top
;
1316 } else if ( position
.top
> 0 && position
.bottom
< 0 ) {
1317 animations
.scrollTop
= containerDimensions
.scroll
.top
+ Math
.min( position
.top
, -position
.bottom
);
1320 if ( !config
.direction
|| config
.direction
=== 'x' ) {
1321 if ( position
.left
< 0 ) {
1322 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ position
.left
;
1323 } else if ( position
.left
> 0 && position
.right
< 0 ) {
1324 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ Math
.min( position
.left
, -position
.right
);
1327 if ( !$.isEmptyObject( animations
) ) {
1328 $container
.stop( true ).animate( animations
, config
.duration
=== undefined ? 'fast' : config
.duration
);
1329 $container
.queue( function ( next
) {
1336 return deferred
.promise();
1340 * Force the browser to reconsider whether it really needs to render scrollbars inside the element
1341 * and reserve space for them, because it probably doesn't.
1343 * Workaround primarily for <https://code.google.com/p/chromium/issues/detail?id=387290>, but also
1344 * similar bugs in other browsers. "Just" forcing a reflow is not sufficient in all cases, we need
1345 * to first actually detach (or hide, but detaching is simpler) all children, *then* force a reflow,
1346 * and then reattach (or show) them back.
1349 * @param {HTMLElement} el Element to reconsider the scrollbars on
1351 OO
.ui
.Element
.static.reconsiderScrollbars = function ( el
) {
1352 var i
, len
, scrollLeft
, scrollTop
, nodes
= [];
1353 // Save scroll position
1354 scrollLeft
= el
.scrollLeft
;
1355 scrollTop
= el
.scrollTop
;
1356 // Detach all children
1357 while ( el
.firstChild
) {
1358 nodes
.push( el
.firstChild
);
1359 el
.removeChild( el
.firstChild
);
1362 void el
.offsetHeight
;
1363 // Reattach all children
1364 for ( i
= 0, len
= nodes
.length
; i
< len
; i
++ ) {
1365 el
.appendChild( nodes
[ i
] );
1367 // Restore scroll position (no-op if scrollbars disappeared)
1368 el
.scrollLeft
= scrollLeft
;
1369 el
.scrollTop
= scrollTop
;
1375 * Toggle visibility of an element.
1377 * @param {boolean} [show] Make element visible, omit to toggle visibility
1381 OO
.ui
.Element
.prototype.toggle = function ( show
) {
1382 show
= show
=== undefined ? !this.visible
: !!show
;
1384 if ( show
!== this.isVisible() ) {
1385 this.visible
= show
;
1386 this.$element
.toggleClass( 'oo-ui-element-hidden', !this.visible
);
1387 this.emit( 'toggle', show
);
1394 * Check if element is visible.
1396 * @return {boolean} element is visible
1398 OO
.ui
.Element
.prototype.isVisible = function () {
1399 return this.visible
;
1405 * @return {Mixed} Element data
1407 OO
.ui
.Element
.prototype.getData = function () {
1414 * @param {Mixed} data Element data
1417 OO
.ui
.Element
.prototype.setData = function ( data
) {
1423 * Set the element has an 'id' attribute.
1425 * @param {string} id
1428 OO
.ui
.Element
.prototype.setElementId = function ( id
) {
1429 this.elementId
= id
;
1430 this.$element
.attr( 'id', id
);
1435 * Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing,
1436 * and return its value.
1440 OO
.ui
.Element
.prototype.getElementId = function () {
1441 if ( this.elementId
=== null ) {
1442 this.setElementId( OO
.ui
.generateElementId() );
1444 return this.elementId
;
1448 * Check if element supports one or more methods.
1450 * @param {string|string[]} methods Method or list of methods to check
1451 * @return {boolean} All methods are supported
1453 OO
.ui
.Element
.prototype.supports = function ( methods
) {
1457 methods
= Array
.isArray( methods
) ? methods
: [ methods
];
1458 for ( i
= 0, len
= methods
.length
; i
< len
; i
++ ) {
1459 if ( $.isFunction( this[ methods
[ i
] ] ) ) {
1464 return methods
.length
=== support
;
1468 * Update the theme-provided classes.
1470 * @localdoc This is called in element mixins and widget classes any time state changes.
1471 * Updating is debounced, minimizing overhead of changing multiple attributes and
1472 * guaranteeing that theme updates do not occur within an element's constructor
1474 OO
.ui
.Element
.prototype.updateThemeClasses = function () {
1475 OO
.ui
.theme
.queueUpdateElementClasses( this );
1479 * Get the HTML tag name.
1481 * Override this method to base the result on instance information.
1483 * @return {string} HTML tag name
1485 OO
.ui
.Element
.prototype.getTagName = function () {
1486 return this.constructor.static.tagName
;
1490 * Check if the element is attached to the DOM
1492 * @return {boolean} The element is attached to the DOM
1494 OO
.ui
.Element
.prototype.isElementAttached = function () {
1495 return $.contains( this.getElementDocument(), this.$element
[ 0 ] );
1499 * Get the DOM document.
1501 * @return {HTMLDocument} Document object
1503 OO
.ui
.Element
.prototype.getElementDocument = function () {
1504 // Don't cache this in other ways either because subclasses could can change this.$element
1505 return OO
.ui
.Element
.static.getDocument( this.$element
);
1509 * Get the DOM window.
1511 * @return {Window} Window object
1513 OO
.ui
.Element
.prototype.getElementWindow = function () {
1514 return OO
.ui
.Element
.static.getWindow( this.$element
);
1518 * Get closest scrollable container.
1520 * @return {HTMLElement} Closest scrollable container
1522 OO
.ui
.Element
.prototype.getClosestScrollableElementContainer = function () {
1523 return OO
.ui
.Element
.static.getClosestScrollableContainer( this.$element
[ 0 ] );
1527 * Get group element is in.
1529 * @return {OO.ui.mixin.GroupElement|null} Group element, null if none
1531 OO
.ui
.Element
.prototype.getElementGroup = function () {
1532 return this.elementGroup
;
1536 * Set group element is in.
1538 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
1541 OO
.ui
.Element
.prototype.setElementGroup = function ( group
) {
1542 this.elementGroup
= group
;
1547 * Scroll element into view.
1549 * @param {Object} [config] Configuration options
1550 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1552 OO
.ui
.Element
.prototype.scrollElementIntoView = function ( config
) {
1554 !this.isElementAttached() ||
1555 !this.isVisible() ||
1556 ( this.getElementGroup() && !this.getElementGroup().isVisible() )
1558 return $.Deferred().resolve();
1560 return OO
.ui
.Element
.static.scrollIntoView( this.$element
[ 0 ], config
);
1564 * Restore the pre-infusion dynamic state for this widget.
1566 * This method is called after #$element has been inserted into DOM. The parameter is the return
1567 * value of #gatherPreInfuseState.
1570 * @param {Object} state
1572 OO
.ui
.Element
.prototype.restorePreInfuseState = function () {
1576 * Wraps an HTML snippet for use with configuration values which default
1577 * to strings. This bypasses the default html-escaping done to string
1583 * @param {string} [content] HTML content
1585 OO
.ui
.HtmlSnippet
= function OoUiHtmlSnippet( content
) {
1587 this.content
= content
;
1592 OO
.initClass( OO
.ui
.HtmlSnippet
);
1599 * @return {string} Unchanged HTML snippet.
1601 OO
.ui
.HtmlSnippet
.prototype.toString = function () {
1602 return this.content
;
1606 * Layouts are containers for elements and are used to arrange other widgets of arbitrary type in a way
1607 * that is centrally controlled and can be updated dynamically. Layouts can be, and usually are, combined.
1608 * See {@link OO.ui.FieldsetLayout FieldsetLayout}, {@link OO.ui.FieldLayout FieldLayout}, {@link OO.ui.FormLayout FormLayout},
1609 * {@link OO.ui.PanelLayout PanelLayout}, {@link OO.ui.StackLayout StackLayout}, {@link OO.ui.PageLayout PageLayout},
1610 * {@link OO.ui.HorizontalLayout HorizontalLayout}, and {@link OO.ui.BookletLayout BookletLayout} for more information and examples.
1614 * @extends OO.ui.Element
1615 * @mixins OO.EventEmitter
1618 * @param {Object} [config] Configuration options
1620 OO
.ui
.Layout
= function OoUiLayout( config
) {
1621 // Configuration initialization
1622 config
= config
|| {};
1624 // Parent constructor
1625 OO
.ui
.Layout
.parent
.call( this, config
);
1627 // Mixin constructors
1628 OO
.EventEmitter
.call( this );
1631 this.$element
.addClass( 'oo-ui-layout' );
1636 OO
.inheritClass( OO
.ui
.Layout
, OO
.ui
.Element
);
1637 OO
.mixinClass( OO
.ui
.Layout
, OO
.EventEmitter
);
1640 * Widgets are compositions of one or more OOUI elements that users can both view
1641 * and interact with. All widgets can be configured and modified via a standard API,
1642 * and their state can change dynamically according to a model.
1646 * @extends OO.ui.Element
1647 * @mixins OO.EventEmitter
1650 * @param {Object} [config] Configuration options
1651 * @cfg {boolean} [disabled=false] Disable the widget. Disabled widgets cannot be used and their
1652 * appearance reflects this state.
1654 OO
.ui
.Widget
= function OoUiWidget( config
) {
1655 // Initialize config
1656 config
= $.extend( { disabled
: false }, config
);
1658 // Parent constructor
1659 OO
.ui
.Widget
.parent
.call( this, config
);
1661 // Mixin constructors
1662 OO
.EventEmitter
.call( this );
1665 this.disabled
= null;
1666 this.wasDisabled
= null;
1669 this.$element
.addClass( 'oo-ui-widget' );
1670 this.setDisabled( !!config
.disabled
);
1675 OO
.inheritClass( OO
.ui
.Widget
, OO
.ui
.Element
);
1676 OO
.mixinClass( OO
.ui
.Widget
, OO
.EventEmitter
);
1683 * A 'disable' event is emitted when the disabled state of the widget changes
1684 * (i.e. on disable **and** enable).
1686 * @param {boolean} disabled Widget is disabled
1692 * A 'toggle' event is emitted when the visibility of the widget changes.
1694 * @param {boolean} visible Widget is visible
1700 * Check if the widget is disabled.
1702 * @return {boolean} Widget is disabled
1704 OO
.ui
.Widget
.prototype.isDisabled = function () {
1705 return this.disabled
;
1709 * Set the 'disabled' state of the widget.
1711 * When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.
1713 * @param {boolean} disabled Disable widget
1716 OO
.ui
.Widget
.prototype.setDisabled = function ( disabled
) {
1719 this.disabled
= !!disabled
;
1720 isDisabled
= this.isDisabled();
1721 if ( isDisabled
!== this.wasDisabled
) {
1722 this.$element
.toggleClass( 'oo-ui-widget-disabled', isDisabled
);
1723 this.$element
.toggleClass( 'oo-ui-widget-enabled', !isDisabled
);
1724 this.$element
.attr( 'aria-disabled', isDisabled
.toString() );
1725 this.emit( 'disable', isDisabled
);
1726 this.updateThemeClasses();
1728 this.wasDisabled
= isDisabled
;
1734 * Update the disabled state, in case of changes in parent widget.
1738 OO
.ui
.Widget
.prototype.updateDisabled = function () {
1739 this.setDisabled( this.disabled
);
1744 * Get an ID of a labelable node which is part of this widget, if any, to be used for `<label for>`
1747 * If this function returns null, the widget should have a meaningful #simulateLabelClick method
1750 * @return {string|null} The ID of the labelable element
1752 OO
.ui
.Widget
.prototype.getInputId = function () {
1757 * Simulate the behavior of clicking on a label (a HTML `<label>` element) bound to this input.
1758 * HTML only allows `<label>` to act on specific "labelable" elements; complex widgets might need to
1759 * override this method to provide intuitive, accessible behavior.
1761 * By default, this does nothing. OO.ui.mixin.TabIndexedElement overrides it for focusable widgets.
1762 * Individual widgets may override it too.
1764 * This method is called by OO.ui.LabelWidget and OO.ui.FieldLayout. It should not be called
1767 OO
.ui
.Widget
.prototype.simulateLabelClick = function () {
1778 OO
.ui
.Theme
= function OoUiTheme() {
1779 this.elementClassesQueue
= [];
1780 this.debouncedUpdateQueuedElementClasses
= OO
.ui
.debounce( this.updateQueuedElementClasses
);
1785 OO
.initClass( OO
.ui
.Theme
);
1790 * Get a list of classes to be applied to a widget.
1792 * The 'on' and 'off' lists combined MUST contain keys for all classes the theme adds or removes,
1793 * otherwise state transitions will not work properly.
1795 * @param {OO.ui.Element} element Element for which to get classes
1796 * @return {Object.<string,string[]>} Categorized class names with `on` and `off` lists
1798 OO
.ui
.Theme
.prototype.getElementClasses = function () {
1799 return { on
: [], off
: [] };
1803 * Update CSS classes provided by the theme.
1805 * For elements with theme logic hooks, this should be called any time there's a state change.
1807 * @param {OO.ui.Element} element Element for which to update classes
1809 OO
.ui
.Theme
.prototype.updateElementClasses = function ( element
) {
1810 var $elements
= $( [] ),
1811 classes
= this.getElementClasses( element
);
1813 if ( element
.$icon
) {
1814 $elements
= $elements
.add( element
.$icon
);
1816 if ( element
.$indicator
) {
1817 $elements
= $elements
.add( element
.$indicator
);
1821 .removeClass( classes
.off
)
1822 .addClass( classes
.on
);
1828 OO
.ui
.Theme
.prototype.updateQueuedElementClasses = function () {
1830 for ( i
= 0; i
< this.elementClassesQueue
.length
; i
++ ) {
1831 this.updateElementClasses( this.elementClassesQueue
[ i
] );
1834 this.elementClassesQueue
= [];
1838 * Queue #updateElementClasses to be called for this element.
1840 * @localdoc QUnit tests override this method to directly call #queueUpdateElementClasses,
1841 * to make them synchronous.
1843 * @param {OO.ui.Element} element Element for which to update classes
1845 OO
.ui
.Theme
.prototype.queueUpdateElementClasses = function ( element
) {
1846 // Keep items in the queue unique. Use lastIndexOf to start checking from the end because that's
1847 // the most common case (this method is often called repeatedly for the same element).
1848 if ( this.elementClassesQueue
.lastIndexOf( element
) !== -1 ) {
1851 this.elementClassesQueue
.push( element
);
1852 this.debouncedUpdateQueuedElementClasses();
1856 * Get the transition duration in milliseconds for dialogs opening/closing
1858 * The dialog should be fully rendered this many milliseconds after the
1859 * ready process has executed.
1861 * @return {number} Transition duration in milliseconds
1863 OO
.ui
.Theme
.prototype.getDialogTransitionDuration = function () {
1868 * The TabIndexedElement class is an attribute mixin used to add additional functionality to an
1869 * element created by another class. The mixin provides a ‘tabIndex’ property, which specifies the
1870 * order in which users will navigate through the focusable elements via the "tab" key.
1873 * // TabIndexedElement is mixed into the ButtonWidget class
1874 * // to provide a tabIndex property.
1875 * var button1 = new OO.ui.ButtonWidget( {
1879 * var button2 = new OO.ui.ButtonWidget( {
1883 * var button3 = new OO.ui.ButtonWidget( {
1887 * var button4 = new OO.ui.ButtonWidget( {
1891 * $( 'body' ).append( button1.$element, button2.$element, button3.$element, button4.$element );
1897 * @param {Object} [config] Configuration options
1898 * @cfg {jQuery} [$tabIndexed] The element that should use the tabindex functionality. By default,
1899 * the functionality is applied to the element created by the class ($element). If a different element is specified, the tabindex
1900 * functionality will be applied to it instead.
1901 * @cfg {string|number|null} [tabIndex=0] Number that specifies the element’s position in the tab-navigation
1902 * order (e.g., 1 for the first focusable element). Use 0 to use the default navigation order; use -1
1903 * to remove the element from the tab-navigation flow.
1905 OO
.ui
.mixin
.TabIndexedElement
= function OoUiMixinTabIndexedElement( config
) {
1906 // Configuration initialization
1907 config
= $.extend( { tabIndex
: 0 }, config
);
1910 this.$tabIndexed
= null;
1911 this.tabIndex
= null;
1914 this.connect( this, { disable
: 'onTabIndexedElementDisable' } );
1917 this.setTabIndex( config
.tabIndex
);
1918 this.setTabIndexedElement( config
.$tabIndexed
|| this.$element
);
1923 OO
.initClass( OO
.ui
.mixin
.TabIndexedElement
);
1928 * Set the element that should use the tabindex functionality.
1930 * This method is used to retarget a tabindex mixin so that its functionality applies
1931 * to the specified element. If an element is currently using the functionality, the mixin’s
1932 * effect on that element is removed before the new element is set up.
1934 * @param {jQuery} $tabIndexed Element that should use the tabindex functionality
1937 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndexedElement = function ( $tabIndexed
) {
1938 var tabIndex
= this.tabIndex
;
1939 // Remove attributes from old $tabIndexed
1940 this.setTabIndex( null );
1941 // Force update of new $tabIndexed
1942 this.$tabIndexed
= $tabIndexed
;
1943 this.tabIndex
= tabIndex
;
1944 return this.updateTabIndex();
1948 * Set the value of the tabindex.
1950 * @param {string|number|null} tabIndex Tabindex value, or `null` for no tabindex
1953 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndex = function ( tabIndex
) {
1954 tabIndex
= /^-?\d+$/.test( tabIndex
) ? Number( tabIndex
) : null;
1956 if ( this.tabIndex
!== tabIndex
) {
1957 this.tabIndex
= tabIndex
;
1958 this.updateTabIndex();
1965 * Update the `tabindex` attribute, in case of changes to tab index or
1971 OO
.ui
.mixin
.TabIndexedElement
.prototype.updateTabIndex = function () {
1972 if ( this.$tabIndexed
) {
1973 if ( this.tabIndex
!== null ) {
1974 // Do not index over disabled elements
1975 this.$tabIndexed
.attr( {
1976 tabindex
: this.isDisabled() ? -1 : this.tabIndex
,
1977 // Support: ChromeVox and NVDA
1978 // These do not seem to inherit aria-disabled from parent elements
1979 'aria-disabled': this.isDisabled().toString()
1982 this.$tabIndexed
.removeAttr( 'tabindex aria-disabled' );
1989 * Handle disable events.
1992 * @param {boolean} disabled Element is disabled
1994 OO
.ui
.mixin
.TabIndexedElement
.prototype.onTabIndexedElementDisable = function () {
1995 this.updateTabIndex();
1999 * Get the value of the tabindex.
2001 * @return {number|null} Tabindex value
2003 OO
.ui
.mixin
.TabIndexedElement
.prototype.getTabIndex = function () {
2004 return this.tabIndex
;
2008 * Get an ID of a focusable element of this widget, if any, to be used for `<label for>` value.
2010 * If the element already has an ID then that is returned, otherwise unique ID is
2011 * generated, set on the element, and returned.
2013 * @return {string|null} The ID of the focusable element
2015 OO
.ui
.mixin
.TabIndexedElement
.prototype.getInputId = function () {
2018 if ( !this.$tabIndexed
) {
2021 if ( !this.isLabelableNode( this.$tabIndexed
) ) {
2025 id
= this.$tabIndexed
.attr( 'id' );
2026 if ( id
=== undefined ) {
2027 id
= OO
.ui
.generateElementId();
2028 this.$tabIndexed
.attr( 'id', id
);
2035 * Whether the node is 'labelable' according to the HTML spec
2036 * (i.e., whether it can be interacted with through a `<label for="…">`).
2037 * See: <https://html.spec.whatwg.org/multipage/forms.html#category-label>.
2040 * @param {jQuery} $node
2043 OO
.ui
.mixin
.TabIndexedElement
.prototype.isLabelableNode = function ( $node
) {
2045 labelableTags
= [ 'button', 'meter', 'output', 'progress', 'select', 'textarea' ],
2046 tagName
= $node
.prop( 'tagName' ).toLowerCase();
2048 if ( tagName
=== 'input' && $node
.attr( 'type' ) !== 'hidden' ) {
2051 if ( labelableTags
.indexOf( tagName
) !== -1 ) {
2058 * Focus this element.
2062 OO
.ui
.mixin
.TabIndexedElement
.prototype.focus = function () {
2063 if ( !this.isDisabled() ) {
2064 this.$tabIndexed
.focus();
2070 * Blur this element.
2074 OO
.ui
.mixin
.TabIndexedElement
.prototype.blur = function () {
2075 this.$tabIndexed
.blur();
2080 * @inheritdoc OO.ui.Widget
2082 OO
.ui
.mixin
.TabIndexedElement
.prototype.simulateLabelClick = function () {
2087 * ButtonElement is often mixed into other classes to generate a button, which is a clickable
2088 * interface element that can be configured with access keys for accessibility.
2089 * See the [OOUI documentation on MediaWiki] [1] for examples.
2091 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Buttons_and_Switches#Buttons
2097 * @param {Object} [config] Configuration options
2098 * @cfg {jQuery} [$button] The button element created by the class.
2099 * If this configuration is omitted, the button element will use a generated `<a>`.
2100 * @cfg {boolean} [framed=true] Render the button with a frame
2102 OO
.ui
.mixin
.ButtonElement
= function OoUiMixinButtonElement( config
) {
2103 // Configuration initialization
2104 config
= config
|| {};
2107 this.$button
= null;
2109 this.active
= config
.active
!== undefined && config
.active
;
2110 this.onDocumentMouseUpHandler
= this.onDocumentMouseUp
.bind( this );
2111 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
2112 this.onDocumentKeyUpHandler
= this.onDocumentKeyUp
.bind( this );
2113 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
2114 this.onClickHandler
= this.onClick
.bind( this );
2115 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
2118 this.$element
.addClass( 'oo-ui-buttonElement' );
2119 this.toggleFramed( config
.framed
=== undefined || config
.framed
);
2120 this.setButtonElement( config
.$button
|| $( '<a>' ) );
2125 OO
.initClass( OO
.ui
.mixin
.ButtonElement
);
2127 /* Static Properties */
2130 * Cancel mouse down events.
2132 * This property is usually set to `true` to prevent the focus from changing when the button is clicked.
2133 * Classes such as {@link OO.ui.mixin.DraggableElement DraggableElement} and {@link OO.ui.ButtonOptionWidget ButtonOptionWidget}
2134 * use a value of `false` so that dragging behavior is possible and mousedown events can be handled by a
2139 * @property {boolean}
2141 OO
.ui
.mixin
.ButtonElement
.static.cancelButtonMouseDownEvents
= true;
2146 * A 'click' event is emitted when the button element is clicked.
2154 * Set the button element.
2156 * This method is used to retarget a button mixin so that its functionality applies to
2157 * the specified button element instead of the one created by the class. If a button element
2158 * is already set, the method will remove the mixin’s effect on that element.
2160 * @param {jQuery} $button Element to use as button
2162 OO
.ui
.mixin
.ButtonElement
.prototype.setButtonElement = function ( $button
) {
2163 if ( this.$button
) {
2165 .removeClass( 'oo-ui-buttonElement-button' )
2166 .removeAttr( 'role accesskey' )
2168 mousedown
: this.onMouseDownHandler
,
2169 keydown
: this.onKeyDownHandler
,
2170 click
: this.onClickHandler
,
2171 keypress
: this.onKeyPressHandler
2175 this.$button
= $button
2176 .addClass( 'oo-ui-buttonElement-button' )
2178 mousedown
: this.onMouseDownHandler
,
2179 keydown
: this.onKeyDownHandler
,
2180 click
: this.onClickHandler
,
2181 keypress
: this.onKeyPressHandler
2184 // Add `role="button"` on `<a>` elements, where it's needed
2185 // `toUppercase()` is added for XHTML documents
2186 if ( this.$button
.prop( 'tagName' ).toUpperCase() === 'A' ) {
2187 this.$button
.attr( 'role', 'button' );
2192 * Handles mouse down events.
2195 * @param {jQuery.Event} e Mouse down event
2197 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown = function ( e
) {
2198 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
2201 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
2202 // Run the mouseup handler no matter where the mouse is when the button is let go, so we can
2203 // reliably remove the pressed class
2204 this.getElementDocument().addEventListener( 'mouseup', this.onDocumentMouseUpHandler
, true );
2205 // Prevent change of focus unless specifically configured otherwise
2206 if ( this.constructor.static.cancelButtonMouseDownEvents
) {
2212 * Handles document mouse up events.
2215 * @param {MouseEvent} e Mouse up event
2217 OO
.ui
.mixin
.ButtonElement
.prototype.onDocumentMouseUp = function ( e
) {
2218 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
2221 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
2222 // Stop listening for mouseup, since we only needed this once
2223 this.getElementDocument().removeEventListener( 'mouseup', this.onDocumentMouseUpHandler
, true );
2226 // Deprecated alias since 0.28.3
2227 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp = function () {
2228 OO
.ui
.warnDeprecation( 'onMouseUp is deprecated, use onDocumentMouseUp instead' );
2229 this.onDocumentMouseUp
.apply( this, arguments
);
2233 * Handles mouse click events.
2236 * @param {jQuery.Event} e Mouse click event
2239 OO
.ui
.mixin
.ButtonElement
.prototype.onClick = function ( e
) {
2240 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
2241 if ( this.emit( 'click' ) ) {
2248 * Handles key down events.
2251 * @param {jQuery.Event} e Key down event
2253 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyDown = function ( e
) {
2254 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
2257 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
2258 // Run the keyup handler no matter where the key is when the button is let go, so we can
2259 // reliably remove the pressed class
2260 this.getElementDocument().addEventListener( 'keyup', this.onDocumentKeyUpHandler
, true );
2264 * Handles document key up events.
2267 * @param {KeyboardEvent} e Key up event
2269 OO
.ui
.mixin
.ButtonElement
.prototype.onDocumentKeyUp = function ( e
) {
2270 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
2273 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
2274 // Stop listening for keyup, since we only needed this once
2275 this.getElementDocument().removeEventListener( 'keyup', this.onDocumentKeyUpHandler
, true );
2278 // Deprecated alias since 0.28.3
2279 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyUp = function () {
2280 OO
.ui
.warnDeprecation( 'onKeyUp is deprecated, use onDocumentKeyUp instead' );
2281 this.onDocumentKeyUp
.apply( this, arguments
);
2285 * Handles key press events.
2288 * @param {jQuery.Event} e Key press event
2291 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyPress = function ( e
) {
2292 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
2293 if ( this.emit( 'click' ) ) {
2300 * Check if button has a frame.
2302 * @return {boolean} Button is framed
2304 OO
.ui
.mixin
.ButtonElement
.prototype.isFramed = function () {
2309 * Render the button with or without a frame. Omit the `framed` parameter to toggle the button frame on and off.
2311 * @param {boolean} [framed] Make button framed, omit to toggle
2314 OO
.ui
.mixin
.ButtonElement
.prototype.toggleFramed = function ( framed
) {
2315 framed
= framed
=== undefined ? !this.framed
: !!framed
;
2316 if ( framed
!== this.framed
) {
2317 this.framed
= framed
;
2319 .toggleClass( 'oo-ui-buttonElement-frameless', !framed
)
2320 .toggleClass( 'oo-ui-buttonElement-framed', framed
);
2321 this.updateThemeClasses();
2328 * Set the button's active state.
2330 * The active state can be set on:
2332 * - {@link OO.ui.ButtonOptionWidget ButtonOptionWidget} when it is selected
2333 * - {@link OO.ui.ToggleButtonWidget ToggleButtonWidget} when it is toggle on
2334 * - {@link OO.ui.ButtonWidget ButtonWidget} when clicking the button would only refresh the page
2337 * @param {boolean} value Make button active
2340 OO
.ui
.mixin
.ButtonElement
.prototype.setActive = function ( value
) {
2341 this.active
= !!value
;
2342 this.$element
.toggleClass( 'oo-ui-buttonElement-active', this.active
);
2343 this.updateThemeClasses();
2348 * Check if the button is active
2351 * @return {boolean} The button is active
2353 OO
.ui
.mixin
.ButtonElement
.prototype.isActive = function () {
2358 * Any OOUI widget that contains other widgets (such as {@link OO.ui.ButtonWidget buttons} or
2359 * {@link OO.ui.OptionWidget options}) mixes in GroupElement. Adding, removing, and clearing
2360 * items from the group is done through the interface the class provides.
2361 * For more information, please see the [OOUI documentation on MediaWiki] [1].
2363 * [1]: https://www.mediawiki.org/wiki/OOUI/Elements/Groups
2366 * @mixins OO.EmitterList
2370 * @param {Object} [config] Configuration options
2371 * @cfg {jQuery} [$group] The container element created by the class. If this configuration
2372 * is omitted, the group element will use a generated `<div>`.
2374 OO
.ui
.mixin
.GroupElement
= function OoUiMixinGroupElement( config
) {
2375 // Configuration initialization
2376 config
= config
|| {};
2378 // Mixin constructors
2379 OO
.EmitterList
.call( this, config
);
2385 this.setGroupElement( config
.$group
|| $( '<div>' ) );
2390 OO
.mixinClass( OO
.ui
.mixin
.GroupElement
, OO
.EmitterList
);
2397 * A change event is emitted when the set of selected items changes.
2399 * @param {OO.ui.Element[]} items Items currently in the group
2405 * Set the group element.
2407 * If an element is already set, items will be moved to the new element.
2409 * @param {jQuery} $group Element to use as group
2411 OO
.ui
.mixin
.GroupElement
.prototype.setGroupElement = function ( $group
) {
2414 this.$group
= $group
;
2415 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2416 this.$group
.append( this.items
[ i
].$element
);
2421 * Find an item by its data.
2423 * Only the first item with matching data will be returned. To return all matching items,
2424 * use the #findItemsFromData method.
2426 * @param {Object} data Item data to search for
2427 * @return {OO.ui.Element|null} Item with equivalent data, `null` if none exists
2429 OO
.ui
.mixin
.GroupElement
.prototype.findItemFromData = function ( data
) {
2431 hash
= OO
.getHash( data
);
2433 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2434 item
= this.items
[ i
];
2435 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2444 * Find items by their data.
2446 * All items with matching data will be returned. To return only the first match, use the #findItemFromData method instead.
2448 * @param {Object} data Item data to search for
2449 * @return {OO.ui.Element[]} Items with equivalent data
2451 OO
.ui
.mixin
.GroupElement
.prototype.findItemsFromData = function ( data
) {
2453 hash
= OO
.getHash( data
),
2456 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2457 item
= this.items
[ i
];
2458 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2467 * Add items to the group.
2469 * Items will be added to the end of the group array unless the optional `index` parameter specifies
2470 * a different insertion point. Adding an existing item will move it to the end of the array or the point specified by the `index`.
2472 * @param {OO.ui.Element[]} items An array of items to add to the group
2473 * @param {number} [index] Index of the insertion point
2476 OO
.ui
.mixin
.GroupElement
.prototype.addItems = function ( items
, index
) {
2478 OO
.EmitterList
.prototype.addItems
.call( this, items
, index
);
2480 this.emit( 'change', this.getItems() );
2487 OO
.ui
.mixin
.GroupElement
.prototype.moveItem = function ( items
, newIndex
) {
2488 // insertItemElements expects this.items to not have been modified yet, so call before the mixin
2489 this.insertItemElements( items
, newIndex
);
2492 newIndex
= OO
.EmitterList
.prototype.moveItem
.call( this, items
, newIndex
);
2500 OO
.ui
.mixin
.GroupElement
.prototype.insertItem = function ( item
, index
) {
2501 item
.setElementGroup( this );
2502 this.insertItemElements( item
, index
);
2505 index
= OO
.EmitterList
.prototype.insertItem
.call( this, item
, index
);
2511 * Insert elements into the group
2514 * @param {OO.ui.Element} itemWidget Item to insert
2515 * @param {number} index Insertion index
2517 OO
.ui
.mixin
.GroupElement
.prototype.insertItemElements = function ( itemWidget
, index
) {
2518 if ( index
=== undefined || index
< 0 || index
>= this.items
.length
) {
2519 this.$group
.append( itemWidget
.$element
);
2520 } else if ( index
=== 0 ) {
2521 this.$group
.prepend( itemWidget
.$element
);
2523 this.items
[ index
].$element
.before( itemWidget
.$element
);
2528 * Remove the specified items from a group.
2530 * Removed items are detached (not removed) from the DOM so that they may be reused.
2531 * To remove all items from a group, you may wish to use the #clearItems method instead.
2533 * @param {OO.ui.Element[]} items An array of items to remove
2536 OO
.ui
.mixin
.GroupElement
.prototype.removeItems = function ( items
) {
2537 var i
, len
, item
, index
;
2539 // Remove specific items elements
2540 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2542 index
= this.items
.indexOf( item
);
2543 if ( index
!== -1 ) {
2544 item
.setElementGroup( null );
2545 item
.$element
.detach();
2550 OO
.EmitterList
.prototype.removeItems
.call( this, items
);
2552 this.emit( 'change', this.getItems() );
2557 * Clear all items from the group.
2559 * Cleared items are detached from the DOM, not removed, so that they may be reused.
2560 * To remove only a subset of items from a group, use the #removeItems method.
2564 OO
.ui
.mixin
.GroupElement
.prototype.clearItems = function () {
2567 // Remove all item elements
2568 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2569 this.items
[ i
].setElementGroup( null );
2570 this.items
[ i
].$element
.detach();
2574 OO
.EmitterList
.prototype.clearItems
.call( this );
2576 this.emit( 'change', this.getItems() );
2581 * IconElement is often mixed into other classes to generate an icon.
2582 * Icons are graphics, about the size of normal text. They are used to aid the user
2583 * in locating a control or to convey information in a space-efficient way. See the
2584 * [OOUI documentation on MediaWiki] [1] for a list of icons
2585 * included in the library.
2587 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Icons,_Indicators,_and_Labels#Icons
2593 * @param {Object} [config] Configuration options
2594 * @cfg {jQuery} [$icon] The icon element created by the class. If this configuration is omitted,
2595 * the icon element will use a generated `<span>`. To use a different HTML tag, or to specify that
2596 * the icon element be set to an existing icon instead of the one generated by this class, set a
2597 * value using a jQuery selection. For example:
2599 * // Use a <div> tag instead of a <span>
2601 * // Use an existing icon element instead of the one generated by the class
2602 * $icon: this.$element
2603 * // Use an icon element from a child widget
2604 * $icon: this.childwidget.$element
2605 * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
2606 * symbolic names. A map is used for i18n purposes and contains a `default` icon
2607 * name and additional names keyed by language code. The `default` name is used when no icon is keyed
2608 * by the user's language.
2610 * Example of an i18n map:
2612 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2613 * See the [OOUI documentation on MediaWiki] [2] for a list of icons included in the library.
2614 * [2]: https://www.mediawiki.org/wiki/OOUI/Widgets/Icons,_Indicators,_and_Labels#Icons
2615 * @cfg {string|Function} [iconTitle] A text string used as the icon title, or a function that returns title
2616 * text. The icon title is displayed when users move the mouse over the icon.
2618 OO
.ui
.mixin
.IconElement
= function OoUiMixinIconElement( config
) {
2619 // Configuration initialization
2620 config
= config
|| {};
2625 this.iconTitle
= null;
2628 this.setIcon( config
.icon
|| this.constructor.static.icon
);
2629 this.setIconTitle( config
.iconTitle
|| this.constructor.static.iconTitle
);
2630 this.setIconElement( config
.$icon
|| $( '<span>' ) );
2635 OO
.initClass( OO
.ui
.mixin
.IconElement
);
2637 /* Static Properties */
2640 * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map is used
2641 * for i18n purposes and contains a `default` icon name and additional names keyed by
2642 * language code. The `default` name is used when no icon is keyed by the user's language.
2644 * Example of an i18n map:
2646 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2648 * Note: the static property will be overridden if the #icon configuration is used.
2652 * @property {Object|string}
2654 OO
.ui
.mixin
.IconElement
.static.icon
= null;
2657 * The icon title, displayed when users move the mouse over the icon. The value can be text, a
2658 * function that returns title text, or `null` for no title.
2660 * The static property will be overridden if the #iconTitle configuration is used.
2664 * @property {string|Function|null}
2666 OO
.ui
.mixin
.IconElement
.static.iconTitle
= null;
2671 * Set the icon element. This method is used to retarget an icon mixin so that its functionality
2672 * applies to the specified icon element instead of the one created by the class. If an icon
2673 * element is already set, the mixin’s effect on that element is removed. Generated CSS classes
2674 * and mixin methods will no longer affect the element.
2676 * @param {jQuery} $icon Element to use as icon
2678 OO
.ui
.mixin
.IconElement
.prototype.setIconElement = function ( $icon
) {
2681 .removeClass( 'oo-ui-iconElement-icon oo-ui-icon-' + this.icon
)
2682 .removeAttr( 'title' );
2686 .addClass( 'oo-ui-iconElement-icon' )
2687 .toggleClass( 'oo-ui-iconElement-noIcon', !this.icon
)
2688 .toggleClass( 'oo-ui-icon-' + this.icon
, !!this.icon
);
2689 if ( this.iconTitle
!== null ) {
2690 this.$icon
.attr( 'title', this.iconTitle
);
2693 this.updateThemeClasses();
2697 * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove an icon.
2698 * The icon parameter can also be set to a map of icon names. See the #icon config setting
2701 * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map of icon names} keyed
2702 * by language code, or `null` to remove the icon.
2705 OO
.ui
.mixin
.IconElement
.prototype.setIcon = function ( icon
) {
2706 icon
= OO
.isPlainObject( icon
) ? OO
.ui
.getLocalValue( icon
, null, 'default' ) : icon
;
2707 icon
= typeof icon
=== 'string' && icon
.trim().length
? icon
.trim() : null;
2709 if ( this.icon
!== icon
) {
2711 if ( this.icon
!== null ) {
2712 this.$icon
.removeClass( 'oo-ui-icon-' + this.icon
);
2714 if ( icon
!== null ) {
2715 this.$icon
.addClass( 'oo-ui-icon-' + icon
);
2721 this.$element
.toggleClass( 'oo-ui-iconElement', !!this.icon
);
2723 this.$icon
.toggleClass( 'oo-ui-iconElement-noIcon', !this.icon
);
2725 this.updateThemeClasses();
2731 * Set the icon title. Use `null` to remove the title.
2733 * @param {string|Function|null} iconTitle A text string used as the icon title,
2734 * a function that returns title text, or `null` for no title.
2737 OO
.ui
.mixin
.IconElement
.prototype.setIconTitle = function ( iconTitle
) {
2739 ( typeof iconTitle
=== 'function' || ( typeof iconTitle
=== 'string' && iconTitle
.length
) ) ?
2740 OO
.ui
.resolveMsg( iconTitle
) : null;
2742 if ( this.iconTitle
!== iconTitle
) {
2743 this.iconTitle
= iconTitle
;
2745 if ( this.iconTitle
!== null ) {
2746 this.$icon
.attr( 'title', iconTitle
);
2748 this.$icon
.removeAttr( 'title' );
2757 * Get the symbolic name of the icon.
2759 * @return {string} Icon name
2761 OO
.ui
.mixin
.IconElement
.prototype.getIcon = function () {
2766 * Get the icon title. The title text is displayed when a user moves the mouse over the icon.
2768 * @return {string} Icon title text
2770 OO
.ui
.mixin
.IconElement
.prototype.getIconTitle = function () {
2771 return this.iconTitle
;
2775 * IndicatorElement is often mixed into other classes to generate an indicator.
2776 * Indicators are small graphics that are generally used in two ways:
2778 * - To draw attention to the status of an item. For example, an indicator might be
2779 * used to show that an item in a list has errors that need to be resolved.
2780 * - To clarify the function of a control that acts in an exceptional way (a button
2781 * that opens a menu instead of performing an action directly, for example).
2783 * For a list of indicators included in the library, please see the
2784 * [OOUI documentation on MediaWiki] [1].
2786 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2792 * @param {Object} [config] Configuration options
2793 * @cfg {jQuery} [$indicator] The indicator element created by the class. If this
2794 * configuration is omitted, the indicator element will use a generated `<span>`.
2795 * @cfg {string} [indicator] Symbolic name of the indicator (e.g., ‘clear’ or ‘down’).
2796 * See the [OOUI documentation on MediaWiki][2] for a list of indicators included
2798 * [2]: https://www.mediawiki.org/wiki/OOUI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2799 * @cfg {string|Function} [indicatorTitle] A text string used as the indicator title,
2800 * or a function that returns title text. The indicator title is displayed when users move
2801 * the mouse over the indicator.
2803 OO
.ui
.mixin
.IndicatorElement
= function OoUiMixinIndicatorElement( config
) {
2804 // Configuration initialization
2805 config
= config
|| {};
2808 this.$indicator
= null;
2809 this.indicator
= null;
2810 this.indicatorTitle
= null;
2813 this.setIndicator( config
.indicator
|| this.constructor.static.indicator
);
2814 this.setIndicatorTitle( config
.indicatorTitle
|| this.constructor.static.indicatorTitle
);
2815 this.setIndicatorElement( config
.$indicator
|| $( '<span>' ) );
2820 OO
.initClass( OO
.ui
.mixin
.IndicatorElement
);
2822 /* Static Properties */
2825 * Symbolic name of the indicator (e.g., ‘clear’ or ‘down’).
2826 * The static property will be overridden if the #indicator configuration is used.
2830 * @property {string|null}
2832 OO
.ui
.mixin
.IndicatorElement
.static.indicator
= null;
2835 * A text string used as the indicator title, a function that returns title text, or `null`
2836 * for no title. The static property will be overridden if the #indicatorTitle configuration is used.
2840 * @property {string|Function|null}
2842 OO
.ui
.mixin
.IndicatorElement
.static.indicatorTitle
= null;
2847 * Set the indicator element.
2849 * If an element is already set, it will be cleaned up before setting up the new element.
2851 * @param {jQuery} $indicator Element to use as indicator
2853 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorElement = function ( $indicator
) {
2854 if ( this.$indicator
) {
2856 .removeClass( 'oo-ui-indicatorElement-indicator oo-ui-indicator-' + this.indicator
)
2857 .removeAttr( 'title' );
2860 this.$indicator
= $indicator
2861 .addClass( 'oo-ui-indicatorElement-indicator' )
2862 .toggleClass( 'oo-ui-indicatorElement-noIndicator', !this.indicator
)
2863 .toggleClass( 'oo-ui-indicator-' + this.indicator
, !!this.indicator
);
2864 if ( this.indicatorTitle
!== null ) {
2865 this.$indicator
.attr( 'title', this.indicatorTitle
);
2868 this.updateThemeClasses();
2872 * Set the indicator by its symbolic name: ‘clear’, ‘down’, ‘required’, ‘search’, ‘up’. Use `null` to remove the indicator.
2874 * @param {string|null} indicator Symbolic name of indicator, or `null` for no indicator
2877 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicator = function ( indicator
) {
2878 indicator
= typeof indicator
=== 'string' && indicator
.length
? indicator
.trim() : null;
2880 if ( this.indicator
!== indicator
) {
2881 if ( this.$indicator
) {
2882 if ( this.indicator
!== null ) {
2883 this.$indicator
.removeClass( 'oo-ui-indicator-' + this.indicator
);
2885 if ( indicator
!== null ) {
2886 this.$indicator
.addClass( 'oo-ui-indicator-' + indicator
);
2889 this.indicator
= indicator
;
2892 this.$element
.toggleClass( 'oo-ui-indicatorElement', !!this.indicator
);
2893 if ( this.$indicator
) {
2894 this.$indicator
.toggleClass( 'oo-ui-indicatorElement-noIndicator', !this.indicator
);
2896 this.updateThemeClasses();
2902 * Set the indicator title.
2904 * The title is displayed when a user moves the mouse over the indicator.
2906 * @param {string|Function|null} indicatorTitle Indicator title text, a function that returns text, or
2907 * `null` for no indicator title
2910 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorTitle = function ( indicatorTitle
) {
2912 ( typeof indicatorTitle
=== 'function' || ( typeof indicatorTitle
=== 'string' && indicatorTitle
.length
) ) ?
2913 OO
.ui
.resolveMsg( indicatorTitle
) : null;
2915 if ( this.indicatorTitle
!== indicatorTitle
) {
2916 this.indicatorTitle
= indicatorTitle
;
2917 if ( this.$indicator
) {
2918 if ( this.indicatorTitle
!== null ) {
2919 this.$indicator
.attr( 'title', indicatorTitle
);
2921 this.$indicator
.removeAttr( 'title' );
2930 * Get the symbolic name of the indicator (e.g., ‘clear’ or ‘down’).
2932 * @return {string} Symbolic name of indicator
2934 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicator = function () {
2935 return this.indicator
;
2939 * Get the indicator title.
2941 * The title is displayed when a user moves the mouse over the indicator.
2943 * @return {string} Indicator title text
2945 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicatorTitle = function () {
2946 return this.indicatorTitle
;
2950 * LabelElement is often mixed into other classes to generate a label, which
2951 * helps identify the function of an interface element.
2952 * See the [OOUI documentation on MediaWiki] [1] for more information.
2954 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Icons,_Indicators,_and_Labels#Labels
2960 * @param {Object} [config] Configuration options
2961 * @cfg {jQuery} [$label] The label element created by the class. If this
2962 * configuration is omitted, the label element will use a generated `<span>`.
2963 * @cfg {jQuery|string|Function|OO.ui.HtmlSnippet} [label] The label text. The label can be specified
2964 * as a plaintext string, a jQuery selection of elements, or a function that will produce a string
2965 * in the future. See the [OOUI documentation on MediaWiki] [2] for examples.
2966 * [2]: https://www.mediawiki.org/wiki/OOUI/Widgets/Icons,_Indicators,_and_Labels#Labels
2968 OO
.ui
.mixin
.LabelElement
= function OoUiMixinLabelElement( config
) {
2969 // Configuration initialization
2970 config
= config
|| {};
2977 this.setLabel( config
.label
|| this.constructor.static.label
);
2978 this.setLabelElement( config
.$label
|| $( '<span>' ) );
2983 OO
.initClass( OO
.ui
.mixin
.LabelElement
);
2988 * @event labelChange
2989 * @param {string} value
2992 /* Static Properties */
2995 * The label text. The label can be specified as a plaintext string, a function that will
2996 * produce a string in the future, or `null` for no label. The static value will
2997 * be overridden if a label is specified with the #label config option.
3001 * @property {string|Function|null}
3003 OO
.ui
.mixin
.LabelElement
.static.label
= null;
3005 /* Static methods */
3008 * Highlight the first occurrence of the query in the given text
3010 * @param {string} text Text
3011 * @param {string} query Query to find
3012 * @param {Function} [compare] Optional string comparator, e.g. Intl.Collator().compare
3013 * @return {jQuery} Text with the first match of the query
3014 * sub-string wrapped in highlighted span
3016 OO
.ui
.mixin
.LabelElement
.static.highlightQuery = function ( text
, query
, compare
) {
3019 $result
= $( '<span>' );
3023 qLen
= query
.length
;
3024 for ( i
= 0; offset
=== -1 && i
<= tLen
- qLen
; i
++ ) {
3025 if ( compare( query
, text
.slice( i
, i
+ qLen
) ) === 0 ) {
3030 offset
= text
.toLowerCase().indexOf( query
.toLowerCase() );
3033 if ( !query
.length
|| offset
=== -1 ) {
3034 $result
.text( text
);
3037 document
.createTextNode( text
.slice( 0, offset
) ),
3039 .addClass( 'oo-ui-labelElement-label-highlight' )
3040 .text( text
.slice( offset
, offset
+ query
.length
) ),
3041 document
.createTextNode( text
.slice( offset
+ query
.length
) )
3044 return $result
.contents();
3050 * Set the label element.
3052 * If an element is already set, it will be cleaned up before setting up the new element.
3054 * @param {jQuery} $label Element to use as label
3056 OO
.ui
.mixin
.LabelElement
.prototype.setLabelElement = function ( $label
) {
3057 if ( this.$label
) {
3058 this.$label
.removeClass( 'oo-ui-labelElement-label' ).empty();
3061 this.$label
= $label
.addClass( 'oo-ui-labelElement-label' );
3062 this.setLabelContent( this.label
);
3068 * An empty string will result in the label being hidden. A string containing only whitespace will
3069 * be converted to a single ` `.
3071 * @param {jQuery|string|OO.ui.HtmlSnippet|Function|null} label Label nodes; text; a function that returns nodes or
3072 * text; or null for no label
3075 OO
.ui
.mixin
.LabelElement
.prototype.setLabel = function ( label
) {
3076 label
= typeof label
=== 'function' ? OO
.ui
.resolveMsg( label
) : label
;
3077 label
= ( ( typeof label
=== 'string' || label
instanceof jQuery
) && label
.length
) || ( label
instanceof OO
.ui
.HtmlSnippet
&& label
.toString().length
) ? label
: null;
3079 if ( this.label
!== label
) {
3080 if ( this.$label
) {
3081 this.setLabelContent( label
);
3084 this.emit( 'labelChange' );
3087 this.$element
.toggleClass( 'oo-ui-labelElement', !!this.label
);
3093 * Set the label as plain text with a highlighted query
3095 * @param {string} text Text label to set
3096 * @param {string} query Substring of text to highlight
3097 * @param {Function} [compare] Optional string comparator, e.g. Intl.Collator().compare
3100 OO
.ui
.mixin
.LabelElement
.prototype.setHighlightedQuery = function ( text
, query
, compare
) {
3101 return this.setLabel( this.constructor.static.highlightQuery( text
, query
, compare
) );
3107 * @return {jQuery|string|Function|null} Label nodes; text; a function that returns nodes or
3108 * text; or null for no label
3110 OO
.ui
.mixin
.LabelElement
.prototype.getLabel = function () {
3115 * Set the content of the label.
3117 * Do not call this method until after the label element has been set by #setLabelElement.
3120 * @param {jQuery|string|Function|null} label Label nodes; text; a function that returns nodes or
3121 * text; or null for no label
3123 OO
.ui
.mixin
.LabelElement
.prototype.setLabelContent = function ( label
) {
3124 if ( typeof label
=== 'string' ) {
3125 if ( label
.match( /^\s*$/ ) ) {
3126 // Convert whitespace only string to a single non-breaking space
3127 this.$label
.html( ' ' );
3129 this.$label
.text( label
);
3131 } else if ( label
instanceof OO
.ui
.HtmlSnippet
) {
3132 this.$label
.html( label
.toString() );
3133 } else if ( label
instanceof jQuery
) {
3134 this.$label
.empty().append( label
);
3136 this.$label
.empty();
3141 * The FlaggedElement class is an attribute mixin, meaning that it is used to add
3142 * additional functionality to an element created by another class. The class provides
3143 * a ‘flags’ property assigned the name (or an array of names) of styling flags,
3144 * which are used to customize the look and feel of a widget to better describe its
3145 * importance and functionality.
3147 * The library currently contains the following styling flags for general use:
3149 * - **progressive**: Progressive styling is applied to convey that the widget will move the user forward in a process.
3150 * - **destructive**: Destructive styling is applied to convey that the widget will remove something.
3152 * The flags affect the appearance of the buttons:
3155 * // FlaggedElement is mixed into ButtonWidget to provide styling flags
3156 * var button1 = new OO.ui.ButtonWidget( {
3157 * label: 'Progressive',
3158 * flags: 'progressive'
3160 * var button2 = new OO.ui.ButtonWidget( {
3161 * label: 'Destructive',
3162 * flags: 'destructive'
3164 * $( 'body' ).append( button1.$element, button2.$element );
3166 * {@link OO.ui.ActionWidget ActionWidgets}, which are a special kind of button that execute an action, use these flags: **primary** and **safe**.
3167 * Please see the [OOUI documentation on MediaWiki] [1] for more information.
3169 * [1]: https://www.mediawiki.org/wiki/OOUI/Elements/Flagged
3175 * @param {Object} [config] Configuration options
3176 * @cfg {string|string[]} [flags] The name or names of the flags (e.g., 'progressive' or 'primary') to apply.
3177 * Please see the [OOUI documentation on MediaWiki] [2] for more information about available flags.
3178 * [2]: https://www.mediawiki.org/wiki/OOUI/Elements/Flagged
3179 * @cfg {jQuery} [$flagged] The flagged element. By default,
3180 * the flagged functionality is applied to the element created by the class ($element).
3181 * If a different element is specified, the flagged functionality will be applied to it instead.
3183 OO
.ui
.mixin
.FlaggedElement
= function OoUiMixinFlaggedElement( config
) {
3184 // Configuration initialization
3185 config
= config
|| {};
3189 this.$flagged
= null;
3192 this.setFlags( config
.flags
);
3193 this.setFlaggedElement( config
.$flagged
|| this.$element
);
3200 * A flag event is emitted when the #clearFlags or #setFlags methods are used. The `changes`
3201 * parameter contains the name of each modified flag and indicates whether it was
3204 * @param {Object.<string,boolean>} changes Object keyed by flag name. A Boolean `true` indicates
3205 * that the flag was added, `false` that the flag was removed.
3211 * Set the flagged element.
3213 * This method is used to retarget a flagged mixin so that its functionality applies to the specified element.
3214 * If an element is already set, the method will remove the mixin’s effect on that element.
3216 * @param {jQuery} $flagged Element that should be flagged
3218 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlaggedElement = function ( $flagged
) {
3219 var classNames
= Object
.keys( this.flags
).map( function ( flag
) {
3220 return 'oo-ui-flaggedElement-' + flag
;
3223 if ( this.$flagged
) {
3224 this.$flagged
.removeClass( classNames
);
3227 this.$flagged
= $flagged
.addClass( classNames
);
3231 * Check if the specified flag is set.
3233 * @param {string} flag Name of flag
3234 * @return {boolean} The flag is set
3236 OO
.ui
.mixin
.FlaggedElement
.prototype.hasFlag = function ( flag
) {
3237 // This may be called before the constructor, thus before this.flags is set
3238 return this.flags
&& ( flag
in this.flags
);
3242 * Get the names of all flags set.
3244 * @return {string[]} Flag names
3246 OO
.ui
.mixin
.FlaggedElement
.prototype.getFlags = function () {
3247 // This may be called before the constructor, thus before this.flags is set
3248 return Object
.keys( this.flags
|| {} );
3257 OO
.ui
.mixin
.FlaggedElement
.prototype.clearFlags = function () {
3258 var flag
, className
,
3261 classPrefix
= 'oo-ui-flaggedElement-';
3263 for ( flag
in this.flags
) {
3264 className
= classPrefix
+ flag
;
3265 changes
[ flag
] = false;
3266 delete this.flags
[ flag
];
3267 remove
.push( className
);
3270 if ( this.$flagged
) {
3271 this.$flagged
.removeClass( remove
);
3274 this.updateThemeClasses();
3275 this.emit( 'flag', changes
);
3281 * Add one or more flags.
3283 * @param {string|string[]|Object.<string, boolean>} flags A flag name, an array of flag names,
3284 * or an object keyed by flag name with a boolean value that indicates whether the flag should
3285 * be added (`true`) or removed (`false`).
3289 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlags = function ( flags
) {
3290 var i
, len
, flag
, className
,
3294 classPrefix
= 'oo-ui-flaggedElement-';
3296 if ( typeof flags
=== 'string' ) {
3297 className
= classPrefix
+ flags
;
3299 if ( !this.flags
[ flags
] ) {
3300 this.flags
[ flags
] = true;
3301 add
.push( className
);
3303 } else if ( Array
.isArray( flags
) ) {
3304 for ( i
= 0, len
= flags
.length
; i
< len
; i
++ ) {
3306 className
= classPrefix
+ flag
;
3308 if ( !this.flags
[ flag
] ) {
3309 changes
[ flag
] = true;
3310 this.flags
[ flag
] = true;
3311 add
.push( className
);
3314 } else if ( OO
.isPlainObject( flags
) ) {
3315 for ( flag
in flags
) {
3316 className
= classPrefix
+ flag
;
3317 if ( flags
[ flag
] ) {
3319 if ( !this.flags
[ flag
] ) {
3320 changes
[ flag
] = true;
3321 this.flags
[ flag
] = true;
3322 add
.push( className
);
3326 if ( this.flags
[ flag
] ) {
3327 changes
[ flag
] = false;
3328 delete this.flags
[ flag
];
3329 remove
.push( className
);
3335 if ( this.$flagged
) {
3338 .removeClass( remove
);
3341 this.updateThemeClasses();
3342 this.emit( 'flag', changes
);
3348 * TitledElement is mixed into other classes to provide a `title` attribute.
3349 * Titles are rendered by the browser and are made visible when the user moves
3350 * the mouse over the element. Titles are not visible on touch devices.
3353 * // TitledElement provides a 'title' attribute to the
3354 * // ButtonWidget class
3355 * var button = new OO.ui.ButtonWidget( {
3356 * label: 'Button with Title',
3357 * title: 'I am a button'
3359 * $( 'body' ).append( button.$element );
3365 * @param {Object} [config] Configuration options
3366 * @cfg {jQuery} [$titled] The element to which the `title` attribute is applied.
3367 * If this config is omitted, the title functionality is applied to $element, the
3368 * element created by the class.
3369 * @cfg {string|Function} [title] The title text or a function that returns text. If
3370 * this config is omitted, the value of the {@link #static-title static title} property is used.
3372 OO
.ui
.mixin
.TitledElement
= function OoUiMixinTitledElement( config
) {
3373 // Configuration initialization
3374 config
= config
|| {};
3377 this.$titled
= null;
3381 this.setTitle( config
.title
!== undefined ? config
.title
: this.constructor.static.title
);
3382 this.setTitledElement( config
.$titled
|| this.$element
);
3387 OO
.initClass( OO
.ui
.mixin
.TitledElement
);
3389 /* Static Properties */
3392 * The title text, a function that returns text, or `null` for no title. The value of the static property
3393 * is overridden if the #title config option is used.
3397 * @property {string|Function|null}
3399 OO
.ui
.mixin
.TitledElement
.static.title
= null;
3404 * Set the titled element.
3406 * This method is used to retarget a titledElement mixin so that its functionality applies to the specified element.
3407 * If an element is already set, the mixin’s effect on that element is removed before the new element is set up.
3409 * @param {jQuery} $titled Element that should use the 'titled' functionality
3411 OO
.ui
.mixin
.TitledElement
.prototype.setTitledElement = function ( $titled
) {
3412 if ( this.$titled
) {
3413 this.$titled
.removeAttr( 'title' );
3416 this.$titled
= $titled
;
3425 * @param {string|Function|null} title Title text, a function that returns text, or `null` for no title
3428 OO
.ui
.mixin
.TitledElement
.prototype.setTitle = function ( title
) {
3429 title
= typeof title
=== 'function' ? OO
.ui
.resolveMsg( title
) : title
;
3430 title
= ( typeof title
=== 'string' && title
.length
) ? title
: null;
3432 if ( this.title
!== title
) {
3441 * Update the title attribute, in case of changes to title or accessKey.
3446 OO
.ui
.mixin
.TitledElement
.prototype.updateTitle = function () {
3447 var title
= this.getTitle();
3448 if ( this.$titled
) {
3449 if ( title
!== null ) {
3450 // Only if this is an AccessKeyedElement
3451 if ( this.formatTitleWithAccessKey
) {
3452 title
= this.formatTitleWithAccessKey( title
);
3454 this.$titled
.attr( 'title', title
);
3456 this.$titled
.removeAttr( 'title' );
3465 * @return {string} Title string
3467 OO
.ui
.mixin
.TitledElement
.prototype.getTitle = function () {
3472 * AccessKeyedElement is mixed into other classes to provide an `accesskey` attribute.
3473 * Accesskeys allow an user to go to a specific element by using
3474 * a shortcut combination of a browser specific keys + the key
3478 * // AccessKeyedElement provides an 'accesskey' attribute to the
3479 * // ButtonWidget class
3480 * var button = new OO.ui.ButtonWidget( {
3481 * label: 'Button with Accesskey',
3484 * $( 'body' ).append( button.$element );
3490 * @param {Object} [config] Configuration options
3491 * @cfg {jQuery} [$accessKeyed] The element to which the `accesskey` attribute is applied.
3492 * If this config is omitted, the accesskey functionality is applied to $element, the
3493 * element created by the class.
3494 * @cfg {string|Function} [accessKey] The key or a function that returns the key. If
3495 * this config is omitted, no accesskey will be added.
3497 OO
.ui
.mixin
.AccessKeyedElement
= function OoUiMixinAccessKeyedElement( config
) {
3498 // Configuration initialization
3499 config
= config
|| {};
3502 this.$accessKeyed
= null;
3503 this.accessKey
= null;
3506 this.setAccessKey( config
.accessKey
|| null );
3507 this.setAccessKeyedElement( config
.$accessKeyed
|| this.$element
);
3509 // If this is also a TitledElement and it initialized before we did, we may have
3510 // to update the title with the access key
3511 if ( this.updateTitle
) {
3518 OO
.initClass( OO
.ui
.mixin
.AccessKeyedElement
);
3520 /* Static Properties */
3523 * The access key, a function that returns a key, or `null` for no accesskey.
3527 * @property {string|Function|null}
3529 OO
.ui
.mixin
.AccessKeyedElement
.static.accessKey
= null;
3534 * Set the accesskeyed element.
3536 * This method is used to retarget a AccessKeyedElement mixin so that its functionality applies to the specified element.
3537 * If an element is already set, the mixin's effect on that element is removed before the new element is set up.
3539 * @param {jQuery} $accessKeyed Element that should use the 'accesskeyes' functionality
3541 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKeyedElement = function ( $accessKeyed
) {
3542 if ( this.$accessKeyed
) {
3543 this.$accessKeyed
.removeAttr( 'accesskey' );
3546 this.$accessKeyed
= $accessKeyed
;
3547 if ( this.accessKey
) {
3548 this.$accessKeyed
.attr( 'accesskey', this.accessKey
);
3555 * @param {string|Function|null} accessKey Key, a function that returns a key, or `null` for no accesskey
3558 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKey = function ( accessKey
) {
3559 accessKey
= typeof accessKey
=== 'string' ? OO
.ui
.resolveMsg( accessKey
) : null;
3561 if ( this.accessKey
!== accessKey
) {
3562 if ( this.$accessKeyed
) {
3563 if ( accessKey
!== null ) {
3564 this.$accessKeyed
.attr( 'accesskey', accessKey
);
3566 this.$accessKeyed
.removeAttr( 'accesskey' );
3569 this.accessKey
= accessKey
;
3571 // Only if this is a TitledElement
3572 if ( this.updateTitle
) {
3583 * @return {string} accessKey string
3585 OO
.ui
.mixin
.AccessKeyedElement
.prototype.getAccessKey = function () {
3586 return this.accessKey
;
3590 * Add information about the access key to the element's tooltip label.
3591 * (This is only public for hacky usage in FieldLayout.)
3593 * @param {string} title Tooltip label for `title` attribute
3596 OO
.ui
.mixin
.AccessKeyedElement
.prototype.formatTitleWithAccessKey = function ( title
) {
3599 if ( !this.$accessKeyed
) {
3600 // Not initialized yet; the constructor will call updateTitle() which will rerun this function
3603 // Use jquery.accessKeyLabel if available to show modifiers, otherwise just display the single key
3604 if ( $.fn
.updateTooltipAccessKeys
&& $.fn
.updateTooltipAccessKeys
.getAccessKeyLabel
) {
3605 accessKey
= $.fn
.updateTooltipAccessKeys
.getAccessKeyLabel( this.$accessKeyed
[ 0 ] );
3607 accessKey
= this.getAccessKey();
3610 title
+= ' [' + accessKey
+ ']';
3616 * ButtonWidget is a generic widget for buttons. A wide variety of looks,
3617 * feels, and functionality can be customized via the class’s configuration options
3618 * and methods. Please see the [OOUI documentation on MediaWiki] [1] for more information
3621 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Buttons_and_Switches
3624 * // A button widget
3625 * var button = new OO.ui.ButtonWidget( {
3626 * label: 'Button with Icon',
3630 * $( 'body' ).append( button.$element );
3632 * NOTE: HTML form buttons should use the OO.ui.ButtonInputWidget class.
3635 * @extends OO.ui.Widget
3636 * @mixins OO.ui.mixin.ButtonElement
3637 * @mixins OO.ui.mixin.IconElement
3638 * @mixins OO.ui.mixin.IndicatorElement
3639 * @mixins OO.ui.mixin.LabelElement
3640 * @mixins OO.ui.mixin.TitledElement
3641 * @mixins OO.ui.mixin.FlaggedElement
3642 * @mixins OO.ui.mixin.TabIndexedElement
3643 * @mixins OO.ui.mixin.AccessKeyedElement
3646 * @param {Object} [config] Configuration options
3647 * @cfg {boolean} [active=false] Whether button should be shown as active
3648 * @cfg {string} [href] Hyperlink to visit when the button is clicked.
3649 * @cfg {string} [target] The frame or window in which to open the hyperlink.
3650 * @cfg {boolean} [noFollow] Search engine traversal hint (default: true)
3652 OO
.ui
.ButtonWidget
= function OoUiButtonWidget( config
) {
3653 // Configuration initialization
3654 config
= config
|| {};
3656 // Parent constructor
3657 OO
.ui
.ButtonWidget
.parent
.call( this, config
);
3659 // Mixin constructors
3660 OO
.ui
.mixin
.ButtonElement
.call( this, config
);
3661 OO
.ui
.mixin
.IconElement
.call( this, config
);
3662 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
3663 OO
.ui
.mixin
.LabelElement
.call( this, config
);
3664 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$button
} ) );
3665 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
3666 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$button
} ) );
3667 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$button
} ) );
3672 this.noFollow
= false;
3675 this.connect( this, { disable
: 'onDisable' } );
3678 this.$button
.append( this.$icon
, this.$label
, this.$indicator
);
3680 .addClass( 'oo-ui-buttonWidget' )
3681 .append( this.$button
);
3682 this.setActive( config
.active
);
3683 this.setHref( config
.href
);
3684 this.setTarget( config
.target
);
3685 this.setNoFollow( config
.noFollow
);
3690 OO
.inheritClass( OO
.ui
.ButtonWidget
, OO
.ui
.Widget
);
3691 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.ButtonElement
);
3692 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IconElement
);
3693 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IndicatorElement
);
3694 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.LabelElement
);
3695 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TitledElement
);
3696 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.FlaggedElement
);
3697 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TabIndexedElement
);
3698 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
3700 /* Static Properties */
3706 OO
.ui
.ButtonWidget
.static.cancelButtonMouseDownEvents
= false;
3712 OO
.ui
.ButtonWidget
.static.tagName
= 'span';
3717 * Get hyperlink location.
3719 * @return {string} Hyperlink location
3721 OO
.ui
.ButtonWidget
.prototype.getHref = function () {
3726 * Get hyperlink target.
3728 * @return {string} Hyperlink target
3730 OO
.ui
.ButtonWidget
.prototype.getTarget = function () {
3735 * Get search engine traversal hint.
3737 * @return {boolean} Whether search engines should avoid traversing this hyperlink
3739 OO
.ui
.ButtonWidget
.prototype.getNoFollow = function () {
3740 return this.noFollow
;
3744 * Set hyperlink location.
3746 * @param {string|null} href Hyperlink location, null to remove
3748 OO
.ui
.ButtonWidget
.prototype.setHref = function ( href
) {
3749 href
= typeof href
=== 'string' ? href
: null;
3750 if ( href
!== null && !OO
.ui
.isSafeUrl( href
) ) {
3754 if ( href
!== this.href
) {
3763 * Update the `href` attribute, in case of changes to href or
3769 OO
.ui
.ButtonWidget
.prototype.updateHref = function () {
3770 if ( this.href
!== null && !this.isDisabled() ) {
3771 this.$button
.attr( 'href', this.href
);
3773 this.$button
.removeAttr( 'href' );
3780 * Handle disable events.
3783 * @param {boolean} disabled Element is disabled
3785 OO
.ui
.ButtonWidget
.prototype.onDisable = function () {
3790 * Set hyperlink target.
3792 * @param {string|null} target Hyperlink target, null to remove
3794 OO
.ui
.ButtonWidget
.prototype.setTarget = function ( target
) {
3795 target
= typeof target
=== 'string' ? target
: null;
3797 if ( target
!== this.target
) {
3798 this.target
= target
;
3799 if ( target
!== null ) {
3800 this.$button
.attr( 'target', target
);
3802 this.$button
.removeAttr( 'target' );
3810 * Set search engine traversal hint.
3812 * @param {boolean} noFollow True if search engines should avoid traversing this hyperlink
3814 OO
.ui
.ButtonWidget
.prototype.setNoFollow = function ( noFollow
) {
3815 noFollow
= typeof noFollow
=== 'boolean' ? noFollow
: true;
3817 if ( noFollow
!== this.noFollow
) {
3818 this.noFollow
= noFollow
;
3820 this.$button
.attr( 'rel', 'nofollow' );
3822 this.$button
.removeAttr( 'rel' );
3829 // Override method visibility hints from ButtonElement
3840 * A ButtonGroupWidget groups related buttons and is used together with OO.ui.ButtonWidget and
3841 * its subclasses. Each button in a group is addressed by a unique reference. Buttons can be added,
3842 * removed, and cleared from the group.
3845 * // Example: A ButtonGroupWidget with two buttons
3846 * var button1 = new OO.ui.PopupButtonWidget( {
3847 * label: 'Select a category',
3850 * $content: $( '<p>List of categories...</p>' ),
3855 * var button2 = new OO.ui.ButtonWidget( {
3858 * var buttonGroup = new OO.ui.ButtonGroupWidget( {
3859 * items: [button1, button2]
3861 * $( 'body' ).append( buttonGroup.$element );
3864 * @extends OO.ui.Widget
3865 * @mixins OO.ui.mixin.GroupElement
3868 * @param {Object} [config] Configuration options
3869 * @cfg {OO.ui.ButtonWidget[]} [items] Buttons to add
3871 OO
.ui
.ButtonGroupWidget
= function OoUiButtonGroupWidget( config
) {
3872 // Configuration initialization
3873 config
= config
|| {};
3875 // Parent constructor
3876 OO
.ui
.ButtonGroupWidget
.parent
.call( this, config
);
3878 // Mixin constructors
3879 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
3882 this.$element
.addClass( 'oo-ui-buttonGroupWidget' );
3883 if ( Array
.isArray( config
.items
) ) {
3884 this.addItems( config
.items
);
3890 OO
.inheritClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.Widget
);
3891 OO
.mixinClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.mixin
.GroupElement
);
3893 /* Static Properties */
3899 OO
.ui
.ButtonGroupWidget
.static.tagName
= 'span';
3908 OO
.ui
.ButtonGroupWidget
.prototype.focus = function () {
3909 if ( !this.isDisabled() ) {
3910 if ( this.items
[ 0 ] ) {
3911 this.items
[ 0 ].focus();
3920 OO
.ui
.ButtonGroupWidget
.prototype.simulateLabelClick = function () {
3925 * IconWidget is a generic widget for {@link OO.ui.mixin.IconElement icons}. In general, IconWidgets should be used with OO.ui.LabelWidget,
3926 * which creates a label that identifies the icon’s function. See the [OOUI documentation on MediaWiki] [1]
3927 * for a list of icons included in the library.
3930 * // An icon widget with a label
3931 * var myIcon = new OO.ui.IconWidget( {
3935 * // Create a label.
3936 * var iconLabel = new OO.ui.LabelWidget( {
3939 * $( 'body' ).append( myIcon.$element, iconLabel.$element );
3941 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Icons,_Indicators,_and_Labels#Icons
3944 * @extends OO.ui.Widget
3945 * @mixins OO.ui.mixin.IconElement
3946 * @mixins OO.ui.mixin.TitledElement
3947 * @mixins OO.ui.mixin.FlaggedElement
3950 * @param {Object} [config] Configuration options
3952 OO
.ui
.IconWidget
= function OoUiIconWidget( config
) {
3953 // Configuration initialization
3954 config
= config
|| {};
3956 // Parent constructor
3957 OO
.ui
.IconWidget
.parent
.call( this, config
);
3959 // Mixin constructors
3960 OO
.ui
.mixin
.IconElement
.call( this, $.extend( {}, config
, { $icon
: this.$element
} ) );
3961 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3962 OO
.ui
.mixin
.FlaggedElement
.call( this, $.extend( {}, config
, { $flagged
: this.$element
} ) );
3965 this.$element
.addClass( 'oo-ui-iconWidget' );
3970 OO
.inheritClass( OO
.ui
.IconWidget
, OO
.ui
.Widget
);
3971 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.IconElement
);
3972 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.TitledElement
);
3973 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.FlaggedElement
);
3975 /* Static Properties */
3981 OO
.ui
.IconWidget
.static.tagName
= 'span';
3984 * IndicatorWidgets create indicators, which are small graphics that are generally used to draw
3985 * attention to the status of an item or to clarify the function within a control. For a list of
3986 * indicators included in the library, please see the [OOUI documentation on MediaWiki][1].
3989 * // Example of an indicator widget
3990 * var indicator1 = new OO.ui.IndicatorWidget( {
3991 * indicator: 'required'
3994 * // Create a fieldset layout to add a label
3995 * var fieldset = new OO.ui.FieldsetLayout();
3996 * fieldset.addItems( [
3997 * new OO.ui.FieldLayout( indicator1, { label: 'A required indicator:' } )
3999 * $( 'body' ).append( fieldset.$element );
4001 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Icons,_Indicators,_and_Labels#Indicators
4004 * @extends OO.ui.Widget
4005 * @mixins OO.ui.mixin.IndicatorElement
4006 * @mixins OO.ui.mixin.TitledElement
4009 * @param {Object} [config] Configuration options
4011 OO
.ui
.IndicatorWidget
= function OoUiIndicatorWidget( config
) {
4012 // Configuration initialization
4013 config
= config
|| {};
4015 // Parent constructor
4016 OO
.ui
.IndicatorWidget
.parent
.call( this, config
);
4018 // Mixin constructors
4019 OO
.ui
.mixin
.IndicatorElement
.call( this, $.extend( {}, config
, { $indicator
: this.$element
} ) );
4020 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
4023 this.$element
.addClass( 'oo-ui-indicatorWidget' );
4028 OO
.inheritClass( OO
.ui
.IndicatorWidget
, OO
.ui
.Widget
);
4029 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.IndicatorElement
);
4030 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.TitledElement
);
4032 /* Static Properties */
4038 OO
.ui
.IndicatorWidget
.static.tagName
= 'span';
4041 * LabelWidgets help identify the function of interface elements. Each LabelWidget can
4042 * be configured with a `label` option that is set to a string, a label node, or a function:
4044 * - String: a plaintext string
4045 * - jQuery selection: a jQuery selection, used for anything other than a plaintext label, e.g., a
4046 * label that includes a link or special styling, such as a gray color or additional graphical elements.
4047 * - Function: a function that will produce a string in the future. Functions are used
4048 * in cases where the value of the label is not currently defined.
4050 * In addition, the LabelWidget can be associated with an {@link OO.ui.InputWidget input widget}, which
4051 * will come into focus when the label is clicked.
4054 * // Examples of LabelWidgets
4055 * var label1 = new OO.ui.LabelWidget( {
4056 * label: 'plaintext label'
4058 * var label2 = new OO.ui.LabelWidget( {
4059 * label: $( '<a href="default.html">jQuery label</a>' )
4061 * // Create a fieldset layout with fields for each example
4062 * var fieldset = new OO.ui.FieldsetLayout();
4063 * fieldset.addItems( [
4064 * new OO.ui.FieldLayout( label1 ),
4065 * new OO.ui.FieldLayout( label2 )
4067 * $( 'body' ).append( fieldset.$element );
4070 * @extends OO.ui.Widget
4071 * @mixins OO.ui.mixin.LabelElement
4072 * @mixins OO.ui.mixin.TitledElement
4075 * @param {Object} [config] Configuration options
4076 * @cfg {OO.ui.InputWidget} [input] {@link OO.ui.InputWidget Input widget} that uses the label.
4077 * Clicking the label will focus the specified input field.
4079 OO
.ui
.LabelWidget
= function OoUiLabelWidget( config
) {
4080 // Configuration initialization
4081 config
= config
|| {};
4083 // Parent constructor
4084 OO
.ui
.LabelWidget
.parent
.call( this, config
);
4086 // Mixin constructors
4087 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: this.$element
} ) );
4088 OO
.ui
.mixin
.TitledElement
.call( this, config
);
4091 this.input
= config
.input
;
4095 if ( this.input
.getInputId() ) {
4096 this.$element
.attr( 'for', this.input
.getInputId() );
4098 this.$label
.on( 'click', function () {
4099 this.input
.simulateLabelClick();
4103 this.$element
.addClass( 'oo-ui-labelWidget' );
4108 OO
.inheritClass( OO
.ui
.LabelWidget
, OO
.ui
.Widget
);
4109 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.LabelElement
);
4110 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.TitledElement
);
4112 /* Static Properties */
4118 OO
.ui
.LabelWidget
.static.tagName
= 'label';
4121 * PendingElement is a mixin that is used to create elements that notify users that something is happening
4122 * and that they should wait before proceeding. The pending state is visually represented with a pending
4123 * texture that appears in the head of a pending {@link OO.ui.ProcessDialog process dialog} or in the input
4124 * field of a {@link OO.ui.TextInputWidget text input widget}.
4126 * Currently, {@link OO.ui.ActionWidget Action widgets}, which mix in this class, can also be marked as pending, but only when
4127 * used in {@link OO.ui.MessageDialog message dialogs}. The behavior is not currently supported for action widgets used
4128 * in process dialogs.
4131 * function MessageDialog( config ) {
4132 * MessageDialog.parent.call( this, config );
4134 * OO.inheritClass( MessageDialog, OO.ui.MessageDialog );
4136 * MessageDialog.static.name = 'myMessageDialog';
4137 * MessageDialog.static.actions = [
4138 * { action: 'save', label: 'Done', flags: 'primary' },
4139 * { label: 'Cancel', flags: 'safe' }
4142 * MessageDialog.prototype.initialize = function () {
4143 * MessageDialog.parent.prototype.initialize.apply( this, arguments );
4144 * this.content = new OO.ui.PanelLayout( { padded: true } );
4145 * 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>' );
4146 * this.$body.append( this.content.$element );
4148 * MessageDialog.prototype.getBodyHeight = function () {
4151 * MessageDialog.prototype.getActionProcess = function ( action ) {
4152 * var dialog = this;
4153 * if ( action === 'save' ) {
4154 * dialog.getActions().get({actions: 'save'})[0].pushPending();
4155 * return new OO.ui.Process()
4157 * .next( function () {
4158 * dialog.getActions().get({actions: 'save'})[0].popPending();
4161 * return MessageDialog.parent.prototype.getActionProcess.call( this, action );
4164 * var windowManager = new OO.ui.WindowManager();
4165 * $( 'body' ).append( windowManager.$element );
4167 * var dialog = new MessageDialog();
4168 * windowManager.addWindows( [ dialog ] );
4169 * windowManager.openWindow( dialog );
4175 * @param {Object} [config] Configuration options
4176 * @cfg {jQuery} [$pending] Element to mark as pending, defaults to this.$element
4178 OO
.ui
.mixin
.PendingElement
= function OoUiMixinPendingElement( config
) {
4179 // Configuration initialization
4180 config
= config
|| {};
4184 this.$pending
= null;
4187 this.setPendingElement( config
.$pending
|| this.$element
);
4192 OO
.initClass( OO
.ui
.mixin
.PendingElement
);
4197 * Set the pending element (and clean up any existing one).
4199 * @param {jQuery} $pending The element to set to pending.
4201 OO
.ui
.mixin
.PendingElement
.prototype.setPendingElement = function ( $pending
) {
4202 if ( this.$pending
) {
4203 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
4206 this.$pending
= $pending
;
4207 if ( this.pending
> 0 ) {
4208 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
4213 * Check if an element is pending.
4215 * @return {boolean} Element is pending
4217 OO
.ui
.mixin
.PendingElement
.prototype.isPending = function () {
4218 return !!this.pending
;
4222 * Increase the pending counter. The pending state will remain active until the counter is zero
4223 * (i.e., the number of calls to #pushPending and #popPending is the same).
4227 OO
.ui
.mixin
.PendingElement
.prototype.pushPending = function () {
4228 if ( this.pending
=== 0 ) {
4229 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
4230 this.updateThemeClasses();
4238 * Decrease the pending counter. The pending state will remain active until the counter is zero
4239 * (i.e., the number of calls to #pushPending and #popPending is the same).
4243 OO
.ui
.mixin
.PendingElement
.prototype.popPending = function () {
4244 if ( this.pending
=== 1 ) {
4245 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
4246 this.updateThemeClasses();
4248 this.pending
= Math
.max( 0, this.pending
- 1 );
4254 * Element that will stick adjacent to a specified container, even when it is inserted elsewhere
4255 * in the document (for example, in an OO.ui.Window's $overlay).
4257 * The elements's position is automatically calculated and maintained when window is resized or the
4258 * page is scrolled. If you reposition the container manually, you have to call #position to make
4259 * sure the element is still placed correctly.
4261 * As positioning is only possible when both the element and the container are attached to the DOM
4262 * and visible, it's only done after you call #togglePositioning. You might want to do this inside
4263 * the #toggle method to display a floating popup, for example.
4269 * @param {Object} [config] Configuration options
4270 * @cfg {jQuery} [$floatable] Node to position, assigned to #$floatable, omit to use #$element
4271 * @cfg {jQuery} [$floatableContainer] Node to position adjacent to
4272 * @cfg {string} [verticalPosition='below'] Where to position $floatable vertically:
4273 * 'below': Directly below $floatableContainer, aligning f's top edge with fC's bottom edge
4274 * 'above': Directly above $floatableContainer, aligning f's bottom edge with fC's top edge
4275 * 'top': Align the top edge with $floatableContainer's top edge
4276 * 'bottom': Align the bottom edge with $floatableContainer's bottom edge
4277 * 'center': Vertically align the center with $floatableContainer's center
4278 * @cfg {string} [horizontalPosition='start'] Where to position $floatable horizontally:
4279 * 'before': Directly before $floatableContainer, aligning f's end edge with fC's start edge
4280 * 'after': Directly after $floatableContainer, algining f's start edge with fC's end edge
4281 * 'start': Align the start (left in LTR, right in RTL) edge with $floatableContainer's start edge
4282 * 'end': Align the end (right in LTR, left in RTL) edge with $floatableContainer's end edge
4283 * 'center': Horizontally align the center with $floatableContainer's center
4284 * @cfg {boolean} [hideWhenOutOfView=true] Whether to hide the floatable element if the container
4287 OO
.ui
.mixin
.FloatableElement
= function OoUiMixinFloatableElement( config
) {
4288 // Configuration initialization
4289 config
= config
|| {};
4292 this.$floatable
= null;
4293 this.$floatableContainer
= null;
4294 this.$floatableWindow
= null;
4295 this.$floatableClosestScrollable
= null;
4296 this.floatableOutOfView
= false;
4297 this.onFloatableScrollHandler
= this.position
.bind( this );
4298 this.onFloatableWindowResizeHandler
= this.position
.bind( this );
4301 this.setFloatableContainer( config
.$floatableContainer
);
4302 this.setFloatableElement( config
.$floatable
|| this.$element
);
4303 this.setVerticalPosition( config
.verticalPosition
|| 'below' );
4304 this.setHorizontalPosition( config
.horizontalPosition
|| 'start' );
4305 this.hideWhenOutOfView
= config
.hideWhenOutOfView
=== undefined ? true : !!config
.hideWhenOutOfView
;
4311 * Set floatable element.
4313 * If an element is already set, it will be cleaned up before setting up the new element.
4315 * @param {jQuery} $floatable Element to make floatable
4317 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableElement = function ( $floatable
) {
4318 if ( this.$floatable
) {
4319 this.$floatable
.removeClass( 'oo-ui-floatableElement-floatable' );
4320 this.$floatable
.css( { left
: '', top
: '' } );
4323 this.$floatable
= $floatable
.addClass( 'oo-ui-floatableElement-floatable' );
4328 * Set floatable container.
4330 * The element will be positioned relative to the specified container.
4332 * @param {jQuery|null} $floatableContainer Container to keep visible, or null to unset
4334 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableContainer = function ( $floatableContainer
) {
4335 this.$floatableContainer
= $floatableContainer
;
4336 if ( this.$floatable
) {
4342 * Change how the element is positioned vertically.
4344 * @param {string} position 'below', 'above', 'top', 'bottom' or 'center'
4346 OO
.ui
.mixin
.FloatableElement
.prototype.setVerticalPosition = function ( position
) {
4347 if ( [ 'below', 'above', 'top', 'bottom', 'center' ].indexOf( position
) === -1 ) {
4348 throw new Error( 'Invalid value for vertical position: ' + position
);
4350 if ( this.verticalPosition
!== position
) {
4351 this.verticalPosition
= position
;
4352 if ( this.$floatable
) {
4359 * Change how the element is positioned horizontally.
4361 * @param {string} position 'before', 'after', 'start', 'end' or 'center'
4363 OO
.ui
.mixin
.FloatableElement
.prototype.setHorizontalPosition = function ( position
) {
4364 if ( [ 'before', 'after', 'start', 'end', 'center' ].indexOf( position
) === -1 ) {
4365 throw new Error( 'Invalid value for horizontal position: ' + position
);
4367 if ( this.horizontalPosition
!== position
) {
4368 this.horizontalPosition
= position
;
4369 if ( this.$floatable
) {
4376 * Toggle positioning.
4378 * Do not turn positioning on until after the element is attached to the DOM and visible.
4380 * @param {boolean} [positioning] Enable positioning, omit to toggle
4383 OO
.ui
.mixin
.FloatableElement
.prototype.togglePositioning = function ( positioning
) {
4384 var closestScrollableOfContainer
;
4386 if ( !this.$floatable
|| !this.$floatableContainer
) {
4390 positioning
= positioning
=== undefined ? !this.positioning
: !!positioning
;
4392 if ( positioning
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
4393 OO
.ui
.warnDeprecation( 'FloatableElement#togglePositioning: Before calling this method, the element must be attached to the DOM.' );
4394 this.warnedUnattached
= true;
4397 if ( this.positioning
!== positioning
) {
4398 this.positioning
= positioning
;
4400 this.needsCustomPosition
=
4401 this.verticalPostion
!== 'below' ||
4402 this.horizontalPosition
!== 'start' ||
4403 !OO
.ui
.contains( this.$floatableContainer
[ 0 ], this.$floatable
[ 0 ] );
4405 closestScrollableOfContainer
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatableContainer
[ 0 ] );
4406 // If the scrollable is the root, we have to listen to scroll events
4407 // on the window because of browser inconsistencies.
4408 if ( $( closestScrollableOfContainer
).is( 'html, body' ) ) {
4409 closestScrollableOfContainer
= OO
.ui
.Element
.static.getWindow( closestScrollableOfContainer
);
4412 if ( positioning
) {
4413 this.$floatableWindow
= $( this.getElementWindow() );
4414 this.$floatableWindow
.on( 'resize', this.onFloatableWindowResizeHandler
);
4416 this.$floatableClosestScrollable
= $( closestScrollableOfContainer
);
4417 this.$floatableClosestScrollable
.on( 'scroll', this.onFloatableScrollHandler
);
4419 // Initial position after visible
4422 if ( this.$floatableWindow
) {
4423 this.$floatableWindow
.off( 'resize', this.onFloatableWindowResizeHandler
);
4424 this.$floatableWindow
= null;
4427 if ( this.$floatableClosestScrollable
) {
4428 this.$floatableClosestScrollable
.off( 'scroll', this.onFloatableScrollHandler
);
4429 this.$floatableClosestScrollable
= null;
4432 this.$floatable
.css( { left
: '', right
: '', top
: '' } );
4440 * Check whether the bottom edge of the given element is within the viewport of the given container.
4443 * @param {jQuery} $element
4444 * @param {jQuery} $container
4447 OO
.ui
.mixin
.FloatableElement
.prototype.isElementInViewport = function ( $element
, $container
) {
4448 var elemRect
, contRect
, topEdgeInBounds
, bottomEdgeInBounds
, leftEdgeInBounds
, rightEdgeInBounds
,
4449 startEdgeInBounds
, endEdgeInBounds
, viewportSpacing
,
4450 direction
= $element
.css( 'direction' );
4452 elemRect
= $element
[ 0 ].getBoundingClientRect();
4453 if ( $container
[ 0 ] === window
) {
4454 viewportSpacing
= OO
.ui
.getViewportSpacing();
4458 right
: document
.documentElement
.clientWidth
,
4459 bottom
: document
.documentElement
.clientHeight
4461 contRect
.top
+= viewportSpacing
.top
;
4462 contRect
.left
+= viewportSpacing
.left
;
4463 contRect
.right
-= viewportSpacing
.right
;
4464 contRect
.bottom
-= viewportSpacing
.bottom
;
4466 contRect
= $container
[ 0 ].getBoundingClientRect();
4469 topEdgeInBounds
= elemRect
.top
>= contRect
.top
&& elemRect
.top
<= contRect
.bottom
;
4470 bottomEdgeInBounds
= elemRect
.bottom
>= contRect
.top
&& elemRect
.bottom
<= contRect
.bottom
;
4471 leftEdgeInBounds
= elemRect
.left
>= contRect
.left
&& elemRect
.left
<= contRect
.right
;
4472 rightEdgeInBounds
= elemRect
.right
>= contRect
.left
&& elemRect
.right
<= contRect
.right
;
4473 if ( direction
=== 'rtl' ) {
4474 startEdgeInBounds
= rightEdgeInBounds
;
4475 endEdgeInBounds
= leftEdgeInBounds
;
4477 startEdgeInBounds
= leftEdgeInBounds
;
4478 endEdgeInBounds
= rightEdgeInBounds
;
4481 if ( this.verticalPosition
=== 'below' && !bottomEdgeInBounds
) {
4484 if ( this.verticalPosition
=== 'above' && !topEdgeInBounds
) {
4487 if ( this.horizontalPosition
=== 'before' && !startEdgeInBounds
) {
4490 if ( this.horizontalPosition
=== 'after' && !endEdgeInBounds
) {
4494 // The other positioning values are all about being inside the container,
4495 // so in those cases all we care about is that any part of the container is visible.
4496 return elemRect
.top
<= contRect
.bottom
&& elemRect
.bottom
>= contRect
.top
&&
4497 elemRect
.left
<= contRect
.right
&& elemRect
.right
>= contRect
.left
;
4501 * Check if the floatable is hidden to the user because it was offscreen.
4503 * @return {boolean} Floatable is out of view
4505 OO
.ui
.mixin
.FloatableElement
.prototype.isFloatableOutOfView = function () {
4506 return this.floatableOutOfView
;
4510 * Position the floatable below its container.
4512 * This should only be done when both of them are attached to the DOM and visible.
4516 OO
.ui
.mixin
.FloatableElement
.prototype.position = function () {
4517 if ( !this.positioning
) {
4522 // To continue, some things need to be true:
4523 // The element must actually be in the DOM
4524 this.isElementAttached() && (
4525 // The closest scrollable is the current window
4526 this.$floatableClosestScrollable
[ 0 ] === this.getElementWindow() ||
4527 // OR is an element in the element's DOM
4528 $.contains( this.getElementDocument(), this.$floatableClosestScrollable
[ 0 ] )
4531 // Abort early if important parts of the widget are no longer attached to the DOM
4535 this.floatableOutOfView
= this.hideWhenOutOfView
&& !this.isElementInViewport( this.$floatableContainer
, this.$floatableClosestScrollable
);
4536 if ( this.floatableOutOfView
) {
4537 this.$floatable
.addClass( 'oo-ui-element-hidden' );
4540 this.$floatable
.removeClass( 'oo-ui-element-hidden' );
4543 if ( !this.needsCustomPosition
) {
4547 this.$floatable
.css( this.computePosition() );
4549 // We updated the position, so re-evaluate the clipping state.
4550 // (ClippableElement does not listen to 'scroll' events on $floatableContainer's parent, and so
4551 // will not notice the need to update itself.)
4552 // TODO: This is terrible, we shouldn't need to know about ClippableElement at all here. Why does
4553 // it not listen to the right events in the right places?
4562 * Compute how #$floatable should be positioned based on the position of #$floatableContainer
4563 * and the positioning settings. This is a helper for #position that shouldn't be called directly,
4564 * but may be overridden by subclasses if they want to change or add to the positioning logic.
4566 * @return {Object} New position to apply with .css(). Keys are 'top', 'left', 'bottom' and 'right'.
4568 OO
.ui
.mixin
.FloatableElement
.prototype.computePosition = function () {
4569 var isBody
, scrollableX
, scrollableY
, containerPos
,
4570 horizScrollbarHeight
, vertScrollbarWidth
, scrollTop
, scrollLeft
,
4571 newPos
= { top
: '', left
: '', bottom
: '', right
: '' },
4572 direction
= this.$floatableContainer
.css( 'direction' ),
4573 $offsetParent
= this.$floatable
.offsetParent();
4575 if ( $offsetParent
.is( 'html' ) ) {
4576 // The innerHeight/Width and clientHeight/Width calculations don't work well on the
4577 // <html> element, but they do work on the <body>
4578 $offsetParent
= $( $offsetParent
[ 0 ].ownerDocument
.body
);
4580 isBody
= $offsetParent
.is( 'body' );
4581 scrollableX
= $offsetParent
.css( 'overflow-x' ) === 'scroll' || $offsetParent
.css( 'overflow-x' ) === 'auto';
4582 scrollableY
= $offsetParent
.css( 'overflow-y' ) === 'scroll' || $offsetParent
.css( 'overflow-y' ) === 'auto';
4584 vertScrollbarWidth
= $offsetParent
.innerWidth() - $offsetParent
.prop( 'clientWidth' );
4585 horizScrollbarHeight
= $offsetParent
.innerHeight() - $offsetParent
.prop( 'clientHeight' );
4586 // We don't need to compute and add scrollTop and scrollLeft if the scrollable container is the body,
4587 // or if it isn't scrollable
4588 scrollTop
= scrollableY
&& !isBody
? $offsetParent
.scrollTop() : 0;
4589 scrollLeft
= scrollableX
&& !isBody
? OO
.ui
.Element
.static.getScrollLeft( $offsetParent
[ 0 ] ) : 0;
4591 // Avoid passing the <body> to getRelativePosition(), because it won't return what we expect
4592 // if the <body> has a margin
4593 containerPos
= isBody
?
4594 this.$floatableContainer
.offset() :
4595 OO
.ui
.Element
.static.getRelativePosition( this.$floatableContainer
, $offsetParent
);
4596 containerPos
.bottom
= containerPos
.top
+ this.$floatableContainer
.outerHeight();
4597 containerPos
.right
= containerPos
.left
+ this.$floatableContainer
.outerWidth();
4598 containerPos
.start
= direction
=== 'rtl' ? containerPos
.right
: containerPos
.left
;
4599 containerPos
.end
= direction
=== 'rtl' ? containerPos
.left
: containerPos
.right
;
4601 if ( this.verticalPosition
=== 'below' ) {
4602 newPos
.top
= containerPos
.bottom
;
4603 } else if ( this.verticalPosition
=== 'above' ) {
4604 newPos
.bottom
= $offsetParent
.outerHeight() - containerPos
.top
;
4605 } else if ( this.verticalPosition
=== 'top' ) {
4606 newPos
.top
= containerPos
.top
;
4607 } else if ( this.verticalPosition
=== 'bottom' ) {
4608 newPos
.bottom
= $offsetParent
.outerHeight() - containerPos
.bottom
;
4609 } else if ( this.verticalPosition
=== 'center' ) {
4610 newPos
.top
= containerPos
.top
+
4611 ( this.$floatableContainer
.height() - this.$floatable
.height() ) / 2;
4614 if ( this.horizontalPosition
=== 'before' ) {
4615 newPos
.end
= containerPos
.start
;
4616 } else if ( this.horizontalPosition
=== 'after' ) {
4617 newPos
.start
= containerPos
.end
;
4618 } else if ( this.horizontalPosition
=== 'start' ) {
4619 newPos
.start
= containerPos
.start
;
4620 } else if ( this.horizontalPosition
=== 'end' ) {
4621 newPos
.end
= containerPos
.end
;
4622 } else if ( this.horizontalPosition
=== 'center' ) {
4623 newPos
.left
= containerPos
.left
+
4624 ( this.$floatableContainer
.width() - this.$floatable
.width() ) / 2;
4627 if ( newPos
.start
!== undefined ) {
4628 if ( direction
=== 'rtl' ) {
4629 newPos
.right
= ( isBody
? $( $offsetParent
[ 0 ].ownerDocument
.documentElement
) : $offsetParent
).outerWidth() - newPos
.start
;
4631 newPos
.left
= newPos
.start
;
4633 delete newPos
.start
;
4635 if ( newPos
.end
!== undefined ) {
4636 if ( direction
=== 'rtl' ) {
4637 newPos
.left
= newPos
.end
;
4639 newPos
.right
= ( isBody
? $( $offsetParent
[ 0 ].ownerDocument
.documentElement
) : $offsetParent
).outerWidth() - newPos
.end
;
4644 // Account for scroll position
4645 if ( newPos
.top
!== '' ) {
4646 newPos
.top
+= scrollTop
;
4648 if ( newPos
.bottom
!== '' ) {
4649 newPos
.bottom
-= scrollTop
;
4651 if ( newPos
.left
!== '' ) {
4652 newPos
.left
+= scrollLeft
;
4654 if ( newPos
.right
!== '' ) {
4655 newPos
.right
-= scrollLeft
;
4658 // Account for scrollbar gutter
4659 if ( newPos
.bottom
!== '' ) {
4660 newPos
.bottom
-= horizScrollbarHeight
;
4662 if ( direction
=== 'rtl' ) {
4663 if ( newPos
.left
!== '' ) {
4664 newPos
.left
-= vertScrollbarWidth
;
4667 if ( newPos
.right
!== '' ) {
4668 newPos
.right
-= vertScrollbarWidth
;
4676 * Element that can be automatically clipped to visible boundaries.
4678 * Whenever the element's natural height changes, you have to call
4679 * {@link OO.ui.mixin.ClippableElement#clip} to make sure it's still
4680 * clipping correctly.
4682 * The dimensions of #$clippableContainer will be compared to the boundaries of the
4683 * nearest scrollable container. If #$clippableContainer is too tall and/or too wide,
4684 * then #$clippable will be given a fixed reduced height and/or width and will be made
4685 * scrollable. By default, #$clippable and #$clippableContainer are the same element,
4686 * but you can build a static footer by setting #$clippableContainer to an element that contains
4687 * #$clippable and the footer.
4693 * @param {Object} [config] Configuration options
4694 * @cfg {jQuery} [$clippable] Node to clip, assigned to #$clippable, omit to use #$element
4695 * @cfg {jQuery} [$clippableContainer] Node to keep visible, assigned to #$clippableContainer,
4696 * omit to use #$clippable
4698 OO
.ui
.mixin
.ClippableElement
= function OoUiMixinClippableElement( config
) {
4699 // Configuration initialization
4700 config
= config
|| {};
4703 this.$clippable
= null;
4704 this.$clippableContainer
= null;
4705 this.clipping
= false;
4706 this.clippedHorizontally
= false;
4707 this.clippedVertically
= false;
4708 this.$clippableScrollableContainer
= null;
4709 this.$clippableScroller
= null;
4710 this.$clippableWindow
= null;
4711 this.idealWidth
= null;
4712 this.idealHeight
= null;
4713 this.onClippableScrollHandler
= this.clip
.bind( this );
4714 this.onClippableWindowResizeHandler
= this.clip
.bind( this );
4717 if ( config
.$clippableContainer
) {
4718 this.setClippableContainer( config
.$clippableContainer
);
4720 this.setClippableElement( config
.$clippable
|| this.$element
);
4726 * Set clippable element.
4728 * If an element is already set, it will be cleaned up before setting up the new element.
4730 * @param {jQuery} $clippable Element to make clippable
4732 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableElement = function ( $clippable
) {
4733 if ( this.$clippable
) {
4734 this.$clippable
.removeClass( 'oo-ui-clippableElement-clippable' );
4735 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
4736 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4739 this.$clippable
= $clippable
.addClass( 'oo-ui-clippableElement-clippable' );
4744 * Set clippable container.
4746 * This is the container that will be measured when deciding whether to clip. When clipping,
4747 * #$clippable will be resized in order to keep the clippable container fully visible.
4749 * If the clippable container is unset, #$clippable will be used.
4751 * @param {jQuery|null} $clippableContainer Container to keep visible, or null to unset
4753 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableContainer = function ( $clippableContainer
) {
4754 this.$clippableContainer
= $clippableContainer
;
4755 if ( this.$clippable
) {
4763 * Do not turn clipping on until after the element is attached to the DOM and visible.
4765 * @param {boolean} [clipping] Enable clipping, omit to toggle
4768 OO
.ui
.mixin
.ClippableElement
.prototype.toggleClipping = function ( clipping
) {
4769 clipping
= clipping
=== undefined ? !this.clipping
: !!clipping
;
4771 if ( clipping
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
4772 OO
.ui
.warnDeprecation( 'ClippableElement#toggleClipping: Before calling this method, the element must be attached to the DOM.' );
4773 this.warnedUnattached
= true;
4776 if ( this.clipping
!== clipping
) {
4777 this.clipping
= clipping
;
4779 this.$clippableScrollableContainer
= $( this.getClosestScrollableElementContainer() );
4780 // If the clippable container is the root, we have to listen to scroll events and check
4781 // jQuery.scrollTop on the window because of browser inconsistencies
4782 this.$clippableScroller
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4783 $( OO
.ui
.Element
.static.getWindow( this.$clippableScrollableContainer
) ) :
4784 this.$clippableScrollableContainer
;
4785 this.$clippableScroller
.on( 'scroll', this.onClippableScrollHandler
);
4786 this.$clippableWindow
= $( this.getElementWindow() )
4787 .on( 'resize', this.onClippableWindowResizeHandler
);
4788 // Initial clip after visible
4791 this.$clippable
.css( {
4799 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4801 this.$clippableScrollableContainer
= null;
4802 this.$clippableScroller
.off( 'scroll', this.onClippableScrollHandler
);
4803 this.$clippableScroller
= null;
4804 this.$clippableWindow
.off( 'resize', this.onClippableWindowResizeHandler
);
4805 this.$clippableWindow
= null;
4813 * Check if the element will be clipped to fit the visible area of the nearest scrollable container.
4815 * @return {boolean} Element will be clipped to the visible area
4817 OO
.ui
.mixin
.ClippableElement
.prototype.isClipping = function () {
4818 return this.clipping
;
4822 * Check if the bottom or right of the element is being clipped by the nearest scrollable container.
4824 * @return {boolean} Part of the element is being clipped
4826 OO
.ui
.mixin
.ClippableElement
.prototype.isClipped = function () {
4827 return this.clippedHorizontally
|| this.clippedVertically
;
4831 * Check if the right of the element is being clipped by the nearest scrollable container.
4833 * @return {boolean} Part of the element is being clipped
4835 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedHorizontally = function () {
4836 return this.clippedHorizontally
;
4840 * Check if the bottom of the element is being clipped by the nearest scrollable container.
4842 * @return {boolean} Part of the element is being clipped
4844 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedVertically = function () {
4845 return this.clippedVertically
;
4849 * Set the ideal size. These are the dimensions #$clippable will have when it's not being clipped.
4851 * @param {number|string} [width] Width as a number of pixels or CSS string with unit suffix
4852 * @param {number|string} [height] Height as a number of pixels or CSS string with unit suffix
4854 OO
.ui
.mixin
.ClippableElement
.prototype.setIdealSize = function ( width
, height
) {
4855 this.idealWidth
= width
;
4856 this.idealHeight
= height
;
4858 if ( !this.clipping
) {
4859 // Update dimensions
4860 this.$clippable
.css( { width
: width
, height
: height
} );
4862 // While clipping, idealWidth and idealHeight are not considered
4866 * Return the side of the clippable on which it is "anchored" (aligned to something else).
4867 * ClippableElement will clip the opposite side when reducing element's width.
4869 * Classes that mix in ClippableElement should override this to return 'right' if their
4870 * clippable is absolutely positioned and using 'right: Npx' (and not using 'left').
4871 * If your class also mixes in FloatableElement, this is handled automatically.
4873 * (This can't be guessed from the actual CSS because the computed values for 'left'/'right' are
4874 * always in pixels, even if they were unset or set to 'auto'.)
4876 * When in doubt, 'left' (or 'right' in RTL) is a sane fallback.
4878 * @return {string} 'left' or 'right'
4880 OO
.ui
.mixin
.ClippableElement
.prototype.getHorizontalAnchorEdge = function () {
4881 if ( this.computePosition
&& this.positioning
&& this.computePosition().right
!== '' ) {
4888 * Return the side of the clippable on which it is "anchored" (aligned to something else).
4889 * ClippableElement will clip the opposite side when reducing element's width.
4891 * Classes that mix in ClippableElement should override this to return 'bottom' if their
4892 * clippable is absolutely positioned and using 'bottom: Npx' (and not using 'top').
4893 * If your class also mixes in FloatableElement, this is handled automatically.
4895 * (This can't be guessed from the actual CSS because the computed values for 'left'/'right' are
4896 * always in pixels, even if they were unset or set to 'auto'.)
4898 * When in doubt, 'top' is a sane fallback.
4900 * @return {string} 'top' or 'bottom'
4902 OO
.ui
.mixin
.ClippableElement
.prototype.getVerticalAnchorEdge = function () {
4903 if ( this.computePosition
&& this.positioning
&& this.computePosition().bottom
!== '' ) {
4910 * Clip element to visible boundaries and allow scrolling when needed. You should call this method
4911 * when the element's natural height changes.
4913 * Element will be clipped the bottom or right of the element is within 10px of the edge of, or
4914 * overlapped by, the visible area of the nearest scrollable container.
4916 * Because calling clip() when the natural height changes isn't always possible, we also set
4917 * max-height when the element isn't being clipped. This means that if the element tries to grow
4918 * beyond the edge, something reasonable will happen before clip() is called.
4922 OO
.ui
.mixin
.ClippableElement
.prototype.clip = function () {
4923 var extraHeight
, extraWidth
, viewportSpacing
,
4924 desiredWidth
, desiredHeight
, allotedWidth
, allotedHeight
,
4925 naturalWidth
, naturalHeight
, clipWidth
, clipHeight
,
4926 $item
, itemRect
, $viewport
, viewportRect
, availableRect
,
4927 direction
, vertScrollbarWidth
, horizScrollbarHeight
,
4928 // Extra tolerance so that the sloppy code below doesn't result in results that are off
4929 // by one or two pixels. (And also so that we have space to display drop shadows.)
4930 // Chosen by fair dice roll.
4933 if ( !this.clipping
) {
4934 // this.$clippableScrollableContainer and this.$clippableWindow are null, so the below will fail
4938 function rectIntersection( a
, b
) {
4940 out
.top
= Math
.max( a
.top
, b
.top
);
4941 out
.left
= Math
.max( a
.left
, b
.left
);
4942 out
.bottom
= Math
.min( a
.bottom
, b
.bottom
);
4943 out
.right
= Math
.min( a
.right
, b
.right
);
4947 viewportSpacing
= OO
.ui
.getViewportSpacing();
4949 if ( this.$clippableScrollableContainer
.is( 'html, body' ) ) {
4950 $viewport
= $( this.$clippableScrollableContainer
[ 0 ].ownerDocument
.body
);
4951 // Dimensions of the browser window, rather than the element!
4955 right
: document
.documentElement
.clientWidth
,
4956 bottom
: document
.documentElement
.clientHeight
4958 viewportRect
.top
+= viewportSpacing
.top
;
4959 viewportRect
.left
+= viewportSpacing
.left
;
4960 viewportRect
.right
-= viewportSpacing
.right
;
4961 viewportRect
.bottom
-= viewportSpacing
.bottom
;
4963 $viewport
= this.$clippableScrollableContainer
;
4964 viewportRect
= $viewport
[ 0 ].getBoundingClientRect();
4965 // Convert into a plain object
4966 viewportRect
= $.extend( {}, viewportRect
);
4969 // Account for scrollbar gutter
4970 direction
= $viewport
.css( 'direction' );
4971 vertScrollbarWidth
= $viewport
.innerWidth() - $viewport
.prop( 'clientWidth' );
4972 horizScrollbarHeight
= $viewport
.innerHeight() - $viewport
.prop( 'clientHeight' );
4973 viewportRect
.bottom
-= horizScrollbarHeight
;
4974 if ( direction
=== 'rtl' ) {
4975 viewportRect
.left
+= vertScrollbarWidth
;
4977 viewportRect
.right
-= vertScrollbarWidth
;
4980 // Add arbitrary tolerance
4981 viewportRect
.top
+= buffer
;
4982 viewportRect
.left
+= buffer
;
4983 viewportRect
.right
-= buffer
;
4984 viewportRect
.bottom
-= buffer
;
4986 $item
= this.$clippableContainer
|| this.$clippable
;
4988 extraHeight
= $item
.outerHeight() - this.$clippable
.outerHeight();
4989 extraWidth
= $item
.outerWidth() - this.$clippable
.outerWidth();
4991 itemRect
= $item
[ 0 ].getBoundingClientRect();
4992 // Convert into a plain object
4993 itemRect
= $.extend( {}, itemRect
);
4995 // Item might already be clipped, so we can't just use its dimensions (in case we might need to
4996 // make it larger than before). Extend the rectangle to the maximum size we are allowed to take.
4997 if ( this.getHorizontalAnchorEdge() === 'right' ) {
4998 itemRect
.left
= viewportRect
.left
;
5000 itemRect
.right
= viewportRect
.right
;
5002 if ( this.getVerticalAnchorEdge() === 'bottom' ) {
5003 itemRect
.top
= viewportRect
.top
;
5005 itemRect
.bottom
= viewportRect
.bottom
;
5008 availableRect
= rectIntersection( viewportRect
, itemRect
);
5010 desiredWidth
= Math
.max( 0, availableRect
.right
- availableRect
.left
);
5011 desiredHeight
= Math
.max( 0, availableRect
.bottom
- availableRect
.top
);
5012 // It should never be desirable to exceed the dimensions of the browser viewport... right?
5013 desiredWidth
= Math
.min( desiredWidth
,
5014 document
.documentElement
.clientWidth
- viewportSpacing
.left
- viewportSpacing
.right
);
5015 desiredHeight
= Math
.min( desiredHeight
,
5016 document
.documentElement
.clientHeight
- viewportSpacing
.top
- viewportSpacing
.right
);
5017 allotedWidth
= Math
.ceil( desiredWidth
- extraWidth
);
5018 allotedHeight
= Math
.ceil( desiredHeight
- extraHeight
);
5019 naturalWidth
= this.$clippable
.prop( 'scrollWidth' );
5020 naturalHeight
= this.$clippable
.prop( 'scrollHeight' );
5021 clipWidth
= allotedWidth
< naturalWidth
;
5022 clipHeight
= allotedHeight
< naturalHeight
;
5025 // The order matters here. If overflow is not set first, Chrome displays bogus scrollbars. See T157672.
5026 // Forcing a reflow is a smaller workaround than calling reconsiderScrollbars() for this case.
5027 this.$clippable
.css( 'overflowX', 'scroll' );
5028 void this.$clippable
[ 0 ].offsetHeight
; // Force reflow
5029 this.$clippable
.css( {
5030 width
: Math
.max( 0, allotedWidth
),
5034 this.$clippable
.css( {
5036 width
: this.idealWidth
|| '',
5037 maxWidth
: Math
.max( 0, allotedWidth
)
5041 // The order matters here. If overflow is not set first, Chrome displays bogus scrollbars. See T157672.
5042 // Forcing a reflow is a smaller workaround than calling reconsiderScrollbars() for this case.
5043 this.$clippable
.css( 'overflowY', 'scroll' );
5044 void this.$clippable
[ 0 ].offsetHeight
; // Force reflow
5045 this.$clippable
.css( {
5046 height
: Math
.max( 0, allotedHeight
),
5050 this.$clippable
.css( {
5052 height
: this.idealHeight
|| '',
5053 maxHeight
: Math
.max( 0, allotedHeight
)
5057 // If we stopped clipping in at least one of the dimensions
5058 if ( ( this.clippedHorizontally
&& !clipWidth
) || ( this.clippedVertically
&& !clipHeight
) ) {
5059 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
5062 this.clippedHorizontally
= clipWidth
;
5063 this.clippedVertically
= clipHeight
;
5069 * PopupWidget is a container for content. The popup is overlaid and positioned absolutely.
5070 * By default, each popup has an anchor that points toward its origin.
5071 * Please see the [OOUI documentation on MediaWiki.org] [1] for more information and examples.
5073 * Unlike most widgets, PopupWidget is initially hidden and must be shown by calling #toggle.
5076 * // A popup widget.
5077 * var popup = new OO.ui.PopupWidget( {
5078 * $content: $( '<p>Hi there!</p>' ),
5083 * $( 'body' ).append( popup.$element );
5084 * // To display the popup, toggle the visibility to 'true'.
5085 * popup.toggle( true );
5087 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Popups
5090 * @extends OO.ui.Widget
5091 * @mixins OO.ui.mixin.LabelElement
5092 * @mixins OO.ui.mixin.ClippableElement
5093 * @mixins OO.ui.mixin.FloatableElement
5096 * @param {Object} [config] Configuration options
5097 * @cfg {number|null} [width=320] Width of popup in pixels. Pass `null` to use automatic width.
5098 * @cfg {number|null} [height=null] Height of popup in pixels. Pass `null` to use automatic height.
5099 * @cfg {boolean} [anchor=true] Show anchor pointing to origin of popup
5100 * @cfg {string} [position='below'] Where to position the popup relative to $floatableContainer
5101 * 'above': Put popup above $floatableContainer; anchor points down to the horizontal center
5102 * of $floatableContainer
5103 * 'below': Put popup below $floatableContainer; anchor points up to the horizontal center
5104 * of $floatableContainer
5105 * 'before': Put popup to the left (LTR) / right (RTL) of $floatableContainer; anchor points
5106 * endwards (right/left) to the vertical center of $floatableContainer
5107 * 'after': Put popup to the right (LTR) / left (RTL) of $floatableContainer; anchor points
5108 * startwards (left/right) to the vertical center of $floatableContainer
5109 * @cfg {string} [align='center'] How to align the popup to $floatableContainer
5110 * 'forwards': If position is above/below, move the popup as far endwards (right in LTR, left in RTL)
5111 * as possible while still keeping the anchor within the popup;
5112 * if position is before/after, move the popup as far downwards as possible.
5113 * 'backwards': If position is above/below, move the popup as far startwards (left in LTR, right in RTL)
5114 * as possible while still keeping the anchor within the popup;
5115 * if position in before/after, move the popup as far upwards as possible.
5116 * 'center': Horizontally (if position is above/below) or vertically (before/after) align the center
5117 * of the popup with the center of $floatableContainer.
5118 * 'force-left': Alias for 'forwards' in LTR and 'backwards' in RTL
5119 * 'force-right': Alias for 'backwards' in RTL and 'forwards' in LTR
5120 * @cfg {boolean} [autoFlip=true] Whether to automatically switch the popup's position between
5121 * 'above' and 'below', or between 'before' and 'after', if there is not enough space in the
5122 * desired direction to display the popup without clipping
5123 * @cfg {jQuery} [$container] Constrain the popup to the boundaries of the specified container.
5124 * See the [OOUI docs on MediaWiki][3] for an example.
5125 * [3]: https://www.mediawiki.org/wiki/OOUI/Widgets/Popups#containerExample
5126 * @cfg {number} [containerPadding=10] Padding between the popup and its container, specified as a number of pixels.
5127 * @cfg {jQuery} [$content] Content to append to the popup's body
5128 * @cfg {jQuery} [$footer] Content to append to the popup's footer
5129 * @cfg {boolean} [autoClose=false] Automatically close the popup when it loses focus.
5130 * @cfg {jQuery} [$autoCloseIgnore] Elements that will not close the popup when clicked.
5131 * This config option is only relevant if #autoClose is set to `true`. See the [OOUI documentation on MediaWiki][2]
5133 * [2]: https://www.mediawiki.org/wiki/OOUI/Widgets/Popups#autocloseExample
5134 * @cfg {boolean} [head=false] Show a popup header that contains a #label (if specified) and close
5136 * @cfg {boolean} [padded=false] Add padding to the popup's body
5138 OO
.ui
.PopupWidget
= function OoUiPopupWidget( config
) {
5139 // Configuration initialization
5140 config
= config
|| {};
5142 // Parent constructor
5143 OO
.ui
.PopupWidget
.parent
.call( this, config
);
5145 // Properties (must be set before ClippableElement constructor call)
5146 this.$body
= $( '<div>' );
5147 this.$popup
= $( '<div>' );
5149 // Mixin constructors
5150 OO
.ui
.mixin
.LabelElement
.call( this, config
);
5151 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, {
5152 $clippable
: this.$body
,
5153 $clippableContainer
: this.$popup
5155 OO
.ui
.mixin
.FloatableElement
.call( this, config
);
5158 this.$anchor
= $( '<div>' );
5159 // If undefined, will be computed lazily in computePosition()
5160 this.$container
= config
.$container
;
5161 this.containerPadding
= config
.containerPadding
!== undefined ? config
.containerPadding
: 10;
5162 this.autoClose
= !!config
.autoClose
;
5163 this.transitionTimeout
= null;
5164 this.anchored
= false;
5165 this.onDocumentMouseDownHandler
= this.onDocumentMouseDown
.bind( this );
5166 this.onDocumentKeyDownHandler
= this.onDocumentKeyDown
.bind( this );
5169 this.setSize( config
.width
, config
.height
);
5170 this.toggleAnchor( config
.anchor
=== undefined || config
.anchor
);
5171 this.setAlignment( config
.align
|| 'center' );
5172 this.setPosition( config
.position
|| 'below' );
5173 this.setAutoFlip( config
.autoFlip
=== undefined || config
.autoFlip
);
5174 this.setAutoCloseIgnore( config
.$autoCloseIgnore
);
5175 this.$body
.addClass( 'oo-ui-popupWidget-body' );
5176 this.$anchor
.addClass( 'oo-ui-popupWidget-anchor' );
5178 .addClass( 'oo-ui-popupWidget-popup' )
5179 .append( this.$body
);
5181 .addClass( 'oo-ui-popupWidget' )
5182 .append( this.$popup
, this.$anchor
);
5183 // Move content, which was added to #$element by OO.ui.Widget, to the body
5184 // FIXME This is gross, we should use '$body' or something for the config
5185 if ( config
.$content
instanceof jQuery
) {
5186 this.$body
.append( config
.$content
);
5189 if ( config
.padded
) {
5190 this.$body
.addClass( 'oo-ui-popupWidget-body-padded' );
5193 if ( config
.head
) {
5194 this.closeButton
= new OO
.ui
.ButtonWidget( { framed
: false, icon
: 'close' } );
5195 this.closeButton
.connect( this, { click
: 'onCloseButtonClick' } );
5196 this.$head
= $( '<div>' )
5197 .addClass( 'oo-ui-popupWidget-head' )
5198 .append( this.$label
, this.closeButton
.$element
);
5199 this.$popup
.prepend( this.$head
);
5202 if ( config
.$footer
) {
5203 this.$footer
= $( '<div>' )
5204 .addClass( 'oo-ui-popupWidget-footer' )
5205 .append( config
.$footer
);
5206 this.$popup
.append( this.$footer
);
5209 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
5210 // that reference properties not initialized at that time of parent class construction
5211 // TODO: Find a better way to handle post-constructor setup
5212 this.visible
= false;
5213 this.$element
.addClass( 'oo-ui-element-hidden' );
5218 OO
.inheritClass( OO
.ui
.PopupWidget
, OO
.ui
.Widget
);
5219 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.LabelElement
);
5220 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.ClippableElement
);
5221 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.FloatableElement
);
5228 * The popup is ready: it is visible and has been positioned and clipped.
5234 * Handles document mouse down events.
5237 * @param {MouseEvent} e Mouse down event
5239 OO
.ui
.PopupWidget
.prototype.onDocumentMouseDown = function ( e
) {
5242 !OO
.ui
.contains( this.$element
.add( this.$autoCloseIgnore
).get(), e
.target
, true )
5244 this.toggle( false );
5248 // Deprecated alias since 0.28.3
5249 OO
.ui
.PopupWidget
.prototype.onMouseDown = function () {
5250 OO
.ui
.warnDeprecation( 'onMouseDown is deprecated, use onDocumentMouseDown instead' );
5251 this.onDocumentMouseDown
.apply( this, arguments
);
5255 * Bind document mouse down listener.
5259 OO
.ui
.PopupWidget
.prototype.bindDocumentMouseDownListener = function () {
5260 // Capture clicks outside popup
5261 this.getElementDocument().addEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
5262 // We add 'click' event because iOS safari needs to respond to this event.
5263 // We can't use 'touchstart' (as is usually the equivalent to 'mousedown') because
5264 // then it will trigger when scrolling. While iOS Safari has some reported behavior
5265 // of occasionally not emitting 'click' properly, that event seems to be the standard
5266 // that it should be emitting, so we add it to this and will operate the event handler
5267 // on whichever of these events was triggered first
5268 this.getElementDocument().addEventListener( 'click', this.onDocumentMouseDownHandler
, true );
5271 // Deprecated alias since 0.28.3
5272 OO
.ui
.PopupWidget
.prototype.bindMouseDownListener = function () {
5273 OO
.ui
.warnDeprecation( 'bindMouseDownListener is deprecated, use bindDocumentMouseDownListener instead' );
5274 this.bindDocumentMouseDownListener
.apply( this, arguments
);
5278 * Handles close button click events.
5282 OO
.ui
.PopupWidget
.prototype.onCloseButtonClick = function () {
5283 if ( this.isVisible() ) {
5284 this.toggle( false );
5289 * Unbind document mouse down listener.
5293 OO
.ui
.PopupWidget
.prototype.unbindDocumentMouseDownListener = function () {
5294 this.getElementDocument().removeEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
5295 this.getElementDocument().removeEventListener( 'click', this.onDocumentMouseDownHandler
, true );
5298 // Deprecated alias since 0.28.3
5299 OO
.ui
.PopupWidget
.prototype.unbindMouseDownListener = function () {
5300 OO
.ui
.warnDeprecation( 'unbindMouseDownListener is deprecated, use unbindDocumentMouseDownListener instead' );
5301 this.unbindDocumentMouseDownListener
.apply( this, arguments
);
5305 * Handles document key down events.
5308 * @param {KeyboardEvent} e Key down event
5310 OO
.ui
.PopupWidget
.prototype.onDocumentKeyDown = function ( e
) {
5312 e
.which
=== OO
.ui
.Keys
.ESCAPE
&&
5315 this.toggle( false );
5317 e
.stopPropagation();
5322 * Bind document key down listener.
5326 OO
.ui
.PopupWidget
.prototype.bindDocumentKeyDownListener = function () {
5327 this.getElementDocument().addEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
5330 // Deprecated alias since 0.28.3
5331 OO
.ui
.PopupWidget
.prototype.bindKeyDownListener = function () {
5332 OO
.ui
.warnDeprecation( 'bindKeyDownListener is deprecated, use bindDocumentKeyDownListener instead' );
5333 this.bindDocumentKeyDownListener
.apply( this, arguments
);
5337 * Unbind document key down listener.
5341 OO
.ui
.PopupWidget
.prototype.unbindDocumentKeyDownListener = function () {
5342 this.getElementDocument().removeEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
5345 // Deprecated alias since 0.28.3
5346 OO
.ui
.PopupWidget
.prototype.unbindKeyDownListener = function () {
5347 OO
.ui
.warnDeprecation( 'unbindKeyDownListener is deprecated, use unbindDocumentKeyDownListener instead' );
5348 this.unbindDocumentKeyDownListener
.apply( this, arguments
);
5352 * Show, hide, or toggle the visibility of the anchor.
5354 * @param {boolean} [show] Show anchor, omit to toggle
5356 OO
.ui
.PopupWidget
.prototype.toggleAnchor = function ( show
) {
5357 show
= show
=== undefined ? !this.anchored
: !!show
;
5359 if ( this.anchored
!== show
) {
5361 this.$element
.addClass( 'oo-ui-popupWidget-anchored' );
5362 this.$element
.addClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
5364 this.$element
.removeClass( 'oo-ui-popupWidget-anchored' );
5365 this.$element
.removeClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
5367 this.anchored
= show
;
5372 * Change which edge the anchor appears on.
5374 * @param {string} edge 'top', 'bottom', 'start' or 'end'
5376 OO
.ui
.PopupWidget
.prototype.setAnchorEdge = function ( edge
) {
5377 if ( [ 'top', 'bottom', 'start', 'end' ].indexOf( edge
) === -1 ) {
5378 throw new Error( 'Invalid value for edge: ' + edge
);
5380 if ( this.anchorEdge
!== null ) {
5381 this.$element
.removeClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
5383 this.anchorEdge
= edge
;
5384 if ( this.anchored
) {
5385 this.$element
.addClass( 'oo-ui-popupWidget-anchored-' + edge
);
5390 * Check if the anchor is visible.
5392 * @return {boolean} Anchor is visible
5394 OO
.ui
.PopupWidget
.prototype.hasAnchor = function () {
5395 return this.anchored
;
5399 * Toggle visibility of the popup. The popup is initially hidden and must be shown by calling
5400 * `.toggle( true )` after its #$element is attached to the DOM.
5402 * Do not show the popup while it is not attached to the DOM. The calculations required to display
5403 * it in the right place and with the right dimensions only work correctly while it is attached.
5404 * Side-effects may include broken interface and exceptions being thrown. This wasn't always
5405 * strictly enforced, so currently it only generates a warning in the browser console.
5410 OO
.ui
.PopupWidget
.prototype.toggle = function ( show
) {
5411 var change
, normalHeight
, oppositeHeight
, normalWidth
, oppositeWidth
;
5412 show
= show
=== undefined ? !this.isVisible() : !!show
;
5414 change
= show
!== this.isVisible();
5416 if ( show
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
5417 OO
.ui
.warnDeprecation( 'PopupWidget#toggle: Before calling this method, the popup must be attached to the DOM.' );
5418 this.warnedUnattached
= true;
5420 if ( show
&& !this.$floatableContainer
&& this.isElementAttached() ) {
5421 // Fall back to the parent node if the floatableContainer is not set
5422 this.setFloatableContainer( this.$element
.parent() );
5425 if ( change
&& show
&& this.autoFlip
) {
5426 // Reset auto-flipping before showing the popup again. It's possible we no longer need to flip
5427 // (e.g. if the user scrolled).
5428 this.isAutoFlipped
= false;
5432 OO
.ui
.PopupWidget
.parent
.prototype.toggle
.call( this, show
);
5435 this.togglePositioning( show
&& !!this.$floatableContainer
);
5438 if ( this.autoClose
) {
5439 this.bindDocumentMouseDownListener();
5440 this.bindDocumentKeyDownListener();
5442 this.updateDimensions();
5443 this.toggleClipping( true );
5445 if ( this.autoFlip
) {
5446 if ( this.popupPosition
=== 'above' || this.popupPosition
=== 'below' ) {
5447 if ( this.isClippedVertically() || this.isFloatableOutOfView() ) {
5448 // If opening the popup in the normal direction causes it to be clipped, open
5449 // in the opposite one instead
5450 normalHeight
= this.$element
.height();
5451 this.isAutoFlipped
= !this.isAutoFlipped
;
5453 if ( this.isClippedVertically() || this.isFloatableOutOfView() ) {
5454 // If that also causes it to be clipped, open in whichever direction
5455 // we have more space
5456 oppositeHeight
= this.$element
.height();
5457 if ( oppositeHeight
< normalHeight
) {
5458 this.isAutoFlipped
= !this.isAutoFlipped
;
5464 if ( this.popupPosition
=== 'before' || this.popupPosition
=== 'after' ) {
5465 if ( this.isClippedHorizontally() || this.isFloatableOutOfView() ) {
5466 // If opening the popup in the normal direction causes it to be clipped, open
5467 // in the opposite one instead
5468 normalWidth
= this.$element
.width();
5469 this.isAutoFlipped
= !this.isAutoFlipped
;
5470 // Due to T180173 horizontally clipped PopupWidgets have messed up dimensions,
5471 // which causes positioning to be off. Toggle clipping back and fort to work around.
5472 this.toggleClipping( false );
5474 this.toggleClipping( true );
5475 if ( this.isClippedHorizontally() || this.isFloatableOutOfView() ) {
5476 // If that also causes it to be clipped, open in whichever direction
5477 // we have more space
5478 oppositeWidth
= this.$element
.width();
5479 if ( oppositeWidth
< normalWidth
) {
5480 this.isAutoFlipped
= !this.isAutoFlipped
;
5481 // Due to T180173 horizontally clipped PopupWidgets have messed up dimensions,
5482 // which causes positioning to be off. Toggle clipping back and fort to work around.
5483 this.toggleClipping( false );
5485 this.toggleClipping( true );
5492 this.emit( 'ready' );
5494 this.toggleClipping( false );
5495 if ( this.autoClose
) {
5496 this.unbindDocumentMouseDownListener();
5497 this.unbindDocumentKeyDownListener();
5506 * Set the size of the popup.
5508 * Changing the size may also change the popup's position depending on the alignment.
5510 * @param {number|null} [width=320] Width in pixels. Pass `null` to use automatic width.
5511 * @param {number|null} [height=null] Height in pixels. Pass `null` to use automatic height.
5512 * @param {boolean} [transition=false] Use a smooth transition
5515 OO
.ui
.PopupWidget
.prototype.setSize = function ( width
, height
, transition
) {
5516 this.width
= width
!== undefined ? width
: 320;
5517 this.height
= height
!== undefined ? height
: null;
5518 if ( this.isVisible() ) {
5519 this.updateDimensions( transition
);
5524 * Update the size and position.
5526 * Only use this to keep the popup properly anchored. Use #setSize to change the size, and this will
5527 * be called automatically.
5529 * @param {boolean} [transition=false] Use a smooth transition
5532 OO
.ui
.PopupWidget
.prototype.updateDimensions = function ( transition
) {
5535 // Prevent transition from being interrupted
5536 clearTimeout( this.transitionTimeout
);
5538 // Enable transition
5539 this.$element
.addClass( 'oo-ui-popupWidget-transitioning' );
5545 // Prevent transitioning after transition is complete
5546 this.transitionTimeout
= setTimeout( function () {
5547 widget
.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
5550 // Prevent transitioning immediately
5551 this.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
5558 OO
.ui
.PopupWidget
.prototype.computePosition = function () {
5559 var direction
, align
, vertical
, start
, end
, near
, far
, sizeProp
, popupSize
, anchorSize
, anchorPos
,
5560 anchorOffset
, anchorMargin
, parentPosition
, positionProp
, positionAdjustment
, floatablePos
,
5561 offsetParentPos
, containerPos
, popupPosition
, viewportSpacing
,
5563 anchorCss
= { left
: '', right
: '', top
: '', bottom
: '' },
5564 popupPositionOppositeMap
= {
5572 'force-left': 'backwards',
5573 'force-right': 'forwards'
5576 'force-left': 'forwards',
5577 'force-right': 'backwards'
5589 backwards
: this.anchored
? 'before' : 'end'
5597 if ( !this.$container
) {
5598 // Lazy-initialize $container if not specified in constructor
5599 this.$container
= $( this.getClosestScrollableElementContainer() );
5601 direction
= this.$container
.css( 'direction' );
5603 // Set height and width before we do anything else, since it might cause our measurements
5604 // to change (e.g. due to scrollbars appearing or disappearing), and it also affects centering
5606 width
: this.width
!== null ? this.width
: 'auto',
5607 height
: this.height
!== null ? this.height
: 'auto'
5610 align
= alignMap
[ direction
][ this.align
] || this.align
;
5611 popupPosition
= this.popupPosition
;
5612 if ( this.isAutoFlipped
) {
5613 popupPosition
= popupPositionOppositeMap
[ popupPosition
];
5616 // If the popup is positioned before or after, then the anchor positioning is vertical, otherwise horizontal
5617 vertical
= popupPosition
=== 'before' || popupPosition
=== 'after';
5618 start
= vertical
? 'top' : ( direction
=== 'rtl' ? 'right' : 'left' );
5619 end
= vertical
? 'bottom' : ( direction
=== 'rtl' ? 'left' : 'right' );
5620 near
= vertical
? 'top' : 'left';
5621 far
= vertical
? 'bottom' : 'right';
5622 sizeProp
= vertical
? 'Height' : 'Width';
5623 popupSize
= vertical
? ( this.height
|| this.$popup
.height() ) : ( this.width
|| this.$popup
.width() );
5625 this.setAnchorEdge( anchorEdgeMap
[ popupPosition
] );
5626 this.horizontalPosition
= vertical
? popupPosition
: hPosMap
[ align
];
5627 this.verticalPosition
= vertical
? vPosMap
[ align
] : popupPosition
;
5630 parentPosition
= OO
.ui
.mixin
.FloatableElement
.prototype.computePosition
.call( this );
5631 // Find out which property FloatableElement used for positioning, and adjust that value
5632 positionProp
= vertical
?
5633 ( parentPosition
.top
!== '' ? 'top' : 'bottom' ) :
5634 ( parentPosition
.left
!== '' ? 'left' : 'right' );
5636 // Figure out where the near and far edges of the popup and $floatableContainer are
5637 floatablePos
= this.$floatableContainer
.offset();
5638 floatablePos
[ far
] = floatablePos
[ near
] + this.$floatableContainer
[ 'outer' + sizeProp
]();
5639 // Measure where the offsetParent is and compute our position based on that and parentPosition
5640 offsetParentPos
= this.$element
.offsetParent()[ 0 ] === document
.documentElement
?
5641 { top
: 0, left
: 0 } :
5642 this.$element
.offsetParent().offset();
5644 if ( positionProp
=== near
) {
5645 popupPos
[ near
] = offsetParentPos
[ near
] + parentPosition
[ near
];
5646 popupPos
[ far
] = popupPos
[ near
] + popupSize
;
5648 popupPos
[ far
] = offsetParentPos
[ near
] +
5649 this.$element
.offsetParent()[ 'inner' + sizeProp
]() - parentPosition
[ far
];
5650 popupPos
[ near
] = popupPos
[ far
] - popupSize
;
5653 if ( this.anchored
) {
5654 // Position the anchor (which is positioned relative to the popup) to point to $floatableContainer
5655 anchorPos
= ( floatablePos
[ start
] + floatablePos
[ end
] ) / 2;
5656 anchorOffset
= ( start
=== far
? -1 : 1 ) * ( anchorPos
- popupPos
[ start
] );
5658 // If the anchor is less than 2*anchorSize from either edge, move the popup to make more space
5659 // this.$anchor.width()/height() returns 0 because of the CSS trickery we use, so use scrollWidth/Height
5660 anchorSize
= this.$anchor
[ 0 ][ 'scroll' + sizeProp
];
5661 anchorMargin
= parseFloat( this.$anchor
.css( 'margin-' + start
) );
5662 if ( anchorOffset
+ anchorMargin
< 2 * anchorSize
) {
5663 // Not enough space for the anchor on the start side; pull the popup startwards
5664 positionAdjustment
= ( positionProp
=== start
? -1 : 1 ) *
5665 ( 2 * anchorSize
- ( anchorOffset
+ anchorMargin
) );
5666 } else if ( anchorOffset
+ anchorMargin
> popupSize
- 2 * anchorSize
) {
5667 // Not enough space for the anchor on the end side; pull the popup endwards
5668 positionAdjustment
= ( positionProp
=== end
? -1 : 1 ) *
5669 ( anchorOffset
+ anchorMargin
- ( popupSize
- 2 * anchorSize
) );
5671 positionAdjustment
= 0;
5674 positionAdjustment
= 0;
5677 // Check if the popup will go beyond the edge of this.$container
5678 containerPos
= this.$container
[ 0 ] === document
.documentElement
?
5679 { top
: 0, left
: 0 } :
5680 this.$container
.offset();
5681 containerPos
[ far
] = containerPos
[ near
] + this.$container
[ 'inner' + sizeProp
]();
5682 if ( this.$container
[ 0 ] === document
.documentElement
) {
5683 viewportSpacing
= OO
.ui
.getViewportSpacing();
5684 containerPos
[ near
] += viewportSpacing
[ near
];
5685 containerPos
[ far
] -= viewportSpacing
[ far
];
5687 // Take into account how much the popup will move because of the adjustments we're going to make
5688 popupPos
[ near
] += ( positionProp
=== near
? 1 : -1 ) * positionAdjustment
;
5689 popupPos
[ far
] += ( positionProp
=== near
? 1 : -1 ) * positionAdjustment
;
5690 if ( containerPos
[ near
] + this.containerPadding
> popupPos
[ near
] ) {
5691 // Popup goes beyond the near (left/top) edge, move it to the right/bottom
5692 positionAdjustment
+= ( positionProp
=== near
? 1 : -1 ) *
5693 ( containerPos
[ near
] + this.containerPadding
- popupPos
[ near
] );
5694 } else if ( containerPos
[ far
] - this.containerPadding
< popupPos
[ far
] ) {
5695 // Popup goes beyond the far (right/bottom) edge, move it to the left/top
5696 positionAdjustment
+= ( positionProp
=== far
? 1 : -1 ) *
5697 ( popupPos
[ far
] - ( containerPos
[ far
] - this.containerPadding
) );
5700 if ( this.anchored
) {
5701 // Adjust anchorOffset for positionAdjustment
5702 anchorOffset
+= ( positionProp
=== start
? -1 : 1 ) * positionAdjustment
;
5704 // Position the anchor
5705 anchorCss
[ start
] = anchorOffset
;
5706 this.$anchor
.css( anchorCss
);
5709 // Move the popup if needed
5710 parentPosition
[ positionProp
] += positionAdjustment
;
5712 return parentPosition
;
5716 * Set popup alignment
5718 * @param {string} [align=center] Alignment of the popup, `center`, `force-left`, `force-right`,
5719 * `backwards` or `forwards`.
5721 OO
.ui
.PopupWidget
.prototype.setAlignment = function ( align
) {
5722 // Validate alignment
5723 if ( [ 'force-left', 'force-right', 'backwards', 'forwards', 'center' ].indexOf( align
) > -1 ) {
5726 this.align
= 'center';
5732 * Get popup alignment
5734 * @return {string} Alignment of the popup, `center`, `force-left`, `force-right`,
5735 * `backwards` or `forwards`.
5737 OO
.ui
.PopupWidget
.prototype.getAlignment = function () {
5742 * Change the positioning of the popup.
5744 * @param {string} position 'above', 'below', 'before' or 'after'
5746 OO
.ui
.PopupWidget
.prototype.setPosition = function ( position
) {
5747 if ( [ 'above', 'below', 'before', 'after' ].indexOf( position
) === -1 ) {
5750 this.popupPosition
= position
;
5755 * Get popup positioning.
5757 * @return {string} 'above', 'below', 'before' or 'after'
5759 OO
.ui
.PopupWidget
.prototype.getPosition = function () {
5760 return this.popupPosition
;
5764 * Set popup auto-flipping.
5766 * @param {boolean} autoFlip Whether to automatically switch the popup's position between
5767 * 'above' and 'below', or between 'before' and 'after', if there is not enough space in the
5768 * desired direction to display the popup without clipping
5770 OO
.ui
.PopupWidget
.prototype.setAutoFlip = function ( autoFlip
) {
5771 autoFlip
= !!autoFlip
;
5773 if ( this.autoFlip
!== autoFlip
) {
5774 this.autoFlip
= autoFlip
;
5779 * Set which elements will not close the popup when clicked.
5781 * For auto-closing popups, clicks on these elements will not cause the popup to auto-close.
5783 * @param {jQuery} $autoCloseIgnore Elements to ignore for auto-closing
5785 OO
.ui
.PopupWidget
.prototype.setAutoCloseIgnore = function ( $autoCloseIgnore
) {
5786 this.$autoCloseIgnore
= $autoCloseIgnore
;
5790 * Get an ID of the body element, this can be used as the
5791 * `aria-describedby` attribute for an input field.
5793 * @return {string} The ID of the body element
5795 OO
.ui
.PopupWidget
.prototype.getBodyId = function () {
5796 var id
= this.$body
.attr( 'id' );
5797 if ( id
=== undefined ) {
5798 id
= OO
.ui
.generateElementId();
5799 this.$body
.attr( 'id', id
);
5805 * PopupElement is mixed into other classes to generate a {@link OO.ui.PopupWidget popup widget}.
5806 * A popup is a container for content. It is overlaid and positioned absolutely. By default, each
5807 * popup has an anchor, which is an arrow-like protrusion that points toward the popup’s origin.
5808 * See {@link OO.ui.PopupWidget PopupWidget} for an example.
5814 * @param {Object} [config] Configuration options
5815 * @cfg {Object} [popup] Configuration to pass to popup
5816 * @cfg {boolean} [popup.autoClose=true] Popup auto-closes when it loses focus
5818 OO
.ui
.mixin
.PopupElement
= function OoUiMixinPopupElement( config
) {
5819 // Configuration initialization
5820 config
= config
|| {};
5823 this.popup
= new OO
.ui
.PopupWidget( $.extend(
5826 $floatableContainer
: this.$element
5830 $autoCloseIgnore
: this.$element
.add( config
.popup
&& config
.popup
.$autoCloseIgnore
)
5840 * @return {OO.ui.PopupWidget} Popup widget
5842 OO
.ui
.mixin
.PopupElement
.prototype.getPopup = function () {
5847 * PopupButtonWidgets toggle the visibility of a contained {@link OO.ui.PopupWidget PopupWidget},
5848 * which is used to display additional information or options.
5851 * // Example of a popup button.
5852 * var popupButton = new OO.ui.PopupButtonWidget( {
5853 * label: 'Popup button with options',
5856 * $content: $( '<p>Additional options here.</p>' ),
5858 * align: 'force-left'
5861 * // Append the button to the DOM.
5862 * $( 'body' ).append( popupButton.$element );
5865 * @extends OO.ui.ButtonWidget
5866 * @mixins OO.ui.mixin.PopupElement
5869 * @param {Object} [config] Configuration options
5870 * @cfg {jQuery} [$overlay] Render the popup into a separate layer. This configuration is useful in cases where
5871 * the expanded popup is larger than its containing `<div>`. The specified overlay layer is usually on top of the
5872 * containing `<div>` and has a larger area. By default, the popup uses relative positioning.
5873 * See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
5875 OO
.ui
.PopupButtonWidget
= function OoUiPopupButtonWidget( config
) {
5876 // Configuration initialization
5877 config
= config
|| {};
5879 // Parent constructor
5880 OO
.ui
.PopupButtonWidget
.parent
.call( this, config
);
5882 // Mixin constructors
5883 OO
.ui
.mixin
.PopupElement
.call( this, config
);
5886 this.$overlay
= ( config
.$overlay
=== true ? OO
.ui
.getDefaultOverlay() : config
.$overlay
) || this.$element
;
5889 this.connect( this, { click
: 'onAction' } );
5893 .addClass( 'oo-ui-popupButtonWidget' );
5895 .addClass( 'oo-ui-popupButtonWidget-popup' )
5896 .toggleClass( 'oo-ui-popupButtonWidget-framed-popup', this.isFramed() )
5897 .toggleClass( 'oo-ui-popupButtonWidget-frameless-popup', !this.isFramed() );
5898 this.$overlay
.append( this.popup
.$element
);
5903 OO
.inheritClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.ButtonWidget
);
5904 OO
.mixinClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.mixin
.PopupElement
);
5909 * Handle the button action being triggered.
5913 OO
.ui
.PopupButtonWidget
.prototype.onAction = function () {
5914 this.popup
.toggle();
5918 * Mixin for OO.ui.Widget subclasses to provide OO.ui.mixin.GroupElement.
5920 * Use together with OO.ui.mixin.ItemWidget to make disabled state inheritable.
5925 * @mixins OO.ui.mixin.GroupElement
5928 * @param {Object} [config] Configuration options
5930 OO
.ui
.mixin
.GroupWidget
= function OoUiMixinGroupWidget( config
) {
5931 // Mixin constructors
5932 OO
.ui
.mixin
.GroupElement
.call( this, config
);
5937 OO
.mixinClass( OO
.ui
.mixin
.GroupWidget
, OO
.ui
.mixin
.GroupElement
);
5942 * Set the disabled state of the widget.
5944 * This will also update the disabled state of child widgets.
5946 * @param {boolean} disabled Disable widget
5949 OO
.ui
.mixin
.GroupWidget
.prototype.setDisabled = function ( disabled
) {
5953 // Note: Calling #setDisabled this way assumes this is mixed into an OO.ui.Widget
5954 OO
.ui
.Widget
.prototype.setDisabled
.call( this, disabled
);
5956 // During construction, #setDisabled is called before the OO.ui.mixin.GroupElement constructor
5958 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5959 this.items
[ i
].updateDisabled();
5967 * Mixin for widgets used as items in widgets that mix in OO.ui.mixin.GroupWidget.
5969 * Item widgets have a reference to a OO.ui.mixin.GroupWidget while they are attached to the group. This
5970 * allows bidirectional communication.
5972 * Use together with OO.ui.mixin.GroupWidget to make disabled state inheritable.
5980 OO
.ui
.mixin
.ItemWidget
= function OoUiMixinItemWidget() {
5987 * Check if widget is disabled.
5989 * Checks parent if present, making disabled state inheritable.
5991 * @return {boolean} Widget is disabled
5993 OO
.ui
.mixin
.ItemWidget
.prototype.isDisabled = function () {
5994 return this.disabled
||
5995 ( this.elementGroup
instanceof OO
.ui
.Widget
&& this.elementGroup
.isDisabled() );
5999 * Set group element is in.
6001 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
6004 OO
.ui
.mixin
.ItemWidget
.prototype.setElementGroup = function ( group
) {
6006 // Note: Calling #setElementGroup this way assumes this is mixed into an OO.ui.Element
6007 OO
.ui
.Element
.prototype.setElementGroup
.call( this, group
);
6009 // Initialize item disabled states
6010 this.updateDisabled();
6016 * OptionWidgets are special elements that can be selected and configured with data. The
6017 * data is often unique for each option, but it does not have to be. OptionWidgets are used
6018 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
6019 * and examples, please see the [OOUI documentation on MediaWiki][1].
6021 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options
6024 * @extends OO.ui.Widget
6025 * @mixins OO.ui.mixin.ItemWidget
6026 * @mixins OO.ui.mixin.LabelElement
6027 * @mixins OO.ui.mixin.FlaggedElement
6028 * @mixins OO.ui.mixin.AccessKeyedElement
6031 * @param {Object} [config] Configuration options
6033 OO
.ui
.OptionWidget
= function OoUiOptionWidget( config
) {
6034 // Configuration initialization
6035 config
= config
|| {};
6037 // Parent constructor
6038 OO
.ui
.OptionWidget
.parent
.call( this, config
);
6040 // Mixin constructors
6041 OO
.ui
.mixin
.ItemWidget
.call( this );
6042 OO
.ui
.mixin
.LabelElement
.call( this, config
);
6043 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
6044 OO
.ui
.mixin
.AccessKeyedElement
.call( this, config
);
6047 this.selected
= false;
6048 this.highlighted
= false;
6049 this.pressed
= false;
6053 .data( 'oo-ui-optionWidget', this )
6054 // Allow programmatic focussing (and by accesskey), but not tabbing
6055 .attr( 'tabindex', '-1' )
6056 .attr( 'role', 'option' )
6057 .attr( 'aria-selected', 'false' )
6058 .addClass( 'oo-ui-optionWidget' )
6059 .append( this.$label
);
6064 OO
.inheritClass( OO
.ui
.OptionWidget
, OO
.ui
.Widget
);
6065 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.ItemWidget
);
6066 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.LabelElement
);
6067 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.FlaggedElement
);
6068 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
6070 /* Static Properties */
6073 * Whether this option can be selected. See #setSelected.
6077 * @property {boolean}
6079 OO
.ui
.OptionWidget
.static.selectable
= true;
6082 * Whether this option can be highlighted. See #setHighlighted.
6086 * @property {boolean}
6088 OO
.ui
.OptionWidget
.static.highlightable
= true;
6091 * Whether this option can be pressed. See #setPressed.
6095 * @property {boolean}
6097 OO
.ui
.OptionWidget
.static.pressable
= true;
6100 * Whether this option will be scrolled into view when it is selected.
6104 * @property {boolean}
6106 OO
.ui
.OptionWidget
.static.scrollIntoViewOnSelect
= false;
6111 * Check if the option can be selected.
6113 * @return {boolean} Item is selectable
6115 OO
.ui
.OptionWidget
.prototype.isSelectable = function () {
6116 return this.constructor.static.selectable
&& !this.disabled
&& this.isVisible();
6120 * Check if the option can be highlighted. A highlight indicates that the option
6121 * may be selected when a user presses enter or clicks. Disabled items cannot
6124 * @return {boolean} Item is highlightable
6126 OO
.ui
.OptionWidget
.prototype.isHighlightable = function () {
6127 return this.constructor.static.highlightable
&& !this.disabled
&& this.isVisible();
6131 * Check if the option can be pressed. The pressed state occurs when a user mouses
6132 * down on an item, but has not yet let go of the mouse.
6134 * @return {boolean} Item is pressable
6136 OO
.ui
.OptionWidget
.prototype.isPressable = function () {
6137 return this.constructor.static.pressable
&& !this.disabled
&& this.isVisible();
6141 * Check if the option is selected.
6143 * @return {boolean} Item is selected
6145 OO
.ui
.OptionWidget
.prototype.isSelected = function () {
6146 return this.selected
;
6150 * Check if the option is highlighted. A highlight indicates that the
6151 * item may be selected when a user presses enter or clicks.
6153 * @return {boolean} Item is highlighted
6155 OO
.ui
.OptionWidget
.prototype.isHighlighted = function () {
6156 return this.highlighted
;
6160 * Check if the option is pressed. The pressed state occurs when a user mouses
6161 * down on an item, but has not yet let go of the mouse. The item may appear
6162 * selected, but it will not be selected until the user releases the mouse.
6164 * @return {boolean} Item is pressed
6166 OO
.ui
.OptionWidget
.prototype.isPressed = function () {
6167 return this.pressed
;
6171 * Set the option’s selected state. In general, all modifications to the selection
6172 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
6173 * method instead of this method.
6175 * @param {boolean} [state=false] Select option
6178 OO
.ui
.OptionWidget
.prototype.setSelected = function ( state
) {
6179 if ( this.constructor.static.selectable
) {
6180 this.selected
= !!state
;
6182 .toggleClass( 'oo-ui-optionWidget-selected', state
)
6183 .attr( 'aria-selected', state
.toString() );
6184 if ( state
&& this.constructor.static.scrollIntoViewOnSelect
) {
6185 this.scrollElementIntoView();
6187 this.updateThemeClasses();
6193 * Set the option’s highlighted state. In general, all programmatic
6194 * modifications to the highlight should be handled by the
6195 * SelectWidget’s {@link OO.ui.SelectWidget#highlightItem highlightItem( [item] )}
6196 * method instead of this method.
6198 * @param {boolean} [state=false] Highlight option
6201 OO
.ui
.OptionWidget
.prototype.setHighlighted = function ( state
) {
6202 if ( this.constructor.static.highlightable
) {
6203 this.highlighted
= !!state
;
6204 this.$element
.toggleClass( 'oo-ui-optionWidget-highlighted', state
);
6205 this.updateThemeClasses();
6211 * Set the option’s pressed state. In general, all
6212 * programmatic modifications to the pressed state should be handled by the
6213 * SelectWidget’s {@link OO.ui.SelectWidget#pressItem pressItem( [item] )}
6214 * method instead of this method.
6216 * @param {boolean} [state=false] Press option
6219 OO
.ui
.OptionWidget
.prototype.setPressed = function ( state
) {
6220 if ( this.constructor.static.pressable
) {
6221 this.pressed
= !!state
;
6222 this.$element
.toggleClass( 'oo-ui-optionWidget-pressed', state
);
6223 this.updateThemeClasses();
6229 * Get text to match search strings against.
6231 * The default implementation returns the label text, but subclasses
6232 * can override this to provide more complex behavior.
6234 * @return {string|boolean} String to match search string against
6236 OO
.ui
.OptionWidget
.prototype.getMatchText = function () {
6237 var label
= this.getLabel();
6238 return typeof label
=== 'string' ? label
: this.$label
.text();
6242 * A SelectWidget is of a generic selection of options. The OOUI library contains several types of
6243 * select widgets, including {@link OO.ui.ButtonSelectWidget button selects},
6244 * {@link OO.ui.RadioSelectWidget radio selects}, and {@link OO.ui.MenuSelectWidget
6247 * This class should be used together with OO.ui.OptionWidget or OO.ui.DecoratedOptionWidget. For more
6248 * information, please see the [OOUI documentation on MediaWiki][1].
6251 * // Example of a select widget with three options
6252 * var select = new OO.ui.SelectWidget( {
6254 * new OO.ui.OptionWidget( {
6256 * label: 'Option One',
6258 * new OO.ui.OptionWidget( {
6260 * label: 'Option Two',
6262 * new OO.ui.OptionWidget( {
6264 * label: 'Option Three',
6268 * $( 'body' ).append( select.$element );
6270 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options
6274 * @extends OO.ui.Widget
6275 * @mixins OO.ui.mixin.GroupWidget
6278 * @param {Object} [config] Configuration options
6279 * @cfg {OO.ui.OptionWidget[]} [items] An array of options to add to the select.
6280 * Options are created with {@link OO.ui.OptionWidget OptionWidget} classes. See
6281 * the [OOUI documentation on MediaWiki] [2] for examples.
6282 * [2]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options
6284 OO
.ui
.SelectWidget
= function OoUiSelectWidget( config
) {
6285 // Configuration initialization
6286 config
= config
|| {};
6288 // Parent constructor
6289 OO
.ui
.SelectWidget
.parent
.call( this, config
);
6291 // Mixin constructors
6292 OO
.ui
.mixin
.GroupWidget
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
6295 this.pressed
= false;
6296 this.selecting
= null;
6297 this.onDocumentMouseUpHandler
= this.onDocumentMouseUp
.bind( this );
6298 this.onDocumentMouseMoveHandler
= this.onDocumentMouseMove
.bind( this );
6299 this.onDocumentKeyDownHandler
= this.onDocumentKeyDown
.bind( this );
6300 this.onDocumentKeyPressHandler
= this.onDocumentKeyPress
.bind( this );
6301 this.keyPressBuffer
= '';
6302 this.keyPressBufferTimer
= null;
6303 this.blockMouseOverEvents
= 0;
6306 this.connect( this, {
6310 focusin
: this.onFocus
.bind( this ),
6311 mousedown
: this.onMouseDown
.bind( this ),
6312 mouseover
: this.onMouseOver
.bind( this ),
6313 mouseleave
: this.onMouseLeave
.bind( this )
6318 .addClass( 'oo-ui-selectWidget oo-ui-selectWidget-depressed' )
6319 .attr( 'role', 'listbox' );
6320 this.setFocusOwner( this.$element
);
6321 if ( Array
.isArray( config
.items
) ) {
6322 this.addItems( config
.items
);
6328 OO
.inheritClass( OO
.ui
.SelectWidget
, OO
.ui
.Widget
);
6329 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupWidget
);
6336 * A `highlight` event is emitted when the highlight is changed with the #highlightItem method.
6338 * @param {OO.ui.OptionWidget|null} item Highlighted item
6344 * A `press` event is emitted when the #pressItem method is used to programmatically modify the
6345 * pressed state of an option.
6347 * @param {OO.ui.OptionWidget|null} item Pressed item
6353 * A `select` event is emitted when the selection is modified programmatically with the #selectItem method.
6355 * @param {OO.ui.OptionWidget|null} item Selected item
6360 * A `choose` event is emitted when an item is chosen with the #chooseItem method.
6361 * @param {OO.ui.OptionWidget} item Chosen item
6367 * An `add` event is emitted when options are added to the select with the #addItems method.
6369 * @param {OO.ui.OptionWidget[]} items Added items
6370 * @param {number} index Index of insertion point
6376 * A `remove` event is emitted when options are removed from the select with the #clearItems
6377 * or #removeItems methods.
6379 * @param {OO.ui.OptionWidget[]} items Removed items
6385 * Handle focus events
6388 * @param {jQuery.Event} event
6390 OO
.ui
.SelectWidget
.prototype.onFocus = function ( event
) {
6392 if ( event
.target
=== this.$element
[ 0 ] ) {
6393 // This widget was focussed, e.g. by the user tabbing to it.
6394 // The styles for focus state depend on one of the items being selected.
6395 if ( !this.findSelectedItem() ) {
6396 item
= this.findFirstSelectableItem();
6399 if ( event
.target
.tabIndex
=== -1 ) {
6400 // One of the options got focussed (and the event bubbled up here).
6401 // They can't be tabbed to, but they can be activated using accesskeys.
6402 // OptionWidgets and focusable UI elements inside them have tabindex="-1" set.
6403 item
= this.findTargetItem( event
);
6405 // There is something actually user-focusable in one of the labels of the options, and the
6406 // user focussed it (e.g. by tabbing to it). Do nothing (especially, don't change the focus).
6412 if ( item
.constructor.static.highlightable
) {
6413 this.highlightItem( item
);
6415 this.selectItem( item
);
6419 if ( event
.target
!== this.$element
[ 0 ] ) {
6420 this.$focusOwner
.focus();
6425 * Handle mouse down events.
6428 * @param {jQuery.Event} e Mouse down event
6430 OO
.ui
.SelectWidget
.prototype.onMouseDown = function ( e
) {
6433 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
6434 this.togglePressed( true );
6435 item
= this.findTargetItem( e
);
6436 if ( item
&& item
.isSelectable() ) {
6437 this.pressItem( item
);
6438 this.selecting
= item
;
6439 this.getElementDocument().addEventListener( 'mouseup', this.onDocumentMouseUpHandler
, true );
6440 this.getElementDocument().addEventListener( 'mousemove', this.onDocumentMouseMoveHandler
, true );
6447 * Handle document mouse up events.
6450 * @param {MouseEvent} e Mouse up event
6452 OO
.ui
.SelectWidget
.prototype.onDocumentMouseUp = function ( e
) {
6455 this.togglePressed( false );
6456 if ( !this.selecting
) {
6457 item
= this.findTargetItem( e
);
6458 if ( item
&& item
.isSelectable() ) {
6459 this.selecting
= item
;
6462 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
&& this.selecting
) {
6463 this.pressItem( null );
6464 this.chooseItem( this.selecting
);
6465 this.selecting
= null;
6468 this.getElementDocument().removeEventListener( 'mouseup', this.onDocumentMouseUpHandler
, true );
6469 this.getElementDocument().removeEventListener( 'mousemove', this.onDocumentMouseMoveHandler
, true );
6474 // Deprecated alias since 0.28.3
6475 OO
.ui
.SelectWidget
.prototype.onMouseUp = function () {
6476 OO
.ui
.warnDeprecation( 'onMouseUp is deprecated, use onDocumentMouseUp instead' );
6477 this.onDocumentMouseUp
.apply( this, arguments
);
6481 * Handle document mouse move events.
6484 * @param {MouseEvent} e Mouse move event
6486 OO
.ui
.SelectWidget
.prototype.onDocumentMouseMove = function ( e
) {
6489 if ( !this.isDisabled() && this.pressed
) {
6490 item
= this.findTargetItem( e
);
6491 if ( item
&& item
!== this.selecting
&& item
.isSelectable() ) {
6492 this.pressItem( item
);
6493 this.selecting
= item
;
6498 // Deprecated alias since 0.28.3
6499 OO
.ui
.SelectWidget
.prototype.onMouseMove = function () {
6500 OO
.ui
.warnDeprecation( 'onMouseMove is deprecated, use onDocumentMouseMove instead' );
6501 this.onDocumentMouseMove
.apply( this, arguments
);
6505 * Handle mouse over events.
6508 * @param {jQuery.Event} e Mouse over event
6510 OO
.ui
.SelectWidget
.prototype.onMouseOver = function ( e
) {
6512 if ( this.blockMouseOverEvents
) {
6515 if ( !this.isDisabled() ) {
6516 item
= this.findTargetItem( e
);
6517 this.highlightItem( item
&& item
.isHighlightable() ? item
: null );
6523 * Handle mouse leave events.
6526 * @param {jQuery.Event} e Mouse over event
6528 OO
.ui
.SelectWidget
.prototype.onMouseLeave = function () {
6529 if ( !this.isDisabled() ) {
6530 this.highlightItem( null );
6536 * Handle document key down events.
6539 * @param {KeyboardEvent} e Key down event
6541 OO
.ui
.SelectWidget
.prototype.onDocumentKeyDown = function ( e
) {
6544 currentItem
= this.findHighlightedItem() || this.findSelectedItem();
6546 if ( !this.isDisabled() && this.isVisible() ) {
6547 switch ( e
.keyCode
) {
6548 case OO
.ui
.Keys
.ENTER
:
6549 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
6550 // Was only highlighted, now let's select it. No-op if already selected.
6551 this.chooseItem( currentItem
);
6556 case OO
.ui
.Keys
.LEFT
:
6557 this.clearKeyPressBuffer();
6558 nextItem
= this.findRelativeSelectableItem( currentItem
, -1 );
6561 case OO
.ui
.Keys
.DOWN
:
6562 case OO
.ui
.Keys
.RIGHT
:
6563 this.clearKeyPressBuffer();
6564 nextItem
= this.findRelativeSelectableItem( currentItem
, 1 );
6567 case OO
.ui
.Keys
.ESCAPE
:
6568 case OO
.ui
.Keys
.TAB
:
6569 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
6570 currentItem
.setHighlighted( false );
6572 this.unbindDocumentKeyDownListener();
6573 this.unbindDocumentKeyPressListener();
6574 // Don't prevent tabbing away / defocusing
6580 if ( nextItem
.constructor.static.highlightable
) {
6581 this.highlightItem( nextItem
);
6583 this.chooseItem( nextItem
);
6585 this.scrollItemIntoView( nextItem
);
6590 e
.stopPropagation();
6595 // Deprecated alias since 0.28.3
6596 OO
.ui
.SelectWidget
.prototype.onKeyDown = function () {
6597 OO
.ui
.warnDeprecation( 'onKeyDown is deprecated, use onDocumentKeyDown instead' );
6598 this.onDocumentKeyDown
.apply( this, arguments
);
6602 * Bind document key down listener.
6606 OO
.ui
.SelectWidget
.prototype.bindDocumentKeyDownListener = function () {
6607 this.getElementDocument().addEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
6610 // Deprecated alias since 0.28.3
6611 OO
.ui
.SelectWidget
.prototype.bindKeyDownListener = function () {
6612 OO
.ui
.warnDeprecation( 'bindKeyDownListener is deprecated, use bindDocumentKeyDownListener instead' );
6613 this.bindDocumentKeyDownListener
.apply( this, arguments
);
6617 * Unbind document key down listener.
6621 OO
.ui
.SelectWidget
.prototype.unbindDocumentKeyDownListener = function () {
6622 this.getElementDocument().removeEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
6625 // Deprecated alias since 0.28.3
6626 OO
.ui
.SelectWidget
.prototype.unbindKeyDownListener = function () {
6627 OO
.ui
.warnDeprecation( 'unbindKeyDownListener is deprecated, use unbindDocumentKeyDownListener instead' );
6628 this.unbindDocumentKeyDownListener
.apply( this, arguments
);
6632 * Scroll item into view, preventing spurious mouse highlight actions from happening.
6634 * @param {OO.ui.OptionWidget} item Item to scroll into view
6636 OO
.ui
.SelectWidget
.prototype.scrollItemIntoView = function ( item
) {
6638 // Chromium's Blink engine will generate spurious 'mouseover' events during programmatic scrolling
6639 // and around 100-150 ms after it is finished.
6640 this.blockMouseOverEvents
++;
6641 item
.scrollElementIntoView().done( function () {
6642 setTimeout( function () {
6643 widget
.blockMouseOverEvents
--;
6649 * Clear the key-press buffer
6653 OO
.ui
.SelectWidget
.prototype.clearKeyPressBuffer = function () {
6654 if ( this.keyPressBufferTimer
) {
6655 clearTimeout( this.keyPressBufferTimer
);
6656 this.keyPressBufferTimer
= null;
6658 this.keyPressBuffer
= '';
6662 * Handle key press events.
6665 * @param {KeyboardEvent} e Key press event
6667 OO
.ui
.SelectWidget
.prototype.onDocumentKeyPress = function ( e
) {
6668 var c
, filter
, item
;
6670 if ( !e
.charCode
) {
6671 if ( e
.keyCode
=== OO
.ui
.Keys
.BACKSPACE
&& this.keyPressBuffer
!== '' ) {
6672 this.keyPressBuffer
= this.keyPressBuffer
.substr( 0, this.keyPressBuffer
.length
- 1 );
6677 if ( String
.fromCodePoint
) {
6678 c
= String
.fromCodePoint( e
.charCode
);
6680 c
= String
.fromCharCode( e
.charCode
);
6683 if ( this.keyPressBufferTimer
) {
6684 clearTimeout( this.keyPressBufferTimer
);
6686 this.keyPressBufferTimer
= setTimeout( this.clearKeyPressBuffer
.bind( this ), 1500 );
6688 item
= this.findHighlightedItem() || this.findSelectedItem();
6690 if ( this.keyPressBuffer
=== c
) {
6691 // Common (if weird) special case: typing "xxxx" will cycle through all
6692 // the items beginning with "x".
6694 item
= this.findRelativeSelectableItem( item
, 1 );
6697 this.keyPressBuffer
+= c
;
6700 filter
= this.getItemMatcher( this.keyPressBuffer
, false );
6701 if ( !item
|| !filter( item
) ) {
6702 item
= this.findRelativeSelectableItem( item
, 1, filter
);
6705 if ( this.isVisible() && item
.constructor.static.highlightable
) {
6706 this.highlightItem( item
);
6708 this.chooseItem( item
);
6710 this.scrollItemIntoView( item
);
6714 e
.stopPropagation();
6717 // Deprecated alias since 0.28.3
6718 OO
.ui
.SelectWidget
.prototype.onKeyPress = function () {
6719 OO
.ui
.warnDeprecation( 'onKeyPress is deprecated, use onDocumentKeyPress instead' );
6720 this.onDocumentKeyPress
.apply( this, arguments
);
6724 * Get a matcher for the specific string
6727 * @param {string} s String to match against items
6728 * @param {boolean} [exact=false] Only accept exact matches
6729 * @return {Function} function ( OO.ui.OptionWidget ) => boolean
6731 OO
.ui
.SelectWidget
.prototype.getItemMatcher = function ( s
, exact
) {
6734 if ( s
.normalize
) {
6737 s
= exact
? s
.trim() : s
.replace( /^\s+/, '' );
6738 re
= '^\\s*' + s
.replace( /([\\{}()|.?*+\-^$[\]])/g, '\\$1' ).replace( /\s+/g, '\\s+' );
6742 re
= new RegExp( re
, 'i' );
6743 return function ( item
) {
6744 var matchText
= item
.getMatchText();
6745 if ( matchText
.normalize
) {
6746 matchText
= matchText
.normalize();
6748 return re
.test( matchText
);
6753 * Bind document key press listener.
6757 OO
.ui
.SelectWidget
.prototype.bindDocumentKeyPressListener = function () {
6758 this.getElementDocument().addEventListener( 'keypress', this.onDocumentKeyPressHandler
, true );
6761 // Deprecated alias since 0.28.3
6762 OO
.ui
.SelectWidget
.prototype.bindKeyPressListener = function () {
6763 OO
.ui
.warnDeprecation( 'bindKeyPressListener is deprecated, use bindDocumentKeyPressListener instead' );
6764 this.bindDocumentKeyPressListener
.apply( this, arguments
);
6768 * Unbind document key down listener.
6770 * If you override this, be sure to call this.clearKeyPressBuffer() from your
6775 OO
.ui
.SelectWidget
.prototype.unbindDocumentKeyPressListener = function () {
6776 this.getElementDocument().removeEventListener( 'keypress', this.onDocumentKeyPressHandler
, true );
6777 this.clearKeyPressBuffer();
6780 // Deprecated alias since 0.28.3
6781 OO
.ui
.SelectWidget
.prototype.unbindKeyPressListener = function () {
6782 OO
.ui
.warnDeprecation( 'unbindDocumentKeyPressListener is deprecated, use unbindDocumentKeyPressListener instead' );
6783 this.unbindDocumentKeyPressListener
.apply( this, arguments
);
6787 * Visibility change handler
6790 * @param {boolean} visible
6792 OO
.ui
.SelectWidget
.prototype.onToggle = function ( visible
) {
6794 this.clearKeyPressBuffer();
6799 * Get the closest item to a jQuery.Event.
6802 * @param {jQuery.Event} e
6803 * @return {OO.ui.OptionWidget|null} Outline item widget, `null` if none was found
6805 OO
.ui
.SelectWidget
.prototype.findTargetItem = function ( e
) {
6806 var $option
= $( e
.target
).closest( '.oo-ui-optionWidget' );
6807 if ( !$option
.closest( '.oo-ui-selectWidget' ).is( this.$element
) ) {
6810 return $option
.data( 'oo-ui-optionWidget' ) || null;
6814 * Find selected item.
6816 * @return {OO.ui.OptionWidget|null} Selected item, `null` if no item is selected
6818 OO
.ui
.SelectWidget
.prototype.findSelectedItem = function () {
6821 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6822 if ( this.items
[ i
].isSelected() ) {
6823 return this.items
[ i
];
6830 * Find highlighted item.
6832 * @return {OO.ui.OptionWidget|null} Highlighted item, `null` if no item is highlighted
6834 OO
.ui
.SelectWidget
.prototype.findHighlightedItem = function () {
6837 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6838 if ( this.items
[ i
].isHighlighted() ) {
6839 return this.items
[ i
];
6846 * Toggle pressed state.
6848 * Press is a state that occurs when a user mouses down on an item, but
6849 * has not yet let go of the mouse. The item may appear selected, but it will not be selected
6850 * until the user releases the mouse.
6852 * @param {boolean} pressed An option is being pressed
6854 OO
.ui
.SelectWidget
.prototype.togglePressed = function ( pressed
) {
6855 if ( pressed
=== undefined ) {
6856 pressed
= !this.pressed
;
6858 if ( pressed
!== this.pressed
) {
6860 .toggleClass( 'oo-ui-selectWidget-pressed', pressed
)
6861 .toggleClass( 'oo-ui-selectWidget-depressed', !pressed
);
6862 this.pressed
= pressed
;
6867 * Highlight an option. If the `item` param is omitted, no options will be highlighted
6868 * and any existing highlight will be removed. The highlight is mutually exclusive.
6870 * @param {OO.ui.OptionWidget} [item] Item to highlight, omit for no highlight
6874 OO
.ui
.SelectWidget
.prototype.highlightItem = function ( item
) {
6875 var i
, len
, highlighted
,
6878 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6879 highlighted
= this.items
[ i
] === item
;
6880 if ( this.items
[ i
].isHighlighted() !== highlighted
) {
6881 this.items
[ i
].setHighlighted( highlighted
);
6887 this.$focusOwner
.attr( 'aria-activedescendant', item
.getElementId() );
6889 this.$focusOwner
.removeAttr( 'aria-activedescendant' );
6891 this.emit( 'highlight', item
);
6898 * Fetch an item by its label.
6900 * @param {string} label Label of the item to select.
6901 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
6902 * @return {OO.ui.Element|null} Item with equivalent label, `null` if none exists
6904 OO
.ui
.SelectWidget
.prototype.getItemFromLabel = function ( label
, prefix
) {
6906 len
= this.items
.length
,
6907 filter
= this.getItemMatcher( label
, true );
6909 for ( i
= 0; i
< len
; i
++ ) {
6910 item
= this.items
[ i
];
6911 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
6918 filter
= this.getItemMatcher( label
, false );
6919 for ( i
= 0; i
< len
; i
++ ) {
6920 item
= this.items
[ i
];
6921 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
6937 * Programmatically select an option by its label. If the item does not exist,
6938 * all options will be deselected.
6940 * @param {string} [label] Label of the item to select.
6941 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
6945 OO
.ui
.SelectWidget
.prototype.selectItemByLabel = function ( label
, prefix
) {
6946 var itemFromLabel
= this.getItemFromLabel( label
, !!prefix
);
6947 if ( label
=== undefined || !itemFromLabel
) {
6948 return this.selectItem();
6950 return this.selectItem( itemFromLabel
);
6954 * Programmatically select an option by its data. If the `data` parameter is omitted,
6955 * or if the item does not exist, all options will be deselected.
6957 * @param {Object|string} [data] Value of the item to select, omit to deselect all
6961 OO
.ui
.SelectWidget
.prototype.selectItemByData = function ( data
) {
6962 var itemFromData
= this.findItemFromData( data
);
6963 if ( data
=== undefined || !itemFromData
) {
6964 return this.selectItem();
6966 return this.selectItem( itemFromData
);
6970 * Programmatically select an option by its reference. If the `item` parameter is omitted,
6971 * all options will be deselected.
6973 * @param {OO.ui.OptionWidget} [item] Item to select, omit to deselect all
6977 OO
.ui
.SelectWidget
.prototype.selectItem = function ( item
) {
6978 var i
, len
, selected
,
6981 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6982 selected
= this.items
[ i
] === item
;
6983 if ( this.items
[ i
].isSelected() !== selected
) {
6984 this.items
[ i
].setSelected( selected
);
6989 if ( item
&& !item
.constructor.static.highlightable
) {
6991 this.$focusOwner
.attr( 'aria-activedescendant', item
.getElementId() );
6993 this.$focusOwner
.removeAttr( 'aria-activedescendant' );
6996 this.emit( 'select', item
);
7005 * Press is a state that occurs when a user mouses down on an item, but has not
7006 * yet let go of the mouse. The item may appear selected, but it will not be selected until the user
7007 * releases the mouse.
7009 * @param {OO.ui.OptionWidget} [item] Item to press, omit to depress all
7013 OO
.ui
.SelectWidget
.prototype.pressItem = function ( item
) {
7014 var i
, len
, pressed
,
7017 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
7018 pressed
= this.items
[ i
] === item
;
7019 if ( this.items
[ i
].isPressed() !== pressed
) {
7020 this.items
[ i
].setPressed( pressed
);
7025 this.emit( 'press', item
);
7034 * Note that ‘choose’ should never be modified programmatically. A user can choose
7035 * an option with the keyboard or mouse and it becomes selected. To select an item programmatically,
7036 * use the #selectItem method.
7038 * This method is identical to #selectItem, but may vary in subclasses that take additional action
7039 * when users choose an item with the keyboard or mouse.
7041 * @param {OO.ui.OptionWidget} item Item to choose
7045 OO
.ui
.SelectWidget
.prototype.chooseItem = function ( item
) {
7047 this.selectItem( item
);
7048 this.emit( 'choose', item
);
7055 * Find an option by its position relative to the specified item (or to the start of the option array,
7056 * if item is `null`). The direction in which to search through the option array is specified with a
7057 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
7058 * `null` if there are no options in the array.
7060 * @param {OO.ui.OptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
7061 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
7062 * @param {Function} [filter] Only consider items for which this function returns
7063 * true. Function takes an OO.ui.OptionWidget and returns a boolean.
7064 * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no items in the select
7066 OO
.ui
.SelectWidget
.prototype.findRelativeSelectableItem = function ( item
, direction
, filter
) {
7067 var currentIndex
, nextIndex
, i
,
7068 increase
= direction
> 0 ? 1 : -1,
7069 len
= this.items
.length
;
7071 if ( item
instanceof OO
.ui
.OptionWidget
) {
7072 currentIndex
= this.items
.indexOf( item
);
7073 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
7075 // If no item is selected and moving forward, start at the beginning.
7076 // If moving backward, start at the end.
7077 nextIndex
= direction
> 0 ? 0 : len
- 1;
7080 for ( i
= 0; i
< len
; i
++ ) {
7081 item
= this.items
[ nextIndex
];
7083 item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() &&
7084 ( !filter
|| filter( item
) )
7088 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
7094 * Find the next selectable item or `null` if there are no selectable items.
7095 * Disabled options and menu-section markers and breaks are not selectable.
7097 * @return {OO.ui.OptionWidget|null} Item, `null` if there aren't any selectable items
7099 OO
.ui
.SelectWidget
.prototype.findFirstSelectableItem = function () {
7100 return this.findRelativeSelectableItem( null, 1 );
7104 * Add an array of options to the select. Optionally, an index number can be used to
7105 * specify an insertion point.
7107 * @param {OO.ui.OptionWidget[]} items Items to add
7108 * @param {number} [index] Index to insert items after
7112 OO
.ui
.SelectWidget
.prototype.addItems = function ( items
, index
) {
7114 OO
.ui
.mixin
.GroupWidget
.prototype.addItems
.call( this, items
, index
);
7116 // Always provide an index, even if it was omitted
7117 this.emit( 'add', items
, index
=== undefined ? this.items
.length
- items
.length
- 1 : index
);
7123 * Remove the specified array of options from the select. Options will be detached
7124 * from the DOM, not removed, so they can be reused later. To remove all options from
7125 * the select, you may wish to use the #clearItems method instead.
7127 * @param {OO.ui.OptionWidget[]} items Items to remove
7131 OO
.ui
.SelectWidget
.prototype.removeItems = function ( items
) {
7134 // Deselect items being removed
7135 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
7137 if ( item
.isSelected() ) {
7138 this.selectItem( null );
7143 OO
.ui
.mixin
.GroupWidget
.prototype.removeItems
.call( this, items
);
7145 this.emit( 'remove', items
);
7151 * Clear all options from the select. Options will be detached from the DOM, not removed,
7152 * so that they can be reused later. To remove a subset of options from the select, use
7153 * the #removeItems method.
7158 OO
.ui
.SelectWidget
.prototype.clearItems = function () {
7159 var items
= this.items
.slice();
7162 OO
.ui
.mixin
.GroupWidget
.prototype.clearItems
.call( this );
7165 this.selectItem( null );
7167 this.emit( 'remove', items
);
7173 * Set the DOM element which has focus while the user is interacting with this SelectWidget.
7175 * Currently this is just used to set `aria-activedescendant` on it.
7178 * @param {jQuery} $focusOwner
7180 OO
.ui
.SelectWidget
.prototype.setFocusOwner = function ( $focusOwner
) {
7181 this.$focusOwner
= $focusOwner
;
7185 * DecoratedOptionWidgets are {@link OO.ui.OptionWidget options} that can be configured
7186 * with an {@link OO.ui.mixin.IconElement icon} and/or {@link OO.ui.mixin.IndicatorElement indicator}.
7187 * This class is used with OO.ui.SelectWidget to create a selection of mutually exclusive
7188 * options. For more information about options and selects, please see the
7189 * [OOUI documentation on MediaWiki][1].
7192 * // Decorated options in a select widget
7193 * var select = new OO.ui.SelectWidget( {
7195 * new OO.ui.DecoratedOptionWidget( {
7197 * label: 'Option with icon',
7200 * new OO.ui.DecoratedOptionWidget( {
7202 * label: 'Option with indicator',
7207 * $( 'body' ).append( select.$element );
7209 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options
7212 * @extends OO.ui.OptionWidget
7213 * @mixins OO.ui.mixin.IconElement
7214 * @mixins OO.ui.mixin.IndicatorElement
7217 * @param {Object} [config] Configuration options
7219 OO
.ui
.DecoratedOptionWidget
= function OoUiDecoratedOptionWidget( config
) {
7220 // Parent constructor
7221 OO
.ui
.DecoratedOptionWidget
.parent
.call( this, config
);
7223 // Mixin constructors
7224 OO
.ui
.mixin
.IconElement
.call( this, config
);
7225 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7229 .addClass( 'oo-ui-decoratedOptionWidget' )
7230 .prepend( this.$icon
)
7231 .append( this.$indicator
);
7236 OO
.inheritClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.OptionWidget
);
7237 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IconElement
);
7238 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IndicatorElement
);
7241 * MenuOptionWidget is an option widget that looks like a menu item. The class is used with
7242 * OO.ui.MenuSelectWidget to create a menu of mutually exclusive options. Please see
7243 * the [OOUI documentation on MediaWiki] [1] for more information.
7245 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options#Menu_selects_and_options
7248 * @extends OO.ui.DecoratedOptionWidget
7251 * @param {Object} [config] Configuration options
7253 OO
.ui
.MenuOptionWidget
= function OoUiMenuOptionWidget( config
) {
7254 // Parent constructor
7255 OO
.ui
.MenuOptionWidget
.parent
.call( this, config
);
7258 this.checkIcon
= new OO
.ui
.IconWidget( {
7260 classes
: [ 'oo-ui-menuOptionWidget-checkIcon' ]
7265 .prepend( this.checkIcon
.$element
)
7266 .addClass( 'oo-ui-menuOptionWidget' );
7271 OO
.inheritClass( OO
.ui
.MenuOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
7273 /* Static Properties */
7279 OO
.ui
.MenuOptionWidget
.static.scrollIntoViewOnSelect
= true;
7282 * MenuSectionOptionWidgets are used inside {@link OO.ui.MenuSelectWidget menu select widgets} to group one or more related
7283 * {@link OO.ui.MenuOptionWidget menu options}. MenuSectionOptionWidgets cannot be highlighted or selected.
7286 * var myDropdown = new OO.ui.DropdownWidget( {
7289 * new OO.ui.MenuSectionOptionWidget( {
7292 * new OO.ui.MenuOptionWidget( {
7294 * label: 'Welsh Corgi'
7296 * new OO.ui.MenuOptionWidget( {
7298 * label: 'Standard Poodle'
7300 * new OO.ui.MenuSectionOptionWidget( {
7303 * new OO.ui.MenuOptionWidget( {
7310 * $( 'body' ).append( myDropdown.$element );
7313 * @extends OO.ui.DecoratedOptionWidget
7316 * @param {Object} [config] Configuration options
7318 OO
.ui
.MenuSectionOptionWidget
= function OoUiMenuSectionOptionWidget( config
) {
7319 // Parent constructor
7320 OO
.ui
.MenuSectionOptionWidget
.parent
.call( this, config
);
7323 this.$element
.addClass( 'oo-ui-menuSectionOptionWidget' )
7324 .removeAttr( 'role aria-selected' );
7329 OO
.inheritClass( OO
.ui
.MenuSectionOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
7331 /* Static Properties */
7337 OO
.ui
.MenuSectionOptionWidget
.static.selectable
= false;
7343 OO
.ui
.MenuSectionOptionWidget
.static.highlightable
= false;
7346 * MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains options and
7347 * is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget.
7348 * See {@link OO.ui.DropdownWidget DropdownWidget}, {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget},
7349 * and {@link OO.ui.mixin.LookupElement LookupElement} for examples of widgets that contain menus.
7350 * MenuSelectWidgets themselves are not instantiated directly, rather subclassed
7351 * and customized to be opened, closed, and displayed as needed.
7353 * By default, menus are clipped to the visible viewport and are not visible when a user presses the
7354 * mouse outside the menu.
7356 * Menus also have support for keyboard interaction:
7358 * - Enter/Return key: choose and select a menu option
7359 * - Up-arrow key: highlight the previous menu option
7360 * - Down-arrow key: highlight the next menu option
7361 * - Esc key: hide the menu
7363 * Unlike most widgets, MenuSelectWidget is initially hidden and must be shown by calling #toggle.
7365 * Please see the [OOUI documentation on MediaWiki][1] for more information.
7366 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options
7369 * @extends OO.ui.SelectWidget
7370 * @mixins OO.ui.mixin.ClippableElement
7371 * @mixins OO.ui.mixin.FloatableElement
7374 * @param {Object} [config] Configuration options
7375 * @cfg {OO.ui.TextInputWidget} [input] Text input used to implement option highlighting for menu items that match
7376 * the text the user types. This config is used by {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget}
7377 * and {@link OO.ui.mixin.LookupElement LookupElement}
7378 * @cfg {jQuery} [$input] Text input used to implement option highlighting for menu items that match
7379 * the text the user types. This config is used by {@link OO.ui.TagMultiselectWidget TagMultiselectWidget}
7380 * @cfg {OO.ui.Widget} [widget] Widget associated with the menu's active state. If the user clicks the mouse
7381 * anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button
7382 * that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks
7383 * that button, unless the button (or its parent widget) is passed in here.
7384 * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed outside the menu.
7385 * @cfg {jQuery} [$autoCloseIgnore] If these elements are clicked, don't auto-hide the menu.
7386 * @cfg {boolean} [hideOnChoose=true] Hide the menu when the user chooses an option.
7387 * @cfg {boolean} [filterFromInput=false] Filter the displayed options from the input
7388 * @cfg {boolean} [highlightOnFilter] Highlight the first result when filtering
7389 * @cfg {number} [width] Width of the menu
7391 OO
.ui
.MenuSelectWidget
= function OoUiMenuSelectWidget( config
) {
7392 // Configuration initialization
7393 config
= config
|| {};
7395 // Parent constructor
7396 OO
.ui
.MenuSelectWidget
.parent
.call( this, config
);
7398 // Mixin constructors
7399 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, { $clippable
: this.$group
} ) );
7400 OO
.ui
.mixin
.FloatableElement
.call( this, config
);
7402 // Initial vertical positions other than 'center' will result in
7403 // the menu being flipped if there is not enough space in the container.
7404 // Store the original position so we know what to reset to.
7405 this.originalVerticalPosition
= this.verticalPosition
;
7408 this.autoHide
= config
.autoHide
=== undefined || !!config
.autoHide
;
7409 this.hideOnChoose
= config
.hideOnChoose
=== undefined || !!config
.hideOnChoose
;
7410 this.filterFromInput
= !!config
.filterFromInput
;
7411 this.$input
= config
.$input
? config
.$input
: config
.input
? config
.input
.$input
: null;
7412 this.$widget
= config
.widget
? config
.widget
.$element
: null;
7413 this.$autoCloseIgnore
= config
.$autoCloseIgnore
|| $( [] );
7414 this.onDocumentMouseDownHandler
= this.onDocumentMouseDown
.bind( this );
7415 this.onInputEditHandler
= OO
.ui
.debounce( this.updateItemVisibility
.bind( this ), 100 );
7416 this.highlightOnFilter
= !!config
.highlightOnFilter
;
7417 this.width
= config
.width
;
7420 this.$element
.addClass( 'oo-ui-menuSelectWidget' );
7421 if ( config
.widget
) {
7422 this.setFocusOwner( config
.widget
.$tabIndexed
);
7425 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
7426 // that reference properties not initialized at that time of parent class construction
7427 // TODO: Find a better way to handle post-constructor setup
7428 this.visible
= false;
7429 this.$element
.addClass( 'oo-ui-element-hidden' );
7434 OO
.inheritClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.SelectWidget
);
7435 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.ClippableElement
);
7436 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.FloatableElement
);
7443 * The menu is ready: it is visible and has been positioned and clipped.
7446 /* Static properties */
7449 * Positions to flip to if there isn't room in the container for the
7450 * menu in a specific direction.
7452 * @property {Object.<string,string>}
7454 OO
.ui
.MenuSelectWidget
.static.flippedPositions
= {
7464 * Handles document mouse down events.
7467 * @param {MouseEvent} e Mouse down event
7469 OO
.ui
.MenuSelectWidget
.prototype.onDocumentMouseDown = function ( e
) {
7473 this.$element
.add( this.$widget
).add( this.$autoCloseIgnore
).get(),
7478 this.toggle( false );
7485 OO
.ui
.MenuSelectWidget
.prototype.onDocumentKeyDown = function ( e
) {
7486 var currentItem
= this.findHighlightedItem() || this.findSelectedItem();
7488 if ( !this.isDisabled() && this.isVisible() ) {
7489 switch ( e
.keyCode
) {
7490 case OO
.ui
.Keys
.LEFT
:
7491 case OO
.ui
.Keys
.RIGHT
:
7492 // Do nothing if a text field is associated, arrow keys will be handled natively
7493 if ( !this.$input
) {
7494 OO
.ui
.MenuSelectWidget
.parent
.prototype.onDocumentKeyDown
.call( this, e
);
7497 case OO
.ui
.Keys
.ESCAPE
:
7498 case OO
.ui
.Keys
.TAB
:
7499 if ( currentItem
) {
7500 currentItem
.setHighlighted( false );
7502 this.toggle( false );
7503 // Don't prevent tabbing away, prevent defocusing
7504 if ( e
.keyCode
=== OO
.ui
.Keys
.ESCAPE
) {
7506 e
.stopPropagation();
7510 OO
.ui
.MenuSelectWidget
.parent
.prototype.onDocumentKeyDown
.call( this, e
);
7517 * Update menu item visibility and clipping after input changes (if filterFromInput is enabled)
7518 * or after items were added/removed (always).
7522 OO
.ui
.MenuSelectWidget
.prototype.updateItemVisibility = function () {
7523 var i
, item
, items
, visible
, section
, sectionEmpty
, filter
, exactFilter
,
7525 len
= this.items
.length
,
7526 showAll
= !this.isVisible(),
7529 if ( this.$input
&& this.filterFromInput
) {
7530 filter
= showAll
? null : this.getItemMatcher( this.$input
.val() );
7531 exactFilter
= this.getItemMatcher( this.$input
.val(), true );
7532 // Hide non-matching options, and also hide section headers if all options
7533 // in their section are hidden.
7534 for ( i
= 0; i
< len
; i
++ ) {
7535 item
= this.items
[ i
];
7536 if ( item
instanceof OO
.ui
.MenuSectionOptionWidget
) {
7538 // If the previous section was empty, hide its header
7539 section
.toggle( showAll
|| !sectionEmpty
);
7542 sectionEmpty
= true;
7543 } else if ( item
instanceof OO
.ui
.OptionWidget
) {
7544 visible
= showAll
|| filter( item
);
7545 exactMatch
= exactMatch
|| exactFilter( item
);
7546 anyVisible
= anyVisible
|| visible
;
7547 sectionEmpty
= sectionEmpty
&& !visible
;
7548 item
.toggle( visible
);
7551 // Process the final section
7553 section
.toggle( showAll
|| !sectionEmpty
);
7556 if ( anyVisible
&& this.items
.length
&& !exactMatch
) {
7557 this.scrollItemIntoView( this.items
[ 0 ] );
7560 this.$element
.toggleClass( 'oo-ui-menuSelectWidget-invisible', !anyVisible
);
7562 if ( this.highlightOnFilter
) {
7563 // Highlight the first item on the list
7565 items
= this.getItems();
7566 for ( i
= 0; i
< items
.length
; i
++ ) {
7567 if ( items
[ i
].isVisible() ) {
7572 this.highlightItem( item
);
7577 // Reevaluate clipping
7584 OO
.ui
.MenuSelectWidget
.prototype.bindDocumentKeyDownListener = function () {
7585 if ( this.$input
) {
7586 this.$input
.on( 'keydown', this.onDocumentKeyDownHandler
);
7588 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindDocumentKeyDownListener
.call( this );
7595 OO
.ui
.MenuSelectWidget
.prototype.unbindDocumentKeyDownListener = function () {
7596 if ( this.$input
) {
7597 this.$input
.off( 'keydown', this.onDocumentKeyDownHandler
);
7599 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindDocumentKeyDownListener
.call( this );
7606 OO
.ui
.MenuSelectWidget
.prototype.bindDocumentKeyPressListener = function () {
7607 if ( this.$input
) {
7608 if ( this.filterFromInput
) {
7609 this.$input
.on( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
7610 this.updateItemVisibility();
7613 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindDocumentKeyPressListener
.call( this );
7620 OO
.ui
.MenuSelectWidget
.prototype.unbindDocumentKeyPressListener = function () {
7621 if ( this.$input
) {
7622 if ( this.filterFromInput
) {
7623 this.$input
.off( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
7624 this.updateItemVisibility();
7627 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindDocumentKeyPressListener
.call( this );
7634 * When a user chooses an item, the menu is closed, unless the hideOnChoose config option is set to false.
7636 * Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard
7637 * or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.
7639 * @param {OO.ui.OptionWidget} item Item to choose
7642 OO
.ui
.MenuSelectWidget
.prototype.chooseItem = function ( item
) {
7643 OO
.ui
.MenuSelectWidget
.parent
.prototype.chooseItem
.call( this, item
);
7644 if ( this.hideOnChoose
) {
7645 this.toggle( false );
7653 OO
.ui
.MenuSelectWidget
.prototype.addItems = function ( items
, index
) {
7655 OO
.ui
.MenuSelectWidget
.parent
.prototype.addItems
.call( this, items
, index
);
7657 this.updateItemVisibility();
7665 OO
.ui
.MenuSelectWidget
.prototype.removeItems = function ( items
) {
7667 OO
.ui
.MenuSelectWidget
.parent
.prototype.removeItems
.call( this, items
);
7669 this.updateItemVisibility();
7677 OO
.ui
.MenuSelectWidget
.prototype.clearItems = function () {
7679 OO
.ui
.MenuSelectWidget
.parent
.prototype.clearItems
.call( this );
7681 this.updateItemVisibility();
7687 * Toggle visibility of the menu. The menu is initially hidden and must be shown by calling
7688 * `.toggle( true )` after its #$element is attached to the DOM.
7690 * Do not show the menu while it is not attached to the DOM. The calculations required to display
7691 * it in the right place and with the right dimensions only work correctly while it is attached.
7692 * Side-effects may include broken interface and exceptions being thrown. This wasn't always
7693 * strictly enforced, so currently it only generates a warning in the browser console.
7698 OO
.ui
.MenuSelectWidget
.prototype.toggle = function ( visible
) {
7699 var change
, originalHeight
, flippedHeight
;
7701 visible
= ( visible
=== undefined ? !this.visible
: !!visible
) && !!this.items
.length
;
7702 change
= visible
!== this.isVisible();
7704 if ( visible
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
7705 OO
.ui
.warnDeprecation( 'MenuSelectWidget#toggle: Before calling this method, the menu must be attached to the DOM.' );
7706 this.warnedUnattached
= true;
7709 if ( change
&& visible
) {
7710 // Reset position before showing the popup again. It's possible we no longer need to flip
7711 // (e.g. if the user scrolled).
7712 this.setVerticalPosition( this.originalVerticalPosition
);
7716 OO
.ui
.MenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
7722 this.setIdealSize( this.width
);
7723 } else if ( this.$floatableContainer
) {
7724 this.$clippable
.css( 'width', 'auto' );
7726 this.$floatableContainer
[ 0 ].offsetWidth
> this.$clippable
[ 0 ].offsetWidth
?
7727 // Dropdown is smaller than handle so expand to width
7728 this.$floatableContainer
[ 0 ].offsetWidth
:
7729 // Dropdown is larger than handle so auto size
7732 this.$clippable
.css( 'width', '' );
7735 this.togglePositioning( !!this.$floatableContainer
);
7736 this.toggleClipping( true );
7738 this.bindDocumentKeyDownListener();
7739 this.bindDocumentKeyPressListener();
7742 ( this.isClippedVertically() || this.isFloatableOutOfView() ) &&
7743 this.originalVerticalPosition
!== 'center'
7745 // If opening the menu in one direction causes it to be clipped, flip it
7746 originalHeight
= this.$element
.height();
7747 this.setVerticalPosition(
7748 this.constructor.static.flippedPositions
[ this.originalVerticalPosition
]
7750 if ( this.isClippedVertically() || this.isFloatableOutOfView() ) {
7751 // If flipping also causes it to be clipped, open in whichever direction
7752 // we have more space
7753 flippedHeight
= this.$element
.height();
7754 if ( originalHeight
> flippedHeight
) {
7755 this.setVerticalPosition( this.originalVerticalPosition
);
7759 // Note that we do not flip the menu's opening direction if the clipping changes
7760 // later (e.g. after the user scrolls), that seems like it would be annoying
7762 this.$focusOwner
.attr( 'aria-expanded', 'true' );
7764 if ( this.findSelectedItem() ) {
7765 this.$focusOwner
.attr( 'aria-activedescendant', this.findSelectedItem().getElementId() );
7766 this.findSelectedItem().scrollElementIntoView( { duration
: 0 } );
7770 if ( this.autoHide
) {
7771 this.getElementDocument().addEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
7774 this.emit( 'ready' );
7776 this.$focusOwner
.removeAttr( 'aria-activedescendant' );
7777 this.unbindDocumentKeyDownListener();
7778 this.unbindDocumentKeyPressListener();
7779 this.$focusOwner
.attr( 'aria-expanded', 'false' );
7780 this.getElementDocument().removeEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
7781 this.togglePositioning( false );
7782 this.toggleClipping( false );
7790 * DropdownWidgets are not menus themselves, rather they contain a menu of options created with
7791 * OO.ui.MenuOptionWidget. The DropdownWidget takes care of opening and displaying the menu so that
7792 * users can interact with it.
7794 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
7795 * OO.ui.DropdownInputWidget instead.
7798 * // Example: A DropdownWidget with a menu that contains three options
7799 * var dropDown = new OO.ui.DropdownWidget( {
7800 * label: 'Dropdown menu: Select a menu option',
7803 * new OO.ui.MenuOptionWidget( {
7807 * new OO.ui.MenuOptionWidget( {
7811 * new OO.ui.MenuOptionWidget( {
7819 * $( 'body' ).append( dropDown.$element );
7821 * dropDown.getMenu().selectItemByData( 'b' );
7823 * dropDown.getMenu().findSelectedItem().getData(); // returns 'b'
7825 * For more information, please see the [OOUI documentation on MediaWiki] [1].
7827 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options#Menu_selects_and_options
7830 * @extends OO.ui.Widget
7831 * @mixins OO.ui.mixin.IconElement
7832 * @mixins OO.ui.mixin.IndicatorElement
7833 * @mixins OO.ui.mixin.LabelElement
7834 * @mixins OO.ui.mixin.TitledElement
7835 * @mixins OO.ui.mixin.TabIndexedElement
7838 * @param {Object} [config] Configuration options
7839 * @cfg {Object} [menu] Configuration options to pass to {@link OO.ui.MenuSelectWidget menu select widget}
7840 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
7841 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
7842 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
7843 * See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
7845 OO
.ui
.DropdownWidget
= function OoUiDropdownWidget( config
) {
7846 // Configuration initialization
7847 config
= $.extend( { indicator
: 'down' }, config
);
7849 // Parent constructor
7850 OO
.ui
.DropdownWidget
.parent
.call( this, config
);
7852 // Properties (must be set before TabIndexedElement constructor call)
7853 this.$handle
= $( '<span>' );
7854 this.$overlay
= ( config
.$overlay
=== true ? OO
.ui
.getDefaultOverlay() : config
.$overlay
) || this.$element
;
7856 // Mixin constructors
7857 OO
.ui
.mixin
.IconElement
.call( this, config
);
7858 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7859 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7860 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
7861 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$handle
} ) );
7864 this.menu
= new OO
.ui
.MenuSelectWidget( $.extend( {
7866 $floatableContainer
: this.$element
7871 click
: this.onClick
.bind( this ),
7872 keydown
: this.onKeyDown
.bind( this ),
7873 // Hack? Handle type-to-search when menu is not expanded and not handling its own events
7874 keypress
: this.menu
.onKeyPressHandler
,
7875 blur
: this.menu
.clearKeyPressBuffer
.bind( this.menu
)
7877 this.menu
.connect( this, {
7878 select
: 'onMenuSelect',
7879 toggle
: 'onMenuToggle'
7884 .addClass( 'oo-ui-dropdownWidget-handle' )
7887 'aria-owns': this.menu
.getElementId(),
7888 'aria-autocomplete': 'list'
7890 .append( this.$icon
, this.$label
, this.$indicator
);
7892 .addClass( 'oo-ui-dropdownWidget' )
7893 .append( this.$handle
);
7894 this.$overlay
.append( this.menu
.$element
);
7899 OO
.inheritClass( OO
.ui
.DropdownWidget
, OO
.ui
.Widget
);
7900 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IconElement
);
7901 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IndicatorElement
);
7902 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.LabelElement
);
7903 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TitledElement
);
7904 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TabIndexedElement
);
7911 * @return {OO.ui.MenuSelectWidget} Menu of widget
7913 OO
.ui
.DropdownWidget
.prototype.getMenu = function () {
7918 * Handles menu select events.
7921 * @param {OO.ui.MenuOptionWidget} item Selected menu item
7923 OO
.ui
.DropdownWidget
.prototype.onMenuSelect = function ( item
) {
7927 this.setLabel( null );
7931 selectedLabel
= item
.getLabel();
7933 // If the label is a DOM element, clone it, because setLabel will append() it
7934 if ( selectedLabel
instanceof jQuery
) {
7935 selectedLabel
= selectedLabel
.clone();
7938 this.setLabel( selectedLabel
);
7942 * Handle menu toggle events.
7945 * @param {boolean} isVisible Open state of the menu
7947 OO
.ui
.DropdownWidget
.prototype.onMenuToggle = function ( isVisible
) {
7948 this.$element
.toggleClass( 'oo-ui-dropdownWidget-open', isVisible
);
7951 this.$element
.hasClass( 'oo-ui-dropdownWidget-open' ).toString()
7956 * Handle mouse click events.
7959 * @param {jQuery.Event} e Mouse click event
7961 OO
.ui
.DropdownWidget
.prototype.onClick = function ( e
) {
7962 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
7969 * Handle key down events.
7972 * @param {jQuery.Event} e Key down event
7974 OO
.ui
.DropdownWidget
.prototype.onKeyDown = function ( e
) {
7976 !this.isDisabled() &&
7978 e
.which
=== OO
.ui
.Keys
.ENTER
||
7980 e
.which
=== OO
.ui
.Keys
.SPACE
&&
7981 // Avoid conflicts with type-to-search, see SelectWidget#onKeyPress.
7982 // Space only closes the menu is the user is not typing to search.
7983 this.menu
.keyPressBuffer
=== ''
7986 !this.menu
.isVisible() &&
7988 e
.which
=== OO
.ui
.Keys
.UP
||
7989 e
.which
=== OO
.ui
.Keys
.DOWN
8000 * RadioOptionWidget is an option widget that looks like a radio button.
8001 * The class is used with OO.ui.RadioSelectWidget to create a selection of radio options.
8002 * Please see the [OOUI documentation on MediaWiki] [1] for more information.
8004 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options#Button_selects_and_option
8007 * @extends OO.ui.OptionWidget
8010 * @param {Object} [config] Configuration options
8012 OO
.ui
.RadioOptionWidget
= function OoUiRadioOptionWidget( config
) {
8013 // Configuration initialization
8014 config
= config
|| {};
8016 // Properties (must be done before parent constructor which calls #setDisabled)
8017 this.radio
= new OO
.ui
.RadioInputWidget( { value
: config
.data
, tabIndex
: -1 } );
8019 // Parent constructor
8020 OO
.ui
.RadioOptionWidget
.parent
.call( this, config
);
8023 // Remove implicit role, we're handling it ourselves
8024 this.radio
.$input
.attr( 'role', 'presentation' );
8026 .addClass( 'oo-ui-radioOptionWidget' )
8027 .attr( 'role', 'radio' )
8028 .attr( 'aria-checked', 'false' )
8029 .removeAttr( 'aria-selected' )
8030 .prepend( this.radio
.$element
);
8035 OO
.inheritClass( OO
.ui
.RadioOptionWidget
, OO
.ui
.OptionWidget
);
8037 /* Static Properties */
8043 OO
.ui
.RadioOptionWidget
.static.highlightable
= false;
8049 OO
.ui
.RadioOptionWidget
.static.scrollIntoViewOnSelect
= true;
8055 OO
.ui
.RadioOptionWidget
.static.pressable
= false;
8061 OO
.ui
.RadioOptionWidget
.static.tagName
= 'label';
8068 OO
.ui
.RadioOptionWidget
.prototype.setSelected = function ( state
) {
8069 OO
.ui
.RadioOptionWidget
.parent
.prototype.setSelected
.call( this, state
);
8071 this.radio
.setSelected( state
);
8073 .attr( 'aria-checked', state
.toString() )
8074 .removeAttr( 'aria-selected' );
8082 OO
.ui
.RadioOptionWidget
.prototype.setDisabled = function ( disabled
) {
8083 OO
.ui
.RadioOptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
8085 this.radio
.setDisabled( this.isDisabled() );
8091 * RadioSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains radio
8092 * options and is used together with OO.ui.RadioOptionWidget. The RadioSelectWidget provides
8093 * an interface for adding, removing and selecting options.
8094 * Please see the [OOUI documentation on MediaWiki][1] for more information.
8096 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
8097 * OO.ui.RadioSelectInputWidget instead.
8100 * // A RadioSelectWidget with RadioOptions.
8101 * var option1 = new OO.ui.RadioOptionWidget( {
8103 * label: 'Selected radio option'
8106 * var option2 = new OO.ui.RadioOptionWidget( {
8108 * label: 'Unselected radio option'
8111 * var radioSelect=new OO.ui.RadioSelectWidget( {
8112 * items: [ option1, option2 ]
8115 * // Select 'option 1' using the RadioSelectWidget's selectItem() method.
8116 * radioSelect.selectItem( option1 );
8118 * $( 'body' ).append( radioSelect.$element );
8120 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options
8124 * @extends OO.ui.SelectWidget
8125 * @mixins OO.ui.mixin.TabIndexedElement
8128 * @param {Object} [config] Configuration options
8130 OO
.ui
.RadioSelectWidget
= function OoUiRadioSelectWidget( config
) {
8131 // Parent constructor
8132 OO
.ui
.RadioSelectWidget
.parent
.call( this, config
);
8134 // Mixin constructors
8135 OO
.ui
.mixin
.TabIndexedElement
.call( this, config
);
8139 focus
: this.bindDocumentKeyDownListener
.bind( this ),
8140 blur
: this.unbindDocumentKeyDownListener
.bind( this )
8145 .addClass( 'oo-ui-radioSelectWidget' )
8146 .attr( 'role', 'radiogroup' );
8151 OO
.inheritClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.SelectWidget
);
8152 OO
.mixinClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.mixin
.TabIndexedElement
);
8155 * MultioptionWidgets are special elements that can be selected and configured with data. The
8156 * data is often unique for each option, but it does not have to be. MultioptionWidgets are used
8157 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
8158 * and examples, please see the [OOUI documentation on MediaWiki][1].
8160 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Multioptions
8163 * @extends OO.ui.Widget
8164 * @mixins OO.ui.mixin.ItemWidget
8165 * @mixins OO.ui.mixin.LabelElement
8168 * @param {Object} [config] Configuration options
8169 * @cfg {boolean} [selected=false] Whether the option is initially selected
8171 OO
.ui
.MultioptionWidget
= function OoUiMultioptionWidget( config
) {
8172 // Configuration initialization
8173 config
= config
|| {};
8175 // Parent constructor
8176 OO
.ui
.MultioptionWidget
.parent
.call( this, config
);
8178 // Mixin constructors
8179 OO
.ui
.mixin
.ItemWidget
.call( this );
8180 OO
.ui
.mixin
.LabelElement
.call( this, config
);
8183 this.selected
= null;
8187 .addClass( 'oo-ui-multioptionWidget' )
8188 .append( this.$label
);
8189 this.setSelected( config
.selected
);
8194 OO
.inheritClass( OO
.ui
.MultioptionWidget
, OO
.ui
.Widget
);
8195 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.ItemWidget
);
8196 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.LabelElement
);
8203 * A change event is emitted when the selected state of the option changes.
8205 * @param {boolean} selected Whether the option is now selected
8211 * Check if the option is selected.
8213 * @return {boolean} Item is selected
8215 OO
.ui
.MultioptionWidget
.prototype.isSelected = function () {
8216 return this.selected
;
8220 * Set the option’s selected state. In general, all modifications to the selection
8221 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
8222 * method instead of this method.
8224 * @param {boolean} [state=false] Select option
8227 OO
.ui
.MultioptionWidget
.prototype.setSelected = function ( state
) {
8229 if ( this.selected
!== state
) {
8230 this.selected
= state
;
8231 this.emit( 'change', state
);
8232 this.$element
.toggleClass( 'oo-ui-multioptionWidget-selected', state
);
8238 * MultiselectWidget allows selecting multiple options from a list.
8240 * For more information about menus and options, please see the [OOUI documentation on MediaWiki][1].
8242 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options#Menu_selects_and_options
8246 * @extends OO.ui.Widget
8247 * @mixins OO.ui.mixin.GroupWidget
8250 * @param {Object} [config] Configuration options
8251 * @cfg {OO.ui.MultioptionWidget[]} [items] An array of options to add to the multiselect.
8253 OO
.ui
.MultiselectWidget
= function OoUiMultiselectWidget( config
) {
8254 // Parent constructor
8255 OO
.ui
.MultiselectWidget
.parent
.call( this, config
);
8257 // Configuration initialization
8258 config
= config
|| {};
8260 // Mixin constructors
8261 OO
.ui
.mixin
.GroupWidget
.call( this, config
);
8264 this.aggregate( { change
: 'select' } );
8265 // This is mostly for compatibility with TagMultiselectWidget... normally, 'change' is emitted
8266 // by GroupElement only when items are added/removed
8267 this.connect( this, { select
: [ 'emit', 'change' ] } );
8270 if ( config
.items
) {
8271 this.addItems( config
.items
);
8273 this.$group
.addClass( 'oo-ui-multiselectWidget-group' );
8274 this.$element
.addClass( 'oo-ui-multiselectWidget' )
8275 .append( this.$group
);
8280 OO
.inheritClass( OO
.ui
.MultiselectWidget
, OO
.ui
.Widget
);
8281 OO
.mixinClass( OO
.ui
.MultiselectWidget
, OO
.ui
.mixin
.GroupWidget
);
8288 * A change event is emitted when the set of items changes, or an item is selected or deselected.
8294 * A select event is emitted when an item is selected or deselected.
8300 * Find options that are selected.
8302 * @return {OO.ui.MultioptionWidget[]} Selected options
8304 OO
.ui
.MultiselectWidget
.prototype.findSelectedItems = function () {
8305 return this.items
.filter( function ( item
) {
8306 return item
.isSelected();
8311 * Find the data of options that are selected.
8313 * @return {Object[]|string[]} Values of selected options
8315 OO
.ui
.MultiselectWidget
.prototype.findSelectedItemsData = function () {
8316 return this.findSelectedItems().map( function ( item
) {
8322 * Select options by reference. Options not mentioned in the `items` array will be deselected.
8324 * @param {OO.ui.MultioptionWidget[]} items Items to select
8327 OO
.ui
.MultiselectWidget
.prototype.selectItems = function ( items
) {
8328 this.items
.forEach( function ( item
) {
8329 var selected
= items
.indexOf( item
) !== -1;
8330 item
.setSelected( selected
);
8336 * Select items by their data. Options not mentioned in the `datas` array will be deselected.
8338 * @param {Object[]|string[]} datas Values of items to select
8341 OO
.ui
.MultiselectWidget
.prototype.selectItemsByData = function ( datas
) {
8344 items
= datas
.map( function ( data
) {
8345 return widget
.findItemFromData( data
);
8347 this.selectItems( items
);
8352 * CheckboxMultioptionWidget is an option widget that looks like a checkbox.
8353 * The class is used with OO.ui.CheckboxMultiselectWidget to create a selection of checkbox options.
8354 * Please see the [OOUI documentation on MediaWiki] [1] for more information.
8356 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options#Button_selects_and_option
8359 * @extends OO.ui.MultioptionWidget
8362 * @param {Object} [config] Configuration options
8364 OO
.ui
.CheckboxMultioptionWidget
= function OoUiCheckboxMultioptionWidget( config
) {
8365 // Configuration initialization
8366 config
= config
|| {};
8368 // Properties (must be done before parent constructor which calls #setDisabled)
8369 this.checkbox
= new OO
.ui
.CheckboxInputWidget();
8371 // Parent constructor
8372 OO
.ui
.CheckboxMultioptionWidget
.parent
.call( this, config
);
8375 this.checkbox
.on( 'change', this.onCheckboxChange
.bind( this ) );
8376 this.$element
.on( 'keydown', this.onKeyDown
.bind( this ) );
8380 .addClass( 'oo-ui-checkboxMultioptionWidget' )
8381 .prepend( this.checkbox
.$element
);
8386 OO
.inheritClass( OO
.ui
.CheckboxMultioptionWidget
, OO
.ui
.MultioptionWidget
);
8388 /* Static Properties */
8394 OO
.ui
.CheckboxMultioptionWidget
.static.tagName
= 'label';
8399 * Handle checkbox selected state change.
8403 OO
.ui
.CheckboxMultioptionWidget
.prototype.onCheckboxChange = function () {
8404 this.setSelected( this.checkbox
.isSelected() );
8410 OO
.ui
.CheckboxMultioptionWidget
.prototype.setSelected = function ( state
) {
8411 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setSelected
.call( this, state
);
8412 this.checkbox
.setSelected( state
);
8419 OO
.ui
.CheckboxMultioptionWidget
.prototype.setDisabled = function ( disabled
) {
8420 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
8421 this.checkbox
.setDisabled( this.isDisabled() );
8428 OO
.ui
.CheckboxMultioptionWidget
.prototype.focus = function () {
8429 this.checkbox
.focus();
8433 * Handle key down events.
8436 * @param {jQuery.Event} e
8438 OO
.ui
.CheckboxMultioptionWidget
.prototype.onKeyDown = function ( e
) {
8440 element
= this.getElementGroup(),
8443 if ( e
.keyCode
=== OO
.ui
.Keys
.LEFT
|| e
.keyCode
=== OO
.ui
.Keys
.UP
) {
8444 nextItem
= element
.getRelativeFocusableItem( this, -1 );
8445 } else if ( e
.keyCode
=== OO
.ui
.Keys
.RIGHT
|| e
.keyCode
=== OO
.ui
.Keys
.DOWN
) {
8446 nextItem
= element
.getRelativeFocusableItem( this, 1 );
8456 * CheckboxMultiselectWidget is a {@link OO.ui.MultiselectWidget multiselect widget} that contains
8457 * checkboxes and is used together with OO.ui.CheckboxMultioptionWidget. The
8458 * CheckboxMultiselectWidget provides an interface for adding, removing and selecting options.
8459 * Please see the [OOUI documentation on MediaWiki][1] for more information.
8461 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
8462 * OO.ui.CheckboxMultiselectInputWidget instead.
8465 * // A CheckboxMultiselectWidget with CheckboxMultioptions.
8466 * var option1 = new OO.ui.CheckboxMultioptionWidget( {
8469 * label: 'Selected checkbox'
8472 * var option2 = new OO.ui.CheckboxMultioptionWidget( {
8474 * label: 'Unselected checkbox'
8477 * var multiselect=new OO.ui.CheckboxMultiselectWidget( {
8478 * items: [ option1, option2 ]
8481 * $( 'body' ).append( multiselect.$element );
8483 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options
8486 * @extends OO.ui.MultiselectWidget
8489 * @param {Object} [config] Configuration options
8491 OO
.ui
.CheckboxMultiselectWidget
= function OoUiCheckboxMultiselectWidget( config
) {
8492 // Parent constructor
8493 OO
.ui
.CheckboxMultiselectWidget
.parent
.call( this, config
);
8496 this.$lastClicked
= null;
8499 this.$group
.on( 'click', this.onClick
.bind( this ) );
8503 .addClass( 'oo-ui-checkboxMultiselectWidget' );
8508 OO
.inheritClass( OO
.ui
.CheckboxMultiselectWidget
, OO
.ui
.MultiselectWidget
);
8513 * Get an option by its position relative to the specified item (or to the start of the option array,
8514 * if item is `null`). The direction in which to search through the option array is specified with a
8515 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
8516 * `null` if there are no options in the array.
8518 * @param {OO.ui.CheckboxMultioptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
8519 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
8520 * @return {OO.ui.CheckboxMultioptionWidget|null} Item at position, `null` if there are no items in the select
8522 OO
.ui
.CheckboxMultiselectWidget
.prototype.getRelativeFocusableItem = function ( item
, direction
) {
8523 var currentIndex
, nextIndex
, i
,
8524 increase
= direction
> 0 ? 1 : -1,
8525 len
= this.items
.length
;
8528 currentIndex
= this.items
.indexOf( item
);
8529 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
8531 // If no item is selected and moving forward, start at the beginning.
8532 // If moving backward, start at the end.
8533 nextIndex
= direction
> 0 ? 0 : len
- 1;
8536 for ( i
= 0; i
< len
; i
++ ) {
8537 item
= this.items
[ nextIndex
];
8538 if ( item
&& !item
.isDisabled() ) {
8541 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
8547 * Handle click events on checkboxes.
8549 * @param {jQuery.Event} e
8551 OO
.ui
.CheckboxMultiselectWidget
.prototype.onClick = function ( e
) {
8552 var $options
, lastClickedIndex
, nowClickedIndex
, i
, direction
, wasSelected
, items
,
8553 $lastClicked
= this.$lastClicked
,
8554 $nowClicked
= $( e
.target
).closest( '.oo-ui-checkboxMultioptionWidget' )
8555 .not( '.oo-ui-widget-disabled' );
8557 // Allow selecting multiple options at once by Shift-clicking them
8558 if ( $lastClicked
&& $nowClicked
.length
&& e
.shiftKey
) {
8559 $options
= this.$group
.find( '.oo-ui-checkboxMultioptionWidget' );
8560 lastClickedIndex
= $options
.index( $lastClicked
);
8561 nowClickedIndex
= $options
.index( $nowClicked
);
8562 // If it's the same item, either the user is being silly, or it's a fake event generated by the
8563 // browser. In either case we don't need custom handling.
8564 if ( nowClickedIndex
!== lastClickedIndex
) {
8566 wasSelected
= items
[ nowClickedIndex
].isSelected();
8567 direction
= nowClickedIndex
> lastClickedIndex
? 1 : -1;
8569 // This depends on the DOM order of the items and the order of the .items array being the same.
8570 for ( i
= lastClickedIndex
; i
!== nowClickedIndex
; i
+= direction
) {
8571 if ( !items
[ i
].isDisabled() ) {
8572 items
[ i
].setSelected( !wasSelected
);
8575 // For the now-clicked element, use immediate timeout to allow the browser to do its own
8576 // handling first, then set our value. The order in which events happen is different for
8577 // clicks on the <input> and on the <label> and there are additional fake clicks fired for
8578 // non-click actions that change the checkboxes.
8580 setTimeout( function () {
8581 if ( !items
[ nowClickedIndex
].isDisabled() ) {
8582 items
[ nowClickedIndex
].setSelected( !wasSelected
);
8588 if ( $nowClicked
.length
) {
8589 this.$lastClicked
= $nowClicked
;
8598 OO
.ui
.CheckboxMultiselectWidget
.prototype.focus = function () {
8600 if ( !this.isDisabled() ) {
8601 item
= this.getRelativeFocusableItem( null, 1 );
8612 OO
.ui
.CheckboxMultiselectWidget
.prototype.simulateLabelClick = function () {
8617 * Progress bars visually display the status of an operation, such as a download,
8618 * and can be either determinate or indeterminate:
8620 * - **determinate** process bars show the percent of an operation that is complete.
8622 * - **indeterminate** process bars use a visual display of motion to indicate that an operation
8623 * is taking place. Because the extent of an indeterminate operation is unknown, the bar does
8624 * not use percentages.
8626 * The value of the `progress` configuration determines whether the bar is determinate or indeterminate.
8629 * // Examples of determinate and indeterminate progress bars.
8630 * var progressBar1 = new OO.ui.ProgressBarWidget( {
8633 * var progressBar2 = new OO.ui.ProgressBarWidget();
8635 * // Create a FieldsetLayout to layout progress bars
8636 * var fieldset = new OO.ui.FieldsetLayout;
8637 * fieldset.addItems( [
8638 * new OO.ui.FieldLayout( progressBar1, {label: 'Determinate', align: 'top'}),
8639 * new OO.ui.FieldLayout( progressBar2, {label: 'Indeterminate', align: 'top'})
8641 * $( 'body' ).append( fieldset.$element );
8644 * @extends OO.ui.Widget
8647 * @param {Object} [config] Configuration options
8648 * @cfg {number|boolean} [progress=false] The type of progress bar (determinate or indeterminate).
8649 * To create a determinate progress bar, specify a number that reflects the initial percent complete.
8650 * By default, the progress bar is indeterminate.
8652 OO
.ui
.ProgressBarWidget
= function OoUiProgressBarWidget( config
) {
8653 // Configuration initialization
8654 config
= config
|| {};
8656 // Parent constructor
8657 OO
.ui
.ProgressBarWidget
.parent
.call( this, config
);
8660 this.$bar
= $( '<div>' );
8661 this.progress
= null;
8664 this.setProgress( config
.progress
!== undefined ? config
.progress
: false );
8665 this.$bar
.addClass( 'oo-ui-progressBarWidget-bar' );
8668 role
: 'progressbar',
8670 'aria-valuemax': 100
8672 .addClass( 'oo-ui-progressBarWidget' )
8673 .append( this.$bar
);
8678 OO
.inheritClass( OO
.ui
.ProgressBarWidget
, OO
.ui
.Widget
);
8680 /* Static Properties */
8686 OO
.ui
.ProgressBarWidget
.static.tagName
= 'div';
8691 * Get the percent of the progress that has been completed. Indeterminate progresses will return `false`.
8693 * @return {number|boolean} Progress percent
8695 OO
.ui
.ProgressBarWidget
.prototype.getProgress = function () {
8696 return this.progress
;
8700 * Set the percent of the process completed or `false` for an indeterminate process.
8702 * @param {number|boolean} progress Progress percent or `false` for indeterminate
8704 OO
.ui
.ProgressBarWidget
.prototype.setProgress = function ( progress
) {
8705 this.progress
= progress
;
8707 if ( progress
!== false ) {
8708 this.$bar
.css( 'width', this.progress
+ '%' );
8709 this.$element
.attr( 'aria-valuenow', this.progress
);
8711 this.$bar
.css( 'width', '' );
8712 this.$element
.removeAttr( 'aria-valuenow' );
8714 this.$element
.toggleClass( 'oo-ui-progressBarWidget-indeterminate', progress
=== false );
8718 * InputWidget is the base class for all input widgets, which
8719 * include {@link OO.ui.TextInputWidget text inputs}, {@link OO.ui.CheckboxInputWidget checkbox inputs},
8720 * {@link OO.ui.RadioInputWidget radio inputs}, and {@link OO.ui.ButtonInputWidget button inputs}.
8721 * See the [OOUI documentation on MediaWiki] [1] for more information and examples.
8723 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs
8727 * @extends OO.ui.Widget
8728 * @mixins OO.ui.mixin.FlaggedElement
8729 * @mixins OO.ui.mixin.TabIndexedElement
8730 * @mixins OO.ui.mixin.TitledElement
8731 * @mixins OO.ui.mixin.AccessKeyedElement
8734 * @param {Object} [config] Configuration options
8735 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
8736 * @cfg {string} [value=''] The value of the input.
8737 * @cfg {string} [dir] The directionality of the input (ltr/rtl).
8738 * @cfg {string} [inputId] The value of the input’s HTML `id` attribute.
8739 * @cfg {Function} [inputFilter] The name of an input filter function. Input filters modify the value of an input
8740 * before it is accepted.
8742 OO
.ui
.InputWidget
= function OoUiInputWidget( config
) {
8743 // Configuration initialization
8744 config
= config
|| {};
8746 // Parent constructor
8747 OO
.ui
.InputWidget
.parent
.call( this, config
);
8750 // See #reusePreInfuseDOM about config.$input
8751 this.$input
= config
.$input
|| this.getInputElement( config
);
8753 this.inputFilter
= config
.inputFilter
;
8755 // Mixin constructors
8756 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
8757 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$input
} ) );
8758 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
8759 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$input
} ) );
8762 this.$input
.on( 'keydown mouseup cut paste change input select', this.onEdit
.bind( this ) );
8766 .addClass( 'oo-ui-inputWidget-input' )
8767 .attr( 'name', config
.name
)
8768 .prop( 'disabled', this.isDisabled() );
8770 .addClass( 'oo-ui-inputWidget' )
8771 .append( this.$input
);
8772 this.setValue( config
.value
);
8774 this.setDir( config
.dir
);
8776 if ( config
.inputId
!== undefined ) {
8777 this.setInputId( config
.inputId
);
8783 OO
.inheritClass( OO
.ui
.InputWidget
, OO
.ui
.Widget
);
8784 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.FlaggedElement
);
8785 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TabIndexedElement
);
8786 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TitledElement
);
8787 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
8789 /* Static Methods */
8794 OO
.ui
.InputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
8795 config
= OO
.ui
.InputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
8796 // Reusing `$input` lets browsers preserve inputted values across page reloads, see T114134.
8797 config
.$input
= $( node
).find( '.oo-ui-inputWidget-input' );
8804 OO
.ui
.InputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8805 var state
= OO
.ui
.InputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8806 if ( config
.$input
&& config
.$input
.length
) {
8807 state
.value
= config
.$input
.val();
8808 // Might be better in TabIndexedElement, but it's awkward to do there because mixins are awkward
8809 state
.focus
= config
.$input
.is( ':focus' );
8819 * A change event is emitted when the value of the input changes.
8821 * @param {string} value
8827 * Get input element.
8829 * Subclasses of OO.ui.InputWidget use the `config` parameter to produce different elements in
8830 * different circumstances. The element must have a `value` property (like form elements).
8833 * @param {Object} config Configuration options
8834 * @return {jQuery} Input element
8836 OO
.ui
.InputWidget
.prototype.getInputElement = function () {
8837 return $( '<input>' );
8841 * Handle potentially value-changing events.
8844 * @param {jQuery.Event} e Key down, mouse up, cut, paste, change, input, or select event
8846 OO
.ui
.InputWidget
.prototype.onEdit = function () {
8848 if ( !this.isDisabled() ) {
8849 // Allow the stack to clear so the value will be updated
8850 setTimeout( function () {
8851 widget
.setValue( widget
.$input
.val() );
8857 * Get the value of the input.
8859 * @return {string} Input value
8861 OO
.ui
.InputWidget
.prototype.getValue = function () {
8862 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
8863 // it, and we won't know unless they're kind enough to trigger a 'change' event.
8864 var value
= this.$input
.val();
8865 if ( this.value
!== value
) {
8866 this.setValue( value
);
8872 * Set the directionality of the input.
8874 * @param {string} dir Text directionality: 'ltr', 'rtl' or 'auto'
8877 OO
.ui
.InputWidget
.prototype.setDir = function ( dir
) {
8878 this.$input
.prop( 'dir', dir
);
8883 * Set the value of the input.
8885 * @param {string} value New value
8889 OO
.ui
.InputWidget
.prototype.setValue = function ( value
) {
8890 value
= this.cleanUpValue( value
);
8891 // Update the DOM if it has changed. Note that with cleanUpValue, it
8892 // is possible for the DOM value to change without this.value changing.
8893 if ( this.$input
.val() !== value
) {
8894 this.$input
.val( value
);
8896 if ( this.value
!== value
) {
8898 this.emit( 'change', this.value
);
8900 // The first time that the value is set (probably while constructing the widget),
8901 // remember it in defaultValue. This property can be later used to check whether
8902 // the value of the input has been changed since it was created.
8903 if ( this.defaultValue
=== undefined ) {
8904 this.defaultValue
= this.value
;
8905 this.$input
[ 0 ].defaultValue
= this.defaultValue
;
8911 * Clean up incoming value.
8913 * Ensures value is a string, and converts undefined and null to empty string.
8916 * @param {string} value Original value
8917 * @return {string} Cleaned up value
8919 OO
.ui
.InputWidget
.prototype.cleanUpValue = function ( value
) {
8920 if ( value
=== undefined || value
=== null ) {
8922 } else if ( this.inputFilter
) {
8923 return this.inputFilter( String( value
) );
8925 return String( value
);
8932 OO
.ui
.InputWidget
.prototype.setDisabled = function ( state
) {
8933 OO
.ui
.InputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8934 if ( this.$input
) {
8935 this.$input
.prop( 'disabled', this.isDisabled() );
8941 * Set the 'id' attribute of the `<input>` element.
8943 * @param {string} id
8946 OO
.ui
.InputWidget
.prototype.setInputId = function ( id
) {
8947 this.$input
.attr( 'id', id
);
8954 OO
.ui
.InputWidget
.prototype.restorePreInfuseState = function ( state
) {
8955 OO
.ui
.InputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8956 if ( state
.value
!== undefined && state
.value
!== this.getValue() ) {
8957 this.setValue( state
.value
);
8959 if ( state
.focus
) {
8965 * Data widget intended for creating 'hidden'-type inputs.
8968 * @extends OO.ui.Widget
8971 * @param {Object} [config] Configuration options
8972 * @cfg {string} [value=''] The value of the input.
8973 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
8975 OO
.ui
.HiddenInputWidget
= function OoUiHiddenInputWidget( config
) {
8976 // Configuration initialization
8977 config
= $.extend( { value
: '', name
: '' }, config
);
8979 // Parent constructor
8980 OO
.ui
.HiddenInputWidget
.parent
.call( this, config
);
8983 this.$element
.attr( {
8985 value
: config
.value
,
8988 this.$element
.removeAttr( 'aria-disabled' );
8993 OO
.inheritClass( OO
.ui
.HiddenInputWidget
, OO
.ui
.Widget
);
8995 /* Static Properties */
9001 OO
.ui
.HiddenInputWidget
.static.tagName
= 'input';
9004 * ButtonInputWidget is used to submit HTML forms and is intended to be used within
9005 * a OO.ui.FormLayout. If you do not need the button to work with HTML forms, you probably
9006 * want to use OO.ui.ButtonWidget instead. Button input widgets can be rendered as either an
9007 * HTML `<button>` (the default) or an HTML `<input>` tags. See the
9008 * [OOUI documentation on MediaWiki] [1] for more information.
9011 * // A ButtonInputWidget rendered as an HTML button, the default.
9012 * var button = new OO.ui.ButtonInputWidget( {
9013 * label: 'Input button',
9017 * $( 'body' ).append( button.$element );
9019 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs#Button_inputs
9022 * @extends OO.ui.InputWidget
9023 * @mixins OO.ui.mixin.ButtonElement
9024 * @mixins OO.ui.mixin.IconElement
9025 * @mixins OO.ui.mixin.IndicatorElement
9026 * @mixins OO.ui.mixin.LabelElement
9027 * @mixins OO.ui.mixin.TitledElement
9030 * @param {Object} [config] Configuration options
9031 * @cfg {string} [type='button'] The value of the HTML `'type'` attribute: 'button', 'submit' or 'reset'.
9032 * @cfg {boolean} [useInputTag=false] Use an `<input>` tag instead of a `<button>` tag, the default.
9033 * Widgets configured to be an `<input>` do not support {@link #icon icons} and {@link #indicator indicators},
9034 * non-plaintext {@link #label labels}, or {@link #value values}. In general, useInputTag should only
9035 * be set to `true` when there’s need to support IE 6 in a form with multiple buttons.
9037 OO
.ui
.ButtonInputWidget
= function OoUiButtonInputWidget( config
) {
9038 // Configuration initialization
9039 config
= $.extend( { type
: 'button', useInputTag
: false }, config
);
9041 // See InputWidget#reusePreInfuseDOM about config.$input
9042 if ( config
.$input
) {
9043 config
.$input
.empty();
9046 // Properties (must be set before parent constructor, which calls #setValue)
9047 this.useInputTag
= config
.useInputTag
;
9049 // Parent constructor
9050 OO
.ui
.ButtonInputWidget
.parent
.call( this, config
);
9052 // Mixin constructors
9053 OO
.ui
.mixin
.ButtonElement
.call( this, $.extend( {}, config
, { $button
: this.$input
} ) );
9054 OO
.ui
.mixin
.IconElement
.call( this, config
);
9055 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
9056 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9057 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
9060 if ( !config
.useInputTag
) {
9061 this.$input
.append( this.$icon
, this.$label
, this.$indicator
);
9063 this.$element
.addClass( 'oo-ui-buttonInputWidget' );
9068 OO
.inheritClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.InputWidget
);
9069 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.ButtonElement
);
9070 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IconElement
);
9071 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
9072 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.LabelElement
);
9073 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.TitledElement
);
9075 /* Static Properties */
9081 OO
.ui
.ButtonInputWidget
.static.tagName
= 'span';
9089 OO
.ui
.ButtonInputWidget
.prototype.getInputElement = function ( config
) {
9091 type
= [ 'button', 'submit', 'reset' ].indexOf( config
.type
) !== -1 ? config
.type
: 'button';
9092 return $( '<' + ( config
.useInputTag
? 'input' : 'button' ) + ' type="' + type
+ '">' );
9098 * If #useInputTag is `true`, the label is set as the `value` of the `<input>` tag.
9100 * @param {jQuery|string|Function|null} label Label nodes, text, a function that returns nodes or
9101 * text, or `null` for no label
9104 OO
.ui
.ButtonInputWidget
.prototype.setLabel = function ( label
) {
9105 if ( typeof label
=== 'function' ) {
9106 label
= OO
.ui
.resolveMsg( label
);
9109 if ( this.useInputTag
) {
9110 // Discard non-plaintext labels
9111 if ( typeof label
!== 'string' ) {
9115 this.$input
.val( label
);
9118 return OO
.ui
.mixin
.LabelElement
.prototype.setLabel
.call( this, label
);
9122 * Set the value of the input.
9124 * This method is disabled for button inputs configured as {@link #useInputTag <input> tags}, as
9125 * they do not support {@link #value values}.
9127 * @param {string} value New value
9130 OO
.ui
.ButtonInputWidget
.prototype.setValue = function ( value
) {
9131 if ( !this.useInputTag
) {
9132 OO
.ui
.ButtonInputWidget
.parent
.prototype.setValue
.call( this, value
);
9140 OO
.ui
.ButtonInputWidget
.prototype.getInputId = function () {
9141 // Disable generating `<label>` elements for buttons. One would very rarely need additional label
9142 // for a button, and it's already a big clickable target, and it causes unexpected rendering.
9147 * CheckboxInputWidgets, like HTML checkboxes, can be selected and/or configured with a value.
9148 * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
9149 * in {@link OO.ui.FieldLayout field layouts} that use the {@link OO.ui.FieldLayout#align inline}
9150 * alignment. For more information, please see the [OOUI documentation on MediaWiki][1].
9152 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
9155 * // An example of selected, unselected, and disabled checkbox inputs
9156 * var checkbox1=new OO.ui.CheckboxInputWidget( {
9160 * var checkbox2=new OO.ui.CheckboxInputWidget( {
9163 * var checkbox3=new OO.ui.CheckboxInputWidget( {
9167 * // Create a fieldset layout with fields for each checkbox.
9168 * var fieldset = new OO.ui.FieldsetLayout( {
9169 * label: 'Checkboxes'
9171 * fieldset.addItems( [
9172 * new OO.ui.FieldLayout( checkbox1, { label: 'Selected checkbox', align: 'inline' } ),
9173 * new OO.ui.FieldLayout( checkbox2, { label: 'Unselected checkbox', align: 'inline' } ),
9174 * new OO.ui.FieldLayout( checkbox3, { label: 'Disabled checkbox', align: 'inline' } ),
9176 * $( 'body' ).append( fieldset.$element );
9178 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs
9181 * @extends OO.ui.InputWidget
9184 * @param {Object} [config] Configuration options
9185 * @cfg {boolean} [selected=false] Select the checkbox initially. By default, the checkbox is not selected.
9187 OO
.ui
.CheckboxInputWidget
= function OoUiCheckboxInputWidget( config
) {
9188 // Configuration initialization
9189 config
= config
|| {};
9191 // Parent constructor
9192 OO
.ui
.CheckboxInputWidget
.parent
.call( this, config
);
9195 this.checkIcon
= new OO
.ui
.IconWidget( {
9197 classes
: [ 'oo-ui-checkboxInputWidget-checkIcon' ]
9202 .addClass( 'oo-ui-checkboxInputWidget' )
9203 // Required for pretty styling in WikimediaUI theme
9204 .append( this.checkIcon
.$element
);
9205 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
9210 OO
.inheritClass( OO
.ui
.CheckboxInputWidget
, OO
.ui
.InputWidget
);
9212 /* Static Properties */
9218 OO
.ui
.CheckboxInputWidget
.static.tagName
= 'span';
9220 /* Static Methods */
9225 OO
.ui
.CheckboxInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9226 var state
= OO
.ui
.CheckboxInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9227 state
.checked
= config
.$input
.prop( 'checked' );
9237 OO
.ui
.CheckboxInputWidget
.prototype.getInputElement = function () {
9238 return $( '<input>' ).attr( 'type', 'checkbox' );
9244 OO
.ui
.CheckboxInputWidget
.prototype.onEdit = function () {
9246 if ( !this.isDisabled() ) {
9247 // Allow the stack to clear so the value will be updated
9248 setTimeout( function () {
9249 widget
.setSelected( widget
.$input
.prop( 'checked' ) );
9255 * Set selection state of this checkbox.
9257 * @param {boolean} state `true` for selected
9260 OO
.ui
.CheckboxInputWidget
.prototype.setSelected = function ( state
) {
9262 if ( this.selected
!== state
) {
9263 this.selected
= state
;
9264 this.$input
.prop( 'checked', this.selected
);
9265 this.emit( 'change', this.selected
);
9267 // The first time that the selection state is set (probably while constructing the widget),
9268 // remember it in defaultSelected. This property can be later used to check whether
9269 // the selection state of the input has been changed since it was created.
9270 if ( this.defaultSelected
=== undefined ) {
9271 this.defaultSelected
= this.selected
;
9272 this.$input
[ 0 ].defaultChecked
= this.defaultSelected
;
9278 * Check if this checkbox is selected.
9280 * @return {boolean} Checkbox is selected
9282 OO
.ui
.CheckboxInputWidget
.prototype.isSelected = function () {
9283 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
9284 // it, and we won't know unless they're kind enough to trigger a 'change' event.
9285 var selected
= this.$input
.prop( 'checked' );
9286 if ( this.selected
!== selected
) {
9287 this.setSelected( selected
);
9289 return this.selected
;
9295 OO
.ui
.CheckboxInputWidget
.prototype.simulateLabelClick = function () {
9296 if ( !this.isDisabled() ) {
9297 this.$input
.click();
9305 OO
.ui
.CheckboxInputWidget
.prototype.restorePreInfuseState = function ( state
) {
9306 OO
.ui
.CheckboxInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
9307 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
9308 this.setSelected( state
.checked
);
9313 * DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget} intended to be used
9314 * within an HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
9315 * of a hidden HTML `input` tag. Please see the [OOUI documentation on MediaWiki][1] for
9316 * more information about input widgets.
9318 * A DropdownInputWidget always has a value (one of the options is always selected), unless there
9319 * are no options. If no `value` configuration option is provided, the first option is selected.
9320 * If you need a state representing no value (no option being selected), use a DropdownWidget.
9322 * This and OO.ui.RadioSelectInputWidget support the same configuration options.
9325 * // Example: A DropdownInputWidget with three options
9326 * var dropdownInput = new OO.ui.DropdownInputWidget( {
9328 * { data: 'a', label: 'First' },
9329 * { data: 'b', label: 'Second'},
9330 * { data: 'c', label: 'Third' }
9333 * $( 'body' ).append( dropdownInput.$element );
9335 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs
9338 * @extends OO.ui.InputWidget
9341 * @param {Object} [config] Configuration options
9342 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
9343 * @cfg {Object} [dropdown] Configuration options for {@link OO.ui.DropdownWidget DropdownWidget}
9344 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
9345 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
9346 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
9347 * See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
9349 OO
.ui
.DropdownInputWidget
= function OoUiDropdownInputWidget( config
) {
9350 // Configuration initialization
9351 config
= config
|| {};
9353 // Properties (must be done before parent constructor which calls #setDisabled)
9354 this.dropdownWidget
= new OO
.ui
.DropdownWidget( $.extend(
9356 $overlay
: config
.$overlay
9360 // Set up the options before parent constructor, which uses them to validate config.value.
9361 // Use this instead of setOptions() because this.$input is not set up yet.
9362 this.setOptionsData( config
.options
|| [] );
9364 // Parent constructor
9365 OO
.ui
.DropdownInputWidget
.parent
.call( this, config
);
9368 this.dropdownWidget
.getMenu().connect( this, { select
: 'onMenuSelect' } );
9372 .addClass( 'oo-ui-dropdownInputWidget' )
9373 .append( this.dropdownWidget
.$element
);
9374 this.setTabIndexedElement( this.dropdownWidget
.$tabIndexed
);
9379 OO
.inheritClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.InputWidget
);
9387 OO
.ui
.DropdownInputWidget
.prototype.getInputElement = function () {
9388 return $( '<select>' );
9392 * Handles menu select events.
9395 * @param {OO.ui.MenuOptionWidget|null} item Selected menu item
9397 OO
.ui
.DropdownInputWidget
.prototype.onMenuSelect = function ( item
) {
9398 this.setValue( item
? item
.getData() : '' );
9404 OO
.ui
.DropdownInputWidget
.prototype.setValue = function ( value
) {
9406 value
= this.cleanUpValue( value
);
9407 // Only allow setting values that are actually present in the dropdown
9408 selected
= this.dropdownWidget
.getMenu().findItemFromData( value
) ||
9409 this.dropdownWidget
.getMenu().findFirstSelectableItem();
9410 this.dropdownWidget
.getMenu().selectItem( selected
);
9411 value
= selected
? selected
.getData() : '';
9412 OO
.ui
.DropdownInputWidget
.parent
.prototype.setValue
.call( this, value
);
9413 if ( this.optionsDirty
) {
9414 // We reached this from the constructor or from #setOptions.
9415 // We have to update the <select> element.
9416 this.updateOptionsInterface();
9424 OO
.ui
.DropdownInputWidget
.prototype.setDisabled = function ( state
) {
9425 this.dropdownWidget
.setDisabled( state
);
9426 OO
.ui
.DropdownInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
9431 * Set the options available for this input.
9433 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9436 OO
.ui
.DropdownInputWidget
.prototype.setOptions = function ( options
) {
9437 var value
= this.getValue();
9439 this.setOptionsData( options
);
9441 // Re-set the value to update the visible interface (DropdownWidget and <select>).
9442 // In case the previous value is no longer an available option, select the first valid one.
9443 this.setValue( value
);
9449 * Set the internal list of options, used e.g. by setValue() to see which options are allowed.
9451 * This method may be called before the parent constructor, so various properties may not be
9454 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9457 OO
.ui
.DropdownInputWidget
.prototype.setOptionsData = function ( options
) {
9462 this.optionsDirty
= true;
9464 optionWidgets
= options
.map( function ( opt
) {
9467 if ( opt
.optgroup
!== undefined ) {
9468 return widget
.createMenuSectionOptionWidget( opt
.optgroup
);
9471 optValue
= widget
.cleanUpValue( opt
.data
);
9472 return widget
.createMenuOptionWidget(
9474 opt
.label
!== undefined ? opt
.label
: optValue
9479 this.dropdownWidget
.getMenu().clearItems().addItems( optionWidgets
);
9483 * Create a menu option widget.
9486 * @param {string} data Item data
9487 * @param {string} label Item label
9488 * @return {OO.ui.MenuOptionWidget} Option widget
9490 OO
.ui
.DropdownInputWidget
.prototype.createMenuOptionWidget = function ( data
, label
) {
9491 return new OO
.ui
.MenuOptionWidget( {
9498 * Create a menu section option widget.
9501 * @param {string} label Section item label
9502 * @return {OO.ui.MenuSectionOptionWidget} Menu section option widget
9504 OO
.ui
.DropdownInputWidget
.prototype.createMenuSectionOptionWidget = function ( label
) {
9505 return new OO
.ui
.MenuSectionOptionWidget( {
9511 * Update the user-visible interface to match the internal list of options and value.
9513 * This method must only be called after the parent constructor.
9517 OO
.ui
.DropdownInputWidget
.prototype.updateOptionsInterface = function () {
9519 $optionsContainer
= this.$input
,
9520 defaultValue
= this.defaultValue
,
9523 this.$input
.empty();
9525 this.dropdownWidget
.getMenu().getItems().forEach( function ( optionWidget
) {
9528 if ( !( optionWidget
instanceof OO
.ui
.MenuSectionOptionWidget
) ) {
9529 $optionNode
= $( '<option>' )
9530 .attr( 'value', optionWidget
.getData() )
9531 .text( optionWidget
.getLabel() );
9533 // Remember original selection state. This property can be later used to check whether
9534 // the selection state of the input has been changed since it was created.
9535 $optionNode
[ 0 ].defaultSelected
= ( optionWidget
.getData() === defaultValue
);
9537 $optionsContainer
.append( $optionNode
);
9539 $optionNode
= $( '<optgroup>' )
9540 .attr( 'label', optionWidget
.getLabel() );
9541 widget
.$input
.append( $optionNode
);
9542 $optionsContainer
= $optionNode
;
9546 this.optionsDirty
= false;
9552 OO
.ui
.DropdownInputWidget
.prototype.focus = function () {
9553 this.dropdownWidget
.focus();
9560 OO
.ui
.DropdownInputWidget
.prototype.blur = function () {
9561 this.dropdownWidget
.blur();
9566 * RadioInputWidget creates a single radio button. Because radio buttons are usually used as a set,
9567 * in most cases you will want to use a {@link OO.ui.RadioSelectWidget radio select}
9568 * with {@link OO.ui.RadioOptionWidget radio options} instead of this class. For more information,
9569 * please see the [OOUI documentation on MediaWiki][1].
9571 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
9574 * // An example of selected, unselected, and disabled radio inputs
9575 * var radio1 = new OO.ui.RadioInputWidget( {
9579 * var radio2 = new OO.ui.RadioInputWidget( {
9582 * var radio3 = new OO.ui.RadioInputWidget( {
9586 * // Create a fieldset layout with fields for each radio button.
9587 * var fieldset = new OO.ui.FieldsetLayout( {
9588 * label: 'Radio inputs'
9590 * fieldset.addItems( [
9591 * new OO.ui.FieldLayout( radio1, { label: 'Selected', align: 'inline' } ),
9592 * new OO.ui.FieldLayout( radio2, { label: 'Unselected', align: 'inline' } ),
9593 * new OO.ui.FieldLayout( radio3, { label: 'Disabled', align: 'inline' } ),
9595 * $( 'body' ).append( fieldset.$element );
9597 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs
9600 * @extends OO.ui.InputWidget
9603 * @param {Object} [config] Configuration options
9604 * @cfg {boolean} [selected=false] Select the radio button initially. By default, the radio button is not selected.
9606 OO
.ui
.RadioInputWidget
= function OoUiRadioInputWidget( config
) {
9607 // Configuration initialization
9608 config
= config
|| {};
9610 // Parent constructor
9611 OO
.ui
.RadioInputWidget
.parent
.call( this, config
);
9615 .addClass( 'oo-ui-radioInputWidget' )
9616 // Required for pretty styling in WikimediaUI theme
9617 .append( $( '<span>' ) );
9618 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
9623 OO
.inheritClass( OO
.ui
.RadioInputWidget
, OO
.ui
.InputWidget
);
9625 /* Static Properties */
9631 OO
.ui
.RadioInputWidget
.static.tagName
= 'span';
9633 /* Static Methods */
9638 OO
.ui
.RadioInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9639 var state
= OO
.ui
.RadioInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9640 state
.checked
= config
.$input
.prop( 'checked' );
9650 OO
.ui
.RadioInputWidget
.prototype.getInputElement = function () {
9651 return $( '<input>' ).attr( 'type', 'radio' );
9657 OO
.ui
.RadioInputWidget
.prototype.onEdit = function () {
9658 // RadioInputWidget doesn't track its state.
9662 * Set selection state of this radio button.
9664 * @param {boolean} state `true` for selected
9667 OO
.ui
.RadioInputWidget
.prototype.setSelected = function ( state
) {
9668 // RadioInputWidget doesn't track its state.
9669 this.$input
.prop( 'checked', state
);
9670 // The first time that the selection state is set (probably while constructing the widget),
9671 // remember it in defaultSelected. This property can be later used to check whether
9672 // the selection state of the input has been changed since it was created.
9673 if ( this.defaultSelected
=== undefined ) {
9674 this.defaultSelected
= state
;
9675 this.$input
[ 0 ].defaultChecked
= this.defaultSelected
;
9681 * Check if this radio button is selected.
9683 * @return {boolean} Radio is selected
9685 OO
.ui
.RadioInputWidget
.prototype.isSelected = function () {
9686 return this.$input
.prop( 'checked' );
9692 OO
.ui
.RadioInputWidget
.prototype.simulateLabelClick = function () {
9693 if ( !this.isDisabled() ) {
9694 this.$input
.click();
9702 OO
.ui
.RadioInputWidget
.prototype.restorePreInfuseState = function ( state
) {
9703 OO
.ui
.RadioInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
9704 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
9705 this.setSelected( state
.checked
);
9710 * RadioSelectInputWidget is a {@link OO.ui.RadioSelectWidget RadioSelectWidget} intended to be used
9711 * within an HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
9712 * of a hidden HTML `input` tag. Please see the [OOUI documentation on MediaWiki][1] for
9713 * more information about input widgets.
9715 * This and OO.ui.DropdownInputWidget support the same configuration options.
9718 * // Example: A RadioSelectInputWidget with three options
9719 * var radioSelectInput = new OO.ui.RadioSelectInputWidget( {
9721 * { data: 'a', label: 'First' },
9722 * { data: 'b', label: 'Second'},
9723 * { data: 'c', label: 'Third' }
9726 * $( 'body' ).append( radioSelectInput.$element );
9728 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs
9731 * @extends OO.ui.InputWidget
9734 * @param {Object} [config] Configuration options
9735 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
9737 OO
.ui
.RadioSelectInputWidget
= function OoUiRadioSelectInputWidget( config
) {
9738 // Configuration initialization
9739 config
= config
|| {};
9741 // Properties (must be done before parent constructor which calls #setDisabled)
9742 this.radioSelectWidget
= new OO
.ui
.RadioSelectWidget();
9743 // Set up the options before parent constructor, which uses them to validate config.value.
9744 // Use this instead of setOptions() because this.$input is not set up yet
9745 this.setOptionsData( config
.options
|| [] );
9747 // Parent constructor
9748 OO
.ui
.RadioSelectInputWidget
.parent
.call( this, config
);
9751 this.radioSelectWidget
.connect( this, { select
: 'onMenuSelect' } );
9755 .addClass( 'oo-ui-radioSelectInputWidget' )
9756 .append( this.radioSelectWidget
.$element
);
9757 this.setTabIndexedElement( this.radioSelectWidget
.$tabIndexed
);
9762 OO
.inheritClass( OO
.ui
.RadioSelectInputWidget
, OO
.ui
.InputWidget
);
9764 /* Static Methods */
9769 OO
.ui
.RadioSelectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9770 var state
= OO
.ui
.RadioSelectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9771 state
.value
= $( node
).find( '.oo-ui-radioInputWidget .oo-ui-inputWidget-input:checked' ).val();
9778 OO
.ui
.RadioSelectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
9779 config
= OO
.ui
.RadioSelectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
9780 // Cannot reuse the `<input type=radio>` set
9781 delete config
.$input
;
9791 OO
.ui
.RadioSelectInputWidget
.prototype.getInputElement = function () {
9792 // Use this instead of <input type="hidden">, because hidden inputs do not have separate
9793 // 'value' and 'defaultValue' properties, and InputWidget wants to handle 'defaultValue'.
9794 return $( '<input>' ).addClass( 'oo-ui-element-hidden' );
9798 * Handles menu select events.
9801 * @param {OO.ui.RadioOptionWidget} item Selected menu item
9803 OO
.ui
.RadioSelectInputWidget
.prototype.onMenuSelect = function ( item
) {
9804 this.setValue( item
.getData() );
9810 OO
.ui
.RadioSelectInputWidget
.prototype.setValue = function ( value
) {
9812 value
= this.cleanUpValue( value
);
9813 // Only allow setting values that are actually present in the dropdown
9814 selected
= this.radioSelectWidget
.findItemFromData( value
) ||
9815 this.radioSelectWidget
.findFirstSelectableItem();
9816 this.radioSelectWidget
.selectItem( selected
);
9817 value
= selected
? selected
.getData() : '';
9818 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setValue
.call( this, value
);
9825 OO
.ui
.RadioSelectInputWidget
.prototype.setDisabled = function ( state
) {
9826 this.radioSelectWidget
.setDisabled( state
);
9827 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
9832 * Set the options available for this input.
9834 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9837 OO
.ui
.RadioSelectInputWidget
.prototype.setOptions = function ( options
) {
9838 var value
= this.getValue();
9840 this.setOptionsData( options
);
9842 // Re-set the value to update the visible interface (RadioSelectWidget).
9843 // In case the previous value is no longer an available option, select the first valid one.
9844 this.setValue( value
);
9850 * Set the internal list of options, used e.g. by setValue() to see which options are allowed.
9852 * This method may be called before the parent constructor, so various properties may not be
9855 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9858 OO
.ui
.RadioSelectInputWidget
.prototype.setOptionsData = function ( options
) {
9861 this.radioSelectWidget
9863 .addItems( options
.map( function ( opt
) {
9864 var optValue
= widget
.cleanUpValue( opt
.data
);
9865 return new OO
.ui
.RadioOptionWidget( {
9867 label
: opt
.label
!== undefined ? opt
.label
: optValue
9875 OO
.ui
.RadioSelectInputWidget
.prototype.focus = function () {
9876 this.radioSelectWidget
.focus();
9883 OO
.ui
.RadioSelectInputWidget
.prototype.blur = function () {
9884 this.radioSelectWidget
.blur();
9889 * CheckboxMultiselectInputWidget is a
9890 * {@link OO.ui.CheckboxMultiselectWidget CheckboxMultiselectWidget} intended to be used within a
9891 * HTML form, such as a OO.ui.FormLayout. The selected values are synchronized with the value of
9892 * HTML `<input type=checkbox>` tags. Please see the [OOUI documentation on MediaWiki][1] for
9893 * more information about input widgets.
9896 * // Example: A CheckboxMultiselectInputWidget with three options
9897 * var multiselectInput = new OO.ui.CheckboxMultiselectInputWidget( {
9899 * { data: 'a', label: 'First' },
9900 * { data: 'b', label: 'Second'},
9901 * { data: 'c', label: 'Third' }
9904 * $( 'body' ).append( multiselectInput.$element );
9906 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs
9909 * @extends OO.ui.InputWidget
9912 * @param {Object} [config] Configuration options
9913 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: …, disabled: … }`
9915 OO
.ui
.CheckboxMultiselectInputWidget
= function OoUiCheckboxMultiselectInputWidget( config
) {
9916 // Configuration initialization
9917 config
= config
|| {};
9919 // Properties (must be done before parent constructor which calls #setDisabled)
9920 this.checkboxMultiselectWidget
= new OO
.ui
.CheckboxMultiselectWidget();
9921 // Must be set before the #setOptionsData call below
9922 this.inputName
= config
.name
;
9923 // Set up the options before parent constructor, which uses them to validate config.value.
9924 // Use this instead of setOptions() because this.$input is not set up yet
9925 this.setOptionsData( config
.options
|| [] );
9927 // Parent constructor
9928 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.call( this, config
);
9931 this.checkboxMultiselectWidget
.connect( this, { select
: 'onCheckboxesSelect' } );
9935 .addClass( 'oo-ui-checkboxMultiselectInputWidget' )
9936 .append( this.checkboxMultiselectWidget
.$element
);
9937 // We don't use this.$input, but rather the CheckboxInputWidgets inside each option
9938 this.$input
.detach();
9943 OO
.inheritClass( OO
.ui
.CheckboxMultiselectInputWidget
, OO
.ui
.InputWidget
);
9945 /* Static Methods */
9950 OO
.ui
.CheckboxMultiselectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9951 var state
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9952 state
.value
= $( node
).find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
9953 .toArray().map( function ( el
) { return el
.value
; } );
9960 OO
.ui
.CheckboxMultiselectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
9961 config
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
9962 // Cannot reuse the `<input type=checkbox>` set
9963 delete config
.$input
;
9973 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getInputElement = function () {
9975 return $( '<unused>' );
9979 * Handles CheckboxMultiselectWidget select events.
9983 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.onCheckboxesSelect = function () {
9984 this.setValue( this.checkboxMultiselectWidget
.findSelectedItemsData() );
9990 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getValue = function () {
9991 var value
= this.$element
.find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
9992 .toArray().map( function ( el
) { return el
.value
; } );
9993 if ( this.value
!== value
) {
9994 this.setValue( value
);
10002 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setValue = function ( value
) {
10003 value
= this.cleanUpValue( value
);
10004 this.checkboxMultiselectWidget
.selectItemsByData( value
);
10005 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setValue
.call( this, value
);
10006 if ( this.optionsDirty
) {
10007 // We reached this from the constructor or from #setOptions.
10008 // We have to update the <select> element.
10009 this.updateOptionsInterface();
10015 * Clean up incoming value.
10017 * @param {string[]} value Original value
10018 * @return {string[]} Cleaned up value
10020 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.cleanUpValue = function ( value
) {
10021 var i
, singleValue
,
10023 if ( !Array
.isArray( value
) ) {
10026 for ( i
= 0; i
< value
.length
; i
++ ) {
10028 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( this, value
[ i
] );
10029 // Remove options that we don't have here
10030 if ( !this.checkboxMultiselectWidget
.findItemFromData( singleValue
) ) {
10033 cleanValue
.push( singleValue
);
10041 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setDisabled = function ( state
) {
10042 this.checkboxMultiselectWidget
.setDisabled( state
);
10043 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
10048 * Set the options available for this input.
10050 * @param {Object[]} options Array of menu options in the format `{ data: …, label: …, disabled: … }`
10053 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setOptions = function ( options
) {
10054 var value
= this.getValue();
10056 this.setOptionsData( options
);
10058 // Re-set the value to update the visible interface (CheckboxMultiselectWidget).
10059 // This will also get rid of any stale options that we just removed.
10060 this.setValue( value
);
10066 * Set the internal list of options, used e.g. by setValue() to see which options are allowed.
10068 * This method may be called before the parent constructor, so various properties may not be
10071 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
10074 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setOptionsData = function ( options
) {
10077 this.optionsDirty
= true;
10079 this.checkboxMultiselectWidget
10081 .addItems( options
.map( function ( opt
) {
10082 var optValue
, item
, optDisabled
;
10084 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( widget
, opt
.data
);
10085 optDisabled
= opt
.disabled
!== undefined ? opt
.disabled
: false;
10086 item
= new OO
.ui
.CheckboxMultioptionWidget( {
10088 label
: opt
.label
!== undefined ? opt
.label
: optValue
,
10089 disabled
: optDisabled
10091 // Set the 'name' and 'value' for form submission
10092 item
.checkbox
.$input
.attr( 'name', widget
.inputName
);
10093 item
.checkbox
.setValue( optValue
);
10099 * Update the user-visible interface to match the internal list of options and value.
10101 * This method must only be called after the parent constructor.
10105 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.updateOptionsInterface = function () {
10106 var defaultValue
= this.defaultValue
;
10108 this.checkboxMultiselectWidget
.getItems().forEach( function ( item
) {
10109 // Remember original selection state. This property can be later used to check whether
10110 // the selection state of the input has been changed since it was created.
10111 var isDefault
= defaultValue
.indexOf( item
.getData() ) !== -1;
10112 item
.checkbox
.defaultSelected
= isDefault
;
10113 item
.checkbox
.$input
[ 0 ].defaultChecked
= isDefault
;
10116 this.optionsDirty
= false;
10122 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.focus = function () {
10123 this.checkboxMultiselectWidget
.focus();
10128 * TextInputWidgets, like HTML text inputs, can be configured with options that customize the
10129 * size of the field as well as its presentation. In addition, these widgets can be configured
10130 * with {@link OO.ui.mixin.IconElement icons}, {@link OO.ui.mixin.IndicatorElement indicators}, an optional
10131 * validation-pattern (used to determine if an input value is valid or not) and an input filter,
10132 * which modifies incoming values rather than validating them.
10133 * Please see the [OOUI documentation on MediaWiki] [1] for more information and examples.
10135 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
10138 * // Example of a text input widget
10139 * var textInput = new OO.ui.TextInputWidget( {
10140 * value: 'Text input'
10142 * $( 'body' ).append( textInput.$element );
10144 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs
10147 * @extends OO.ui.InputWidget
10148 * @mixins OO.ui.mixin.IconElement
10149 * @mixins OO.ui.mixin.IndicatorElement
10150 * @mixins OO.ui.mixin.PendingElement
10151 * @mixins OO.ui.mixin.LabelElement
10154 * @param {Object} [config] Configuration options
10155 * @cfg {string} [type='text'] The value of the HTML `type` attribute: 'text', 'password'
10156 * 'email', 'url' or 'number'.
10157 * @cfg {string} [placeholder] Placeholder text
10158 * @cfg {boolean} [autofocus=false] Use an HTML `autofocus` attribute to
10159 * instruct the browser to focus this widget.
10160 * @cfg {boolean} [readOnly=false] Prevent changes to the value of the text input.
10161 * @cfg {number} [maxLength] Maximum number of characters allowed in the input.
10163 * For unfortunate historical reasons, this counts the number of UTF-16 code units rather than
10164 * Unicode codepoints, which means that codepoints outside the Basic Multilingual Plane (e.g.
10165 * many emojis) count as 2 characters each.
10166 * @cfg {string} [labelPosition='after'] The position of the inline label relative to that of
10167 * the value or placeholder text: `'before'` or `'after'`
10168 * @cfg {boolean} [required=false] Mark the field as required with `true`. Implies `indicator: 'required'`.
10169 * Note that `false` & setting `indicator: 'required' will result in no indicator shown.
10170 * @cfg {boolean} [autocomplete=true] Should the browser support autocomplete for this field
10171 * @cfg {boolean} [spellcheck] Should the browser support spellcheck for this field (`undefined` means
10172 * leaving it up to the browser).
10173 * @cfg {RegExp|Function|string} [validate] Validation pattern: when string, a symbolic name of a
10174 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer'
10175 * (the value must contain only numbers); when RegExp, a regular expression that must match the
10176 * value for it to be considered valid; when Function, a function receiving the value as parameter
10177 * that must return true, or promise resolving to true, for it to be considered valid.
10179 OO
.ui
.TextInputWidget
= function OoUiTextInputWidget( config
) {
10180 // Configuration initialization
10181 config
= $.extend( {
10183 labelPosition
: 'after'
10186 // Parent constructor
10187 OO
.ui
.TextInputWidget
.parent
.call( this, config
);
10189 // Mixin constructors
10190 OO
.ui
.mixin
.IconElement
.call( this, config
);
10191 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
10192 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$input
} ) );
10193 OO
.ui
.mixin
.LabelElement
.call( this, config
);
10196 this.type
= this.getSaneType( config
);
10197 this.readOnly
= false;
10198 this.required
= false;
10199 this.validate
= null;
10200 this.styleHeight
= null;
10201 this.scrollWidth
= null;
10203 this.setValidation( config
.validate
);
10204 this.setLabelPosition( config
.labelPosition
);
10208 keypress
: this.onKeyPress
.bind( this ),
10209 blur
: this.onBlur
.bind( this ),
10210 focus
: this.onFocus
.bind( this )
10212 this.$icon
.on( 'mousedown', this.onIconMouseDown
.bind( this ) );
10213 this.$indicator
.on( 'mousedown', this.onIndicatorMouseDown
.bind( this ) );
10214 this.on( 'labelChange', this.updatePosition
.bind( this ) );
10215 this.on( 'change', OO
.ui
.debounce( this.onDebouncedChange
.bind( this ), 250 ) );
10219 .addClass( 'oo-ui-textInputWidget oo-ui-textInputWidget-type-' + this.type
)
10220 .append( this.$icon
, this.$indicator
);
10221 this.setReadOnly( !!config
.readOnly
);
10222 this.setRequired( !!config
.required
);
10223 if ( config
.placeholder
!== undefined ) {
10224 this.$input
.attr( 'placeholder', config
.placeholder
);
10226 if ( config
.maxLength
!== undefined ) {
10227 this.$input
.attr( 'maxlength', config
.maxLength
);
10229 if ( config
.autofocus
) {
10230 this.$input
.attr( 'autofocus', 'autofocus' );
10232 if ( config
.autocomplete
=== false ) {
10233 this.$input
.attr( 'autocomplete', 'off' );
10234 // Turning off autocompletion also disables "form caching" when the user navigates to a
10235 // different page and then clicks "Back". Re-enable it when leaving. Borrowed from jQuery UI.
10237 beforeunload: function () {
10238 this.$input
.removeAttr( 'autocomplete' );
10240 pageshow: function () {
10241 // Browsers don't seem to actually fire this event on "Back", they instead just reload the
10242 // whole page... it shouldn't hurt, though.
10243 this.$input
.attr( 'autocomplete', 'off' );
10247 if ( config
.spellcheck
!== undefined ) {
10248 this.$input
.attr( 'spellcheck', config
.spellcheck
? 'true' : 'false' );
10250 if ( this.label
) {
10251 this.isWaitingToBeAttached
= true;
10252 this.installParentChangeDetector();
10258 OO
.inheritClass( OO
.ui
.TextInputWidget
, OO
.ui
.InputWidget
);
10259 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IconElement
);
10260 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
10261 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.PendingElement
);
10262 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.LabelElement
);
10264 /* Static Properties */
10266 OO
.ui
.TextInputWidget
.static.validationPatterns
= {
10274 * An `enter` event is emitted when the user presses 'enter' inside the text box.
10282 * Handle icon mouse down events.
10285 * @param {jQuery.Event} e Mouse down event
10287 OO
.ui
.TextInputWidget
.prototype.onIconMouseDown = function ( e
) {
10288 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
10295 * Handle indicator mouse down events.
10298 * @param {jQuery.Event} e Mouse down event
10300 OO
.ui
.TextInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
10301 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
10308 * Handle key press events.
10311 * @param {jQuery.Event} e Key press event
10312 * @fires enter If enter key is pressed
10314 OO
.ui
.TextInputWidget
.prototype.onKeyPress = function ( e
) {
10315 if ( e
.which
=== OO
.ui
.Keys
.ENTER
) {
10316 this.emit( 'enter', e
);
10321 * Handle blur events.
10324 * @param {jQuery.Event} e Blur event
10326 OO
.ui
.TextInputWidget
.prototype.onBlur = function () {
10327 this.setValidityFlag();
10331 * Handle focus events.
10334 * @param {jQuery.Event} e Focus event
10336 OO
.ui
.TextInputWidget
.prototype.onFocus = function () {
10337 if ( this.isWaitingToBeAttached
) {
10338 // If we've received focus, then we must be attached to the document, and if
10339 // isWaitingToBeAttached is still true, that means the handler never fired. Fire it now.
10340 this.onElementAttach();
10342 this.setValidityFlag( true );
10346 * Handle element attach events.
10349 * @param {jQuery.Event} e Element attach event
10351 OO
.ui
.TextInputWidget
.prototype.onElementAttach = function () {
10352 this.isWaitingToBeAttached
= false;
10353 // Any previously calculated size is now probably invalid if we reattached elsewhere
10354 this.valCache
= null;
10355 this.positionLabel();
10359 * Handle debounced change events.
10361 * @param {string} value
10364 OO
.ui
.TextInputWidget
.prototype.onDebouncedChange = function () {
10365 this.setValidityFlag();
10369 * Check if the input is {@link #readOnly read-only}.
10371 * @return {boolean}
10373 OO
.ui
.TextInputWidget
.prototype.isReadOnly = function () {
10374 return this.readOnly
;
10378 * Set the {@link #readOnly read-only} state of the input.
10380 * @param {boolean} state Make input read-only
10383 OO
.ui
.TextInputWidget
.prototype.setReadOnly = function ( state
) {
10384 this.readOnly
= !!state
;
10385 this.$input
.prop( 'readOnly', this.readOnly
);
10390 * Check if the input is {@link #required required}.
10392 * @return {boolean}
10394 OO
.ui
.TextInputWidget
.prototype.isRequired = function () {
10395 return this.required
;
10399 * Set the {@link #required required} state of the input.
10401 * @param {boolean} state Make input required
10404 OO
.ui
.TextInputWidget
.prototype.setRequired = function ( state
) {
10405 this.required
= !!state
;
10406 if ( this.required
) {
10408 .prop( 'required', true )
10409 .attr( 'aria-required', 'true' );
10410 if ( this.getIndicator() === null ) {
10411 this.setIndicator( 'required' );
10415 .prop( 'required', false )
10416 .removeAttr( 'aria-required' );
10417 if ( this.getIndicator() === 'required' ) {
10418 this.setIndicator( null );
10425 * Support function for making #onElementAttach work across browsers.
10427 * This whole function could be replaced with one line of code using the DOMNodeInsertedIntoDocument
10428 * event, but it's not supported by Firefox and allegedly deprecated, so we only use it as fallback.
10430 * Due to MutationObserver performance woes, #onElementAttach is only somewhat reliably called the
10431 * first time that the element gets attached to the documented.
10433 OO
.ui
.TextInputWidget
.prototype.installParentChangeDetector = function () {
10434 var mutationObserver
, onRemove
, topmostNode
, fakeParentNode
,
10435 MutationObserver
= window
.MutationObserver
|| window
.WebKitMutationObserver
|| window
.MozMutationObserver
,
10438 if ( MutationObserver
) {
10439 // The new way. If only it wasn't so ugly.
10441 if ( this.isElementAttached() ) {
10442 // Widget is attached already, do nothing. This breaks the functionality of this function when
10443 // the widget is detached and reattached. Alas, doing this correctly with MutationObserver
10444 // would require observation of the whole document, which would hurt performance of other,
10445 // more important code.
10449 // Find topmost node in the tree
10450 topmostNode
= this.$element
[ 0 ];
10451 while ( topmostNode
.parentNode
) {
10452 topmostNode
= topmostNode
.parentNode
;
10455 // We have no way to detect the $element being attached somewhere without observing the entire
10456 // DOM with subtree modifications, which would hurt performance. So we cheat: we hook to the
10457 // parent node of $element, and instead detect when $element is removed from it (and thus
10458 // probably attached somewhere else). If there is no parent, we create a "fake" one. If it
10459 // doesn't get attached, we end up back here and create the parent.
10461 mutationObserver
= new MutationObserver( function ( mutations
) {
10462 var i
, j
, removedNodes
;
10463 for ( i
= 0; i
< mutations
.length
; i
++ ) {
10464 removedNodes
= mutations
[ i
].removedNodes
;
10465 for ( j
= 0; j
< removedNodes
.length
; j
++ ) {
10466 if ( removedNodes
[ j
] === topmostNode
) {
10467 setTimeout( onRemove
, 0 );
10474 onRemove = function () {
10475 // If the node was attached somewhere else, report it
10476 if ( widget
.isElementAttached() ) {
10477 widget
.onElementAttach();
10479 mutationObserver
.disconnect();
10480 widget
.installParentChangeDetector();
10483 // Create a fake parent and observe it
10484 fakeParentNode
= $( '<div>' ).append( topmostNode
)[ 0 ];
10485 mutationObserver
.observe( fakeParentNode
, { childList
: true } );
10487 // Using the DOMNodeInsertedIntoDocument event is much nicer and less magical, and works for
10488 // detachment and reattachment, but it's not supported by Firefox and allegedly deprecated.
10489 this.$element
.on( 'DOMNodeInsertedIntoDocument', this.onElementAttach
.bind( this ) );
10497 OO
.ui
.TextInputWidget
.prototype.getInputElement = function ( config
) {
10498 if ( this.getSaneType( config
) === 'number' ) {
10499 return $( '<input>' )
10500 .attr( 'step', 'any' )
10501 .attr( 'type', 'number' );
10503 return $( '<input>' ).attr( 'type', this.getSaneType( config
) );
10508 * Get sanitized value for 'type' for given config.
10510 * @param {Object} config Configuration options
10511 * @return {string|null}
10514 OO
.ui
.TextInputWidget
.prototype.getSaneType = function ( config
) {
10515 var allowedTypes
= [
10522 return allowedTypes
.indexOf( config
.type
) !== -1 ? config
.type
: 'text';
10526 * Focus the input and select a specified range within the text.
10528 * @param {number} from Select from offset
10529 * @param {number} [to] Select to offset, defaults to from
10532 OO
.ui
.TextInputWidget
.prototype.selectRange = function ( from, to
) {
10533 var isBackwards
, start
, end
,
10534 input
= this.$input
[ 0 ];
10538 isBackwards
= to
< from;
10539 start
= isBackwards
? to
: from;
10540 end
= isBackwards
? from : to
;
10545 input
.setSelectionRange( start
, end
, isBackwards
? 'backward' : 'forward' );
10547 // IE throws an exception if you call setSelectionRange on a unattached DOM node.
10548 // Rather than expensively check if the input is attached every time, just check
10549 // if it was the cause of an error being thrown. If not, rethrow the error.
10550 if ( this.getElementDocument().body
.contains( input
) ) {
10558 * Get an object describing the current selection range in a directional manner
10560 * @return {Object} Object containing 'from' and 'to' offsets
10562 OO
.ui
.TextInputWidget
.prototype.getRange = function () {
10563 var input
= this.$input
[ 0 ],
10564 start
= input
.selectionStart
,
10565 end
= input
.selectionEnd
,
10566 isBackwards
= input
.selectionDirection
=== 'backward';
10569 from: isBackwards
? end
: start
,
10570 to
: isBackwards
? start
: end
10575 * Get the length of the text input value.
10577 * This could differ from the length of #getValue if the
10578 * value gets filtered
10580 * @return {number} Input length
10582 OO
.ui
.TextInputWidget
.prototype.getInputLength = function () {
10583 return this.$input
[ 0 ].value
.length
;
10587 * Focus the input and select the entire text.
10591 OO
.ui
.TextInputWidget
.prototype.select = function () {
10592 return this.selectRange( 0, this.getInputLength() );
10596 * Focus the input and move the cursor to the start.
10600 OO
.ui
.TextInputWidget
.prototype.moveCursorToStart = function () {
10601 return this.selectRange( 0 );
10605 * Focus the input and move the cursor to the end.
10609 OO
.ui
.TextInputWidget
.prototype.moveCursorToEnd = function () {
10610 return this.selectRange( this.getInputLength() );
10614 * Insert new content into the input.
10616 * @param {string} content Content to be inserted
10619 OO
.ui
.TextInputWidget
.prototype.insertContent = function ( content
) {
10621 range
= this.getRange(),
10622 value
= this.getValue();
10624 start
= Math
.min( range
.from, range
.to
);
10625 end
= Math
.max( range
.from, range
.to
);
10627 this.setValue( value
.slice( 0, start
) + content
+ value
.slice( end
) );
10628 this.selectRange( start
+ content
.length
);
10633 * Insert new content either side of a selection.
10635 * @param {string} pre Content to be inserted before the selection
10636 * @param {string} post Content to be inserted after the selection
10639 OO
.ui
.TextInputWidget
.prototype.encapsulateContent = function ( pre
, post
) {
10641 range
= this.getRange(),
10642 offset
= pre
.length
;
10644 start
= Math
.min( range
.from, range
.to
);
10645 end
= Math
.max( range
.from, range
.to
);
10647 this.selectRange( start
).insertContent( pre
);
10648 this.selectRange( offset
+ end
).insertContent( post
);
10650 this.selectRange( offset
+ start
, offset
+ end
);
10655 * Set the validation pattern.
10657 * The validation pattern is either a regular expression, a function, or the symbolic name of a
10658 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer' (the
10659 * value must contain only numbers).
10661 * @param {RegExp|Function|string|null} validate Regular expression, function, or the symbolic name
10662 * of a pattern (either ‘integer’ or ‘non-empty’) defined by the class.
10664 OO
.ui
.TextInputWidget
.prototype.setValidation = function ( validate
) {
10665 if ( validate
instanceof RegExp
|| validate
instanceof Function
) {
10666 this.validate
= validate
;
10668 this.validate
= this.constructor.static.validationPatterns
[ validate
] || /.*/;
10673 * Sets the 'invalid' flag appropriately.
10675 * @param {boolean} [isValid] Optionally override validation result
10677 OO
.ui
.TextInputWidget
.prototype.setValidityFlag = function ( isValid
) {
10679 setFlag = function ( valid
) {
10681 widget
.$input
.attr( 'aria-invalid', 'true' );
10683 widget
.$input
.removeAttr( 'aria-invalid' );
10685 widget
.setFlags( { invalid
: !valid
} );
10688 if ( isValid
!== undefined ) {
10689 setFlag( isValid
);
10691 this.getValidity().then( function () {
10700 * Get the validity of current value.
10702 * This method returns a promise that resolves if the value is valid and rejects if
10703 * it isn't. Uses the {@link #validate validation pattern} to check for validity.
10705 * @return {jQuery.Promise} A promise that resolves if the value is valid, rejects if not.
10707 OO
.ui
.TextInputWidget
.prototype.getValidity = function () {
10710 function rejectOrResolve( valid
) {
10712 return $.Deferred().resolve().promise();
10714 return $.Deferred().reject().promise();
10718 // Check browser validity and reject if it is invalid
10720 this.$input
[ 0 ].checkValidity
!== undefined &&
10721 this.$input
[ 0 ].checkValidity() === false
10723 return rejectOrResolve( false );
10726 // Run our checks if the browser thinks the field is valid
10727 if ( this.validate
instanceof Function
) {
10728 result
= this.validate( this.getValue() );
10729 if ( result
&& $.isFunction( result
.promise
) ) {
10730 return result
.promise().then( function ( valid
) {
10731 return rejectOrResolve( valid
);
10734 return rejectOrResolve( result
);
10737 return rejectOrResolve( this.getValue().match( this.validate
) );
10742 * Set the position of the inline label relative to that of the value: `‘before’` or `‘after’`.
10744 * @param {string} labelPosition Label position, 'before' or 'after'
10747 OO
.ui
.TextInputWidget
.prototype.setLabelPosition = function ( labelPosition
) {
10748 this.labelPosition
= labelPosition
;
10749 if ( this.label
) {
10750 // If there is no label and we only change the position, #updatePosition is a no-op,
10751 // but it takes really a lot of work to do nothing.
10752 this.updatePosition();
10758 * Update the position of the inline label.
10760 * This method is called by #setLabelPosition, and can also be called on its own if
10761 * something causes the label to be mispositioned.
10765 OO
.ui
.TextInputWidget
.prototype.updatePosition = function () {
10766 var after
= this.labelPosition
=== 'after';
10769 .toggleClass( 'oo-ui-textInputWidget-labelPosition-after', !!this.label
&& after
)
10770 .toggleClass( 'oo-ui-textInputWidget-labelPosition-before', !!this.label
&& !after
);
10772 this.valCache
= null;
10773 this.scrollWidth
= null;
10774 this.positionLabel();
10780 * Position the label by setting the correct padding on the input.
10785 OO
.ui
.TextInputWidget
.prototype.positionLabel = function () {
10786 var after
, rtl
, property
, newCss
;
10788 if ( this.isWaitingToBeAttached
) {
10789 // #onElementAttach will be called soon, which calls this method
10794 'padding-right': '',
10798 if ( this.label
) {
10799 this.$element
.append( this.$label
);
10801 this.$label
.detach();
10802 // Clear old values if present
10803 this.$input
.css( newCss
);
10807 after
= this.labelPosition
=== 'after';
10808 rtl
= this.$element
.css( 'direction' ) === 'rtl';
10809 property
= after
=== rtl
? 'padding-left' : 'padding-right';
10811 newCss
[ property
] = this.$label
.outerWidth( true ) + ( after
? this.scrollWidth
: 0 );
10812 // We have to clear the padding on the other side, in case the element direction changed
10813 this.$input
.css( newCss
);
10820 * @extends OO.ui.TextInputWidget
10823 * @param {Object} [config] Configuration options
10825 OO
.ui
.SearchInputWidget
= function OoUiSearchInputWidget( config
) {
10826 config
= $.extend( {
10830 // Parent constructor
10831 OO
.ui
.SearchInputWidget
.parent
.call( this, config
);
10834 this.connect( this, {
10839 this.updateSearchIndicator();
10840 this.connect( this, {
10841 disable
: 'onDisable'
10847 OO
.inheritClass( OO
.ui
.SearchInputWidget
, OO
.ui
.TextInputWidget
);
10855 OO
.ui
.SearchInputWidget
.prototype.getSaneType = function () {
10862 OO
.ui
.SearchInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
10863 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
10864 // Clear the text field
10865 this.setValue( '' );
10872 * Update the 'clear' indicator displayed on type: 'search' text
10873 * fields, hiding it when the field is already empty or when it's not
10876 OO
.ui
.SearchInputWidget
.prototype.updateSearchIndicator = function () {
10877 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
10878 this.setIndicator( null );
10880 this.setIndicator( 'clear' );
10885 * Handle change events.
10889 OO
.ui
.SearchInputWidget
.prototype.onChange = function () {
10890 this.updateSearchIndicator();
10894 * Handle disable events.
10896 * @param {boolean} disabled Element is disabled
10899 OO
.ui
.SearchInputWidget
.prototype.onDisable = function () {
10900 this.updateSearchIndicator();
10906 OO
.ui
.SearchInputWidget
.prototype.setReadOnly = function ( state
) {
10907 OO
.ui
.SearchInputWidget
.parent
.prototype.setReadOnly
.call( this, state
);
10908 this.updateSearchIndicator();
10914 * @extends OO.ui.TextInputWidget
10917 * @param {Object} [config] Configuration options
10918 * @cfg {number} [rows] Number of visible lines in textarea. If used with `autosize`,
10919 * specifies minimum number of rows to display.
10920 * @cfg {boolean} [autosize=false] Automatically resize the text input to fit its content.
10921 * Use the #maxRows config to specify a maximum number of displayed rows.
10922 * @cfg {number} [maxRows] Maximum number of rows to display when #autosize is set to true.
10923 * Defaults to the maximum of `10` and `2 * rows`, or `10` if `rows` isn't provided.
10925 OO
.ui
.MultilineTextInputWidget
= function OoUiMultilineTextInputWidget( config
) {
10926 config
= $.extend( {
10929 // Parent constructor
10930 OO
.ui
.MultilineTextInputWidget
.parent
.call( this, config
);
10933 this.autosize
= !!config
.autosize
;
10934 this.minRows
= config
.rows
!== undefined ? config
.rows
: '';
10935 this.maxRows
= config
.maxRows
|| Math
.max( 2 * ( this.minRows
|| 0 ), 10 );
10937 // Clone for resizing
10938 if ( this.autosize
) {
10939 this.$clone
= this.$input
10941 .removeAttr( 'id' )
10942 .removeAttr( 'name' )
10943 .insertAfter( this.$input
)
10944 .attr( 'aria-hidden', 'true' )
10945 .addClass( 'oo-ui-element-hidden' );
10949 this.connect( this, {
10954 if ( config
.rows
) {
10955 this.$input
.attr( 'rows', config
.rows
);
10957 if ( this.autosize
) {
10958 this.$input
.addClass( 'oo-ui-textInputWidget-autosized' );
10959 this.isWaitingToBeAttached
= true;
10960 this.installParentChangeDetector();
10966 OO
.inheritClass( OO
.ui
.MultilineTextInputWidget
, OO
.ui
.TextInputWidget
);
10968 /* Static Methods */
10973 OO
.ui
.MultilineTextInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
10974 var state
= OO
.ui
.MultilineTextInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
10975 state
.scrollTop
= config
.$input
.scrollTop();
10984 OO
.ui
.MultilineTextInputWidget
.prototype.onElementAttach = function () {
10985 OO
.ui
.MultilineTextInputWidget
.parent
.prototype.onElementAttach
.call( this );
10990 * Handle change events.
10994 OO
.ui
.MultilineTextInputWidget
.prototype.onChange = function () {
11001 OO
.ui
.MultilineTextInputWidget
.prototype.updatePosition = function () {
11002 OO
.ui
.MultilineTextInputWidget
.parent
.prototype.updatePosition
.call( this );
11009 * Modify to emit 'enter' on Ctrl/Meta+Enter, instead of plain Enter
11011 OO
.ui
.MultilineTextInputWidget
.prototype.onKeyPress = function ( e
) {
11013 ( e
.which
=== OO
.ui
.Keys
.ENTER
&& ( e
.ctrlKey
|| e
.metaKey
) ) ||
11014 // Some platforms emit keycode 10 for ctrl+enter in a textarea
11017 this.emit( 'enter', e
);
11022 * Automatically adjust the size of the text input.
11024 * This only affects multiline inputs that are {@link #autosize autosized}.
11029 OO
.ui
.MultilineTextInputWidget
.prototype.adjustSize = function () {
11030 var scrollHeight
, innerHeight
, outerHeight
, maxInnerHeight
, measurementError
,
11031 idealHeight
, newHeight
, scrollWidth
, property
;
11033 if ( this.$input
.val() !== this.valCache
) {
11034 if ( this.autosize
) {
11036 .val( this.$input
.val() )
11037 .attr( 'rows', this.minRows
)
11038 // Set inline height property to 0 to measure scroll height
11039 .css( 'height', 0 );
11041 this.$clone
.removeClass( 'oo-ui-element-hidden' );
11043 this.valCache
= this.$input
.val();
11045 scrollHeight
= this.$clone
[ 0 ].scrollHeight
;
11047 // Remove inline height property to measure natural heights
11048 this.$clone
.css( 'height', '' );
11049 innerHeight
= this.$clone
.innerHeight();
11050 outerHeight
= this.$clone
.outerHeight();
11052 // Measure max rows height
11054 .attr( 'rows', this.maxRows
)
11055 .css( 'height', 'auto' )
11057 maxInnerHeight
= this.$clone
.innerHeight();
11059 // Difference between reported innerHeight and scrollHeight with no scrollbars present.
11060 // This is sometimes non-zero on Blink-based browsers, depending on zoom level.
11061 measurementError
= maxInnerHeight
- this.$clone
[ 0 ].scrollHeight
;
11062 idealHeight
= Math
.min( maxInnerHeight
, scrollHeight
+ measurementError
);
11064 this.$clone
.addClass( 'oo-ui-element-hidden' );
11066 // Only apply inline height when expansion beyond natural height is needed
11067 // Use the difference between the inner and outer height as a buffer
11068 newHeight
= idealHeight
> innerHeight
? idealHeight
+ ( outerHeight
- innerHeight
) : '';
11069 if ( newHeight
!== this.styleHeight
) {
11070 this.$input
.css( 'height', newHeight
);
11071 this.styleHeight
= newHeight
;
11072 this.emit( 'resize' );
11075 scrollWidth
= this.$input
[ 0 ].offsetWidth
- this.$input
[ 0 ].clientWidth
;
11076 if ( scrollWidth
!== this.scrollWidth
) {
11077 property
= this.$element
.css( 'direction' ) === 'rtl' ? 'left' : 'right';
11079 this.$label
.css( { right
: '', left
: '' } );
11080 this.$indicator
.css( { right
: '', left
: '' } );
11082 if ( scrollWidth
) {
11083 this.$indicator
.css( property
, scrollWidth
);
11084 if ( this.labelPosition
=== 'after' ) {
11085 this.$label
.css( property
, scrollWidth
);
11089 this.scrollWidth
= scrollWidth
;
11090 this.positionLabel();
11100 OO
.ui
.MultilineTextInputWidget
.prototype.getInputElement = function () {
11101 return $( '<textarea>' );
11105 * Check if the input automatically adjusts its size.
11107 * @return {boolean}
11109 OO
.ui
.MultilineTextInputWidget
.prototype.isAutosizing = function () {
11110 return !!this.autosize
;
11116 OO
.ui
.MultilineTextInputWidget
.prototype.restorePreInfuseState = function ( state
) {
11117 OO
.ui
.MultilineTextInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
11118 if ( state
.scrollTop
!== undefined ) {
11119 this.$input
.scrollTop( state
.scrollTop
);
11124 * ComboBoxInputWidgets combine a {@link OO.ui.TextInputWidget text input} (where a value
11125 * can be entered manually) and a {@link OO.ui.MenuSelectWidget menu of options} (from which
11126 * a value can be chosen instead). Users can choose options from the combo box in one of two ways:
11128 * - by typing a value in the text input field. If the value exactly matches the value of a menu
11129 * option, that option will appear to be selected.
11130 * - by choosing a value from the menu. The value of the chosen option will then appear in the text
11133 * After the user chooses an option, its `data` will be used as a new value for the widget.
11134 * A `label` also can be specified for each option: if given, it will be shown instead of the
11135 * `data` in the dropdown menu.
11137 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
11139 * For more information about menus and options, please see the [OOUI documentation on MediaWiki][1].
11142 * // Example: A ComboBoxInputWidget.
11143 * var comboBox = new OO.ui.ComboBoxInputWidget( {
11144 * value: 'Option 1',
11146 * { data: 'Option 1' },
11147 * { data: 'Option 2' },
11148 * { data: 'Option 3' }
11151 * $( 'body' ).append( comboBox.$element );
11154 * // Example: A ComboBoxInputWidget with additional option labels.
11155 * var comboBox = new OO.ui.ComboBoxInputWidget( {
11156 * value: 'Option 1',
11159 * data: 'Option 1',
11160 * label: 'Option One'
11163 * data: 'Option 2',
11164 * label: 'Option Two'
11167 * data: 'Option 3',
11168 * label: 'Option Three'
11172 * $( 'body' ).append( comboBox.$element );
11174 * [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options#Menu_selects_and_options
11177 * @extends OO.ui.TextInputWidget
11180 * @param {Object} [config] Configuration options
11181 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
11182 * @cfg {Object} [menu] Configuration options to pass to the {@link OO.ui.MenuSelectWidget menu select widget}.
11183 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
11184 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
11185 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
11186 * See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
11188 OO
.ui
.ComboBoxInputWidget
= function OoUiComboBoxInputWidget( config
) {
11189 // Configuration initialization
11190 config
= $.extend( {
11191 autocomplete
: false
11194 // ComboBoxInputWidget shouldn't support `multiline`
11195 config
.multiline
= false;
11197 // See InputWidget#reusePreInfuseDOM about `config.$input`
11198 if ( config
.$input
) {
11199 config
.$input
.removeAttr( 'list' );
11202 // Parent constructor
11203 OO
.ui
.ComboBoxInputWidget
.parent
.call( this, config
);
11206 this.$overlay
= ( config
.$overlay
=== true ? OO
.ui
.getDefaultOverlay() : config
.$overlay
) || this.$element
;
11207 this.dropdownButton
= new OO
.ui
.ButtonWidget( {
11208 classes
: [ 'oo-ui-comboBoxInputWidget-dropdownButton' ],
11210 disabled
: this.disabled
11212 this.menu
= new OO
.ui
.MenuSelectWidget( $.extend(
11216 $floatableContainer
: this.$element
,
11217 disabled
: this.isDisabled()
11223 this.connect( this, {
11224 change
: 'onInputChange',
11225 enter
: 'onInputEnter'
11227 this.dropdownButton
.connect( this, {
11228 click
: 'onDropdownButtonClick'
11230 this.menu
.connect( this, {
11231 choose
: 'onMenuChoose',
11232 add
: 'onMenuItemsChange',
11233 remove
: 'onMenuItemsChange',
11234 toggle
: 'onMenuToggle'
11238 this.$input
.attr( {
11240 'aria-owns': this.menu
.getElementId(),
11241 'aria-autocomplete': 'list'
11243 // Do not override options set via config.menu.items
11244 if ( config
.options
!== undefined ) {
11245 this.setOptions( config
.options
);
11247 this.$field
= $( '<div>' )
11248 .addClass( 'oo-ui-comboBoxInputWidget-field' )
11249 .append( this.$input
, this.dropdownButton
.$element
);
11251 .addClass( 'oo-ui-comboBoxInputWidget' )
11252 .append( this.$field
);
11253 this.$overlay
.append( this.menu
.$element
);
11254 this.onMenuItemsChange();
11259 OO
.inheritClass( OO
.ui
.ComboBoxInputWidget
, OO
.ui
.TextInputWidget
);
11264 * Get the combobox's menu.
11266 * @return {OO.ui.MenuSelectWidget} Menu widget
11268 OO
.ui
.ComboBoxInputWidget
.prototype.getMenu = function () {
11273 * Get the combobox's text input widget.
11275 * @return {OO.ui.TextInputWidget} Text input widget
11277 OO
.ui
.ComboBoxInputWidget
.prototype.getInput = function () {
11282 * Handle input change events.
11285 * @param {string} value New value
11287 OO
.ui
.ComboBoxInputWidget
.prototype.onInputChange = function ( value
) {
11288 var match
= this.menu
.findItemFromData( value
);
11290 this.menu
.selectItem( match
);
11291 if ( this.menu
.findHighlightedItem() ) {
11292 this.menu
.highlightItem( match
);
11295 if ( !this.isDisabled() ) {
11296 this.menu
.toggle( true );
11301 * Handle input enter events.
11305 OO
.ui
.ComboBoxInputWidget
.prototype.onInputEnter = function () {
11306 if ( !this.isDisabled() ) {
11307 this.menu
.toggle( false );
11312 * Handle button click events.
11316 OO
.ui
.ComboBoxInputWidget
.prototype.onDropdownButtonClick = function () {
11317 this.menu
.toggle();
11322 * Handle menu choose events.
11325 * @param {OO.ui.OptionWidget} item Chosen item
11327 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuChoose = function ( item
) {
11328 this.setValue( item
.getData() );
11332 * Handle menu item change events.
11336 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuItemsChange = function () {
11337 var match
= this.menu
.findItemFromData( this.getValue() );
11338 this.menu
.selectItem( match
);
11339 if ( this.menu
.findHighlightedItem() ) {
11340 this.menu
.highlightItem( match
);
11342 this.$element
.toggleClass( 'oo-ui-comboBoxInputWidget-empty', this.menu
.isEmpty() );
11346 * Handle menu toggle events.
11349 * @param {boolean} isVisible Open state of the menu
11351 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuToggle = function ( isVisible
) {
11352 this.$element
.toggleClass( 'oo-ui-comboBoxInputWidget-open', isVisible
);
11358 OO
.ui
.ComboBoxInputWidget
.prototype.setDisabled = function ( disabled
) {
11360 OO
.ui
.ComboBoxInputWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
11362 if ( this.dropdownButton
) {
11363 this.dropdownButton
.setDisabled( this.isDisabled() );
11366 this.menu
.setDisabled( this.isDisabled() );
11373 * Set the options available for this input.
11375 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
11378 OO
.ui
.ComboBoxInputWidget
.prototype.setOptions = function ( options
) {
11381 .addItems( options
.map( function ( opt
) {
11382 return new OO
.ui
.MenuOptionWidget( {
11384 label
: opt
.label
!== undefined ? opt
.label
: opt
.data
11392 * FieldLayouts are used with OO.ui.FieldsetLayout. Each FieldLayout requires a field-widget,
11393 * which is a widget that is specified by reference before any optional configuration settings.
11395 * Field layouts can be configured with help text and/or labels. Labels are aligned in one of four ways:
11397 * - **left**: The label is placed before the field-widget and aligned with the left margin.
11398 * A left-alignment is used for forms with many fields.
11399 * - **right**: The label is placed before the field-widget and aligned to the right margin.
11400 * A right-alignment is used for long but familiar forms which users tab through,
11401 * verifying the current field with a quick glance at the label.
11402 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
11403 * that users fill out from top to bottom.
11404 * - **inline**: The label is placed after the field-widget and aligned to the left.
11405 * An inline-alignment is best used with checkboxes or radio buttons.
11407 * Help text can either be:
11409 * - accessed via a help icon that appears in the upper right corner of the rendered field layout, or
11410 * - shown as a subtle explanation below the label.
11412 * If the help text is brief, or is essential to always espose it, set `helpInline` to `true`. If it
11413 * is long or not essential, leave `helpInline` to its default, `false`.
11415 * Please see the [OOUI documentation on MediaWiki] [1] for examples and more information.
11417 * [1]: https://www.mediawiki.org/wiki/OOUI/Layouts/Fields_and_Fieldsets
11420 * @extends OO.ui.Layout
11421 * @mixins OO.ui.mixin.LabelElement
11422 * @mixins OO.ui.mixin.TitledElement
11425 * @param {OO.ui.Widget} fieldWidget Field widget
11426 * @param {Object} [config] Configuration options
11427 * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top'
11429 * @cfg {Array} [errors] Error messages about the widget, which will be
11430 * displayed below the widget.
11431 * The array may contain strings or OO.ui.HtmlSnippet instances.
11432 * @cfg {Array} [notices] Notices about the widget, which will be displayed
11433 * below the widget.
11434 * The array may contain strings or OO.ui.HtmlSnippet instances.
11435 * These are more visible than `help` messages when `helpInline` is set, and so
11436 * might be good for transient messages.
11437 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified
11438 * and `helpInline` is `false`, a "help" icon will appear in the upper-right
11439 * corner of the rendered field; clicking it will display the text in a popup.
11440 * If `helpInline` is `true`, then a subtle description will be shown after the
11442 * @cfg {boolean} [helpInline=false] Whether or not the help should be inline,
11443 * or shown when the "help" icon is clicked.
11444 * @cfg {jQuery} [$overlay] Passed to OO.ui.PopupButtonWidget for help popup, if
11446 * See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
11448 * @throws {Error} An error is thrown if no widget is specified
11450 OO
.ui
.FieldLayout
= function OoUiFieldLayout( fieldWidget
, config
) {
11451 // Allow passing positional parameters inside the config object
11452 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
11453 config
= fieldWidget
;
11454 fieldWidget
= config
.fieldWidget
;
11457 // Make sure we have required constructor arguments
11458 if ( fieldWidget
=== undefined ) {
11459 throw new Error( 'Widget not found' );
11462 // Configuration initialization
11463 config
= $.extend( { align
: 'left', helpInline
: false }, config
);
11465 // Parent constructor
11466 OO
.ui
.FieldLayout
.parent
.call( this, config
);
11468 // Mixin constructors
11469 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, {
11470 $label
: $( '<label>' )
11472 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
11475 this.fieldWidget
= fieldWidget
;
11478 this.$field
= this.isFieldInline() ? $( '<span>' ) : $( '<div>' );
11479 this.$messages
= $( '<ul>' );
11480 this.$header
= $( '<span>' );
11481 this.$body
= $( '<div>' );
11483 this.helpInline
= config
.helpInline
;
11486 this.fieldWidget
.connect( this, { disable
: 'onFieldDisable' } );
11489 this.$help
= config
.help
?
11490 this.createHelpElement( config
.help
, config
.$overlay
) :
11492 if ( this.fieldWidget
.getInputId() ) {
11493 this.$label
.attr( 'for', this.fieldWidget
.getInputId() );
11494 if ( this.helpInline
) {
11495 this.$help
.attr( 'for', this.fieldWidget
.getInputId() );
11498 this.$label
.on( 'click', function () {
11499 this.fieldWidget
.simulateLabelClick();
11501 if ( this.helpInline
) {
11502 this.$help
.on( 'click', function () {
11503 this.fieldWidget
.simulateLabelClick();
11508 .addClass( 'oo-ui-fieldLayout' )
11509 .toggleClass( 'oo-ui-fieldLayout-disabled', this.fieldWidget
.isDisabled() )
11510 .append( this.$body
);
11511 this.$body
.addClass( 'oo-ui-fieldLayout-body' );
11512 this.$header
.addClass( 'oo-ui-fieldLayout-header' );
11513 this.$messages
.addClass( 'oo-ui-fieldLayout-messages' );
11515 .addClass( 'oo-ui-fieldLayout-field' )
11516 .append( this.fieldWidget
.$element
);
11518 this.setErrors( config
.errors
|| [] );
11519 this.setNotices( config
.notices
|| [] );
11520 this.setAlignment( config
.align
);
11521 // Call this again to take into account the widget's accessKey
11522 this.updateTitle();
11527 OO
.inheritClass( OO
.ui
.FieldLayout
, OO
.ui
.Layout
);
11528 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.LabelElement
);
11529 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.TitledElement
);
11534 * Handle field disable events.
11537 * @param {boolean} value Field is disabled
11539 OO
.ui
.FieldLayout
.prototype.onFieldDisable = function ( value
) {
11540 this.$element
.toggleClass( 'oo-ui-fieldLayout-disabled', value
);
11544 * Get the widget contained by the field.
11546 * @return {OO.ui.Widget} Field widget
11548 OO
.ui
.FieldLayout
.prototype.getField = function () {
11549 return this.fieldWidget
;
11553 * Return `true` if the given field widget can be used with `'inline'` alignment (see
11554 * #setAlignment). Return `false` if it can't or if this can't be determined.
11556 * @return {boolean}
11558 OO
.ui
.FieldLayout
.prototype.isFieldInline = function () {
11559 // This is very simplistic, but should be good enough.
11560 return this.getField().$element
.prop( 'tagName' ).toLowerCase() === 'span';
11565 * @param {string} kind 'error' or 'notice'
11566 * @param {string|OO.ui.HtmlSnippet} text
11569 OO
.ui
.FieldLayout
.prototype.makeMessage = function ( kind
, text
) {
11570 var $listItem
, $icon
, message
;
11571 $listItem
= $( '<li>' );
11572 if ( kind
=== 'error' ) {
11573 $icon
= new OO
.ui
.IconWidget( { icon
: 'alert', flags
: [ 'warning' ] } ).$element
;
11574 $listItem
.attr( 'role', 'alert' );
11575 } else if ( kind
=== 'notice' ) {
11576 $icon
= new OO
.ui
.IconWidget( { icon
: 'notice' } ).$element
;
11580 message
= new OO
.ui
.LabelWidget( { label
: text
} );
11582 .append( $icon
, message
.$element
)
11583 .addClass( 'oo-ui-fieldLayout-messages-' + kind
);
11588 * Set the field alignment mode.
11591 * @param {string} value Alignment mode, either 'left', 'right', 'top' or 'inline'
11594 OO
.ui
.FieldLayout
.prototype.setAlignment = function ( value
) {
11595 if ( value
!== this.align
) {
11596 // Default to 'left'
11597 if ( [ 'left', 'right', 'top', 'inline' ].indexOf( value
) === -1 ) {
11601 if ( value
=== 'inline' && !this.isFieldInline() ) {
11604 // Reorder elements
11606 if ( this.helpInline
) {
11607 if ( value
=== 'top' ) {
11608 this.$header
.append( this.$label
);
11609 this.$body
.append( this.$header
, this.$field
, this.$help
);
11610 } else if ( value
=== 'inline' ) {
11611 this.$header
.append( this.$label
, this.$help
);
11612 this.$body
.append( this.$field
, this.$header
);
11614 this.$header
.append( this.$label
, this.$help
);
11615 this.$body
.append( this.$header
, this.$field
);
11618 if ( value
=== 'top' ) {
11619 this.$header
.append( this.$help
, this.$label
);
11620 this.$body
.append( this.$header
, this.$field
);
11621 } else if ( value
=== 'inline' ) {
11622 this.$header
.append( this.$help
, this.$label
);
11623 this.$body
.append( this.$field
, this.$header
);
11625 this.$header
.append( this.$label
);
11626 this.$body
.append( this.$header
, this.$help
, this.$field
);
11629 // Set classes. The following classes can be used here:
11630 // * oo-ui-fieldLayout-align-left
11631 // * oo-ui-fieldLayout-align-right
11632 // * oo-ui-fieldLayout-align-top
11633 // * oo-ui-fieldLayout-align-inline
11634 if ( this.align
) {
11635 this.$element
.removeClass( 'oo-ui-fieldLayout-align-' + this.align
);
11637 this.$element
.addClass( 'oo-ui-fieldLayout-align-' + value
);
11638 this.align
= value
;
11645 * Set the list of error messages.
11647 * @param {Array} errors Error messages about the widget, which will be displayed below the widget.
11648 * The array may contain strings or OO.ui.HtmlSnippet instances.
11651 OO
.ui
.FieldLayout
.prototype.setErrors = function ( errors
) {
11652 this.errors
= errors
.slice();
11653 this.updateMessages();
11658 * Set the list of notice messages.
11660 * @param {Array} notices Notices about the widget, which will be displayed below the widget.
11661 * The array may contain strings or OO.ui.HtmlSnippet instances.
11664 OO
.ui
.FieldLayout
.prototype.setNotices = function ( notices
) {
11665 this.notices
= notices
.slice();
11666 this.updateMessages();
11671 * Update the rendering of error and notice messages.
11675 OO
.ui
.FieldLayout
.prototype.updateMessages = function () {
11677 this.$messages
.empty();
11679 if ( this.errors
.length
|| this.notices
.length
) {
11680 this.$body
.after( this.$messages
);
11682 this.$messages
.remove();
11686 for ( i
= 0; i
< this.notices
.length
; i
++ ) {
11687 this.$messages
.append( this.makeMessage( 'notice', this.notices
[ i
] ) );
11689 for ( i
= 0; i
< this.errors
.length
; i
++ ) {
11690 this.$messages
.append( this.makeMessage( 'error', this.errors
[ i
] ) );
11695 * Include information about the widget's accessKey in our title. TitledElement calls this method.
11696 * (This is a bit of a hack.)
11699 * @param {string} title Tooltip label for 'title' attribute
11702 OO
.ui
.FieldLayout
.prototype.formatTitleWithAccessKey = function ( title
) {
11703 if ( this.fieldWidget
&& this.fieldWidget
.formatTitleWithAccessKey
) {
11704 return this.fieldWidget
.formatTitleWithAccessKey( title
);
11710 * Creates and returns the help element. Also sets the `aria-describedby`
11711 * attribute on the main element of the `fieldWidget`.
11714 * @param {string|OO.ui.HtmlSnippet} [help] Help text.
11715 * @param {jQuery} [$overlay] Passed to OO.ui.PopupButtonWidget for help popup.
11716 * @return {jQuery} The element that should become `this.$help`.
11718 OO
.ui
.FieldLayout
.prototype.createHelpElement = function ( help
, $overlay
) {
11719 var helpId
, helpWidget
;
11721 if ( this.helpInline
) {
11722 helpWidget
= new OO
.ui
.LabelWidget( {
11724 classes
: [ 'oo-ui-inline-help' ]
11727 helpId
= helpWidget
.getElementId();
11729 helpWidget
= new OO
.ui
.PopupButtonWidget( {
11730 $overlay
: $overlay
,
11734 classes
: [ 'oo-ui-fieldLayout-help' ],
11737 label
: OO
.ui
.msg( 'ooui-field-help' )
11739 if ( help
instanceof OO
.ui
.HtmlSnippet
) {
11740 helpWidget
.getPopup().$body
.html( help
.toString() );
11742 helpWidget
.getPopup().$body
.text( help
);
11745 helpId
= helpWidget
.getPopup().getBodyId();
11748 // Set the 'aria-describedby' attribute on the fieldWidget
11749 // Preference given to an input or a button
11751 this.fieldWidget
.$input
||
11752 this.fieldWidget
.$button
||
11753 this.fieldWidget
.$element
11754 ).attr( 'aria-describedby', helpId
);
11756 return helpWidget
.$element
;
11760 * ActionFieldLayouts are used with OO.ui.FieldsetLayout. The layout consists of a field-widget, a button,
11761 * and an optional label and/or help text. The field-widget (e.g., a {@link OO.ui.TextInputWidget TextInputWidget}),
11762 * is required and is specified before any optional configuration settings.
11764 * Labels can be aligned in one of four ways:
11766 * - **left**: The label is placed before the field-widget and aligned with the left margin.
11767 * A left-alignment is used for forms with many fields.
11768 * - **right**: The label is placed before the field-widget and aligned to the right margin.
11769 * A right-alignment is used for long but familiar forms which users tab through,
11770 * verifying the current field with a quick glance at the label.
11771 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
11772 * that users fill out from top to bottom.
11773 * - **inline**: The label is placed after the field-widget and aligned to the left.
11774 * An inline-alignment is best used with checkboxes or radio buttons.
11776 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout when help
11777 * text is specified.
11780 * // Example of an ActionFieldLayout
11781 * var actionFieldLayout = new OO.ui.ActionFieldLayout(
11782 * new OO.ui.TextInputWidget( {
11783 * placeholder: 'Field widget'
11785 * new OO.ui.ButtonWidget( {
11789 * label: 'An ActionFieldLayout. This label is aligned top',
11791 * help: 'This is help text'
11795 * $( 'body' ).append( actionFieldLayout.$element );
11798 * @extends OO.ui.FieldLayout
11801 * @param {OO.ui.Widget} fieldWidget Field widget
11802 * @param {OO.ui.ButtonWidget} buttonWidget Button widget
11803 * @param {Object} config
11805 OO
.ui
.ActionFieldLayout
= function OoUiActionFieldLayout( fieldWidget
, buttonWidget
, config
) {
11806 // Allow passing positional parameters inside the config object
11807 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
11808 config
= fieldWidget
;
11809 fieldWidget
= config
.fieldWidget
;
11810 buttonWidget
= config
.buttonWidget
;
11813 // Parent constructor
11814 OO
.ui
.ActionFieldLayout
.parent
.call( this, fieldWidget
, config
);
11817 this.buttonWidget
= buttonWidget
;
11818 this.$button
= $( '<span>' );
11819 this.$input
= this.isFieldInline() ? $( '<span>' ) : $( '<div>' );
11823 .addClass( 'oo-ui-actionFieldLayout' );
11825 .addClass( 'oo-ui-actionFieldLayout-button' )
11826 .append( this.buttonWidget
.$element
);
11828 .addClass( 'oo-ui-actionFieldLayout-input' )
11829 .append( this.fieldWidget
.$element
);
11831 .append( this.$input
, this.$button
);
11836 OO
.inheritClass( OO
.ui
.ActionFieldLayout
, OO
.ui
.FieldLayout
);
11839 * FieldsetLayouts are composed of one or more {@link OO.ui.FieldLayout FieldLayouts},
11840 * which each contain an individual widget and, optionally, a label. Each Fieldset can be
11841 * configured with a label as well. For more information and examples,
11842 * please see the [OOUI documentation on MediaWiki][1].
11845 * // Example of a fieldset layout
11846 * var input1 = new OO.ui.TextInputWidget( {
11847 * placeholder: 'A text input field'
11850 * var input2 = new OO.ui.TextInputWidget( {
11851 * placeholder: 'A text input field'
11854 * var fieldset = new OO.ui.FieldsetLayout( {
11855 * label: 'Example of a fieldset layout'
11858 * fieldset.addItems( [
11859 * new OO.ui.FieldLayout( input1, {
11860 * label: 'Field One'
11862 * new OO.ui.FieldLayout( input2, {
11863 * label: 'Field Two'
11866 * $( 'body' ).append( fieldset.$element );
11868 * [1]: https://www.mediawiki.org/wiki/OOUI/Layouts/Fields_and_Fieldsets
11871 * @extends OO.ui.Layout
11872 * @mixins OO.ui.mixin.IconElement
11873 * @mixins OO.ui.mixin.LabelElement
11874 * @mixins OO.ui.mixin.GroupElement
11877 * @param {Object} [config] Configuration options
11878 * @cfg {OO.ui.FieldLayout[]} [items] An array of fields to add to the fieldset. See OO.ui.FieldLayout for more information about fields.
11879 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
11880 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
11881 * For important messages, you are advised to use `notices`, as they are always shown.
11882 * @cfg {jQuery} [$overlay] Passed to OO.ui.PopupButtonWidget for help popup, if `help` is given.
11883 * See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
11885 OO
.ui
.FieldsetLayout
= function OoUiFieldsetLayout( config
) {
11886 // Configuration initialization
11887 config
= config
|| {};
11889 // Parent constructor
11890 OO
.ui
.FieldsetLayout
.parent
.call( this, config
);
11892 // Mixin constructors
11893 OO
.ui
.mixin
.IconElement
.call( this, config
);
11894 OO
.ui
.mixin
.LabelElement
.call( this, config
);
11895 OO
.ui
.mixin
.GroupElement
.call( this, config
);
11898 this.$header
= $( '<legend>' );
11899 if ( config
.help
) {
11900 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
11901 $overlay
: config
.$overlay
,
11905 classes
: [ 'oo-ui-fieldsetLayout-help' ],
11908 label
: OO
.ui
.msg( 'ooui-field-help' )
11910 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
11911 this.popupButtonWidget
.getPopup().$body
.html( config
.help
.toString() );
11913 this.popupButtonWidget
.getPopup().$body
.text( config
.help
);
11915 this.$help
= this.popupButtonWidget
.$element
;
11917 this.$help
= $( [] );
11922 .addClass( 'oo-ui-fieldsetLayout-header' )
11923 .append( this.$icon
, this.$label
, this.$help
);
11924 this.$group
.addClass( 'oo-ui-fieldsetLayout-group' );
11926 .addClass( 'oo-ui-fieldsetLayout' )
11927 .prepend( this.$header
, this.$group
);
11928 if ( Array
.isArray( config
.items
) ) {
11929 this.addItems( config
.items
);
11935 OO
.inheritClass( OO
.ui
.FieldsetLayout
, OO
.ui
.Layout
);
11936 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.IconElement
);
11937 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.LabelElement
);
11938 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.GroupElement
);
11940 /* Static Properties */
11946 OO
.ui
.FieldsetLayout
.static.tagName
= 'fieldset';
11949 * FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts} when you intend to use browser-based
11950 * form submission for the fields instead of handling them in JavaScript. Form layouts can be configured with an
11951 * HTML form action, an encoding type, and a method using the #action, #enctype, and #method configs, respectively.
11952 * See the [OOUI documentation on MediaWiki] [1] for more information and examples.
11954 * Only widgets from the {@link OO.ui.InputWidget InputWidget} family support form submission. It
11955 * includes standard form elements like {@link OO.ui.CheckboxInputWidget checkboxes}, {@link
11956 * OO.ui.RadioInputWidget radio buttons} and {@link OO.ui.TextInputWidget text fields}, as well as
11957 * some fancier controls. Some controls have both regular and InputWidget variants, for example
11958 * OO.ui.DropdownWidget and OO.ui.DropdownInputWidget – only the latter support form submission and
11959 * often have simplified APIs to match the capabilities of HTML forms.
11960 * See the [OOUI documentation on MediaWiki] [2] for more information about InputWidgets.
11962 * [1]: https://www.mediawiki.org/wiki/OOUI/Layouts/Forms
11963 * [2]: https://www.mediawiki.org/wiki/OOUI/Widgets/Inputs
11966 * // Example of a form layout that wraps a fieldset layout
11967 * var input1 = new OO.ui.TextInputWidget( {
11968 * placeholder: 'Username'
11970 * var input2 = new OO.ui.TextInputWidget( {
11971 * placeholder: 'Password',
11974 * var submit = new OO.ui.ButtonInputWidget( {
11978 * var fieldset = new OO.ui.FieldsetLayout( {
11979 * label: 'A form layout'
11981 * fieldset.addItems( [
11982 * new OO.ui.FieldLayout( input1, {
11983 * label: 'Username',
11986 * new OO.ui.FieldLayout( input2, {
11987 * label: 'Password',
11990 * new OO.ui.FieldLayout( submit )
11992 * var form = new OO.ui.FormLayout( {
11993 * items: [ fieldset ],
11994 * action: '/api/formhandler',
11997 * $( 'body' ).append( form.$element );
12000 * @extends OO.ui.Layout
12001 * @mixins OO.ui.mixin.GroupElement
12004 * @param {Object} [config] Configuration options
12005 * @cfg {string} [method] HTML form `method` attribute
12006 * @cfg {string} [action] HTML form `action` attribute
12007 * @cfg {string} [enctype] HTML form `enctype` attribute
12008 * @cfg {OO.ui.FieldsetLayout[]} [items] Fieldset layouts to add to the form layout.
12010 OO
.ui
.FormLayout
= function OoUiFormLayout( config
) {
12013 // Configuration initialization
12014 config
= config
|| {};
12016 // Parent constructor
12017 OO
.ui
.FormLayout
.parent
.call( this, config
);
12019 // Mixin constructors
12020 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
12023 this.$element
.on( 'submit', this.onFormSubmit
.bind( this ) );
12025 // Make sure the action is safe
12026 action
= config
.action
;
12027 if ( action
!== undefined && !OO
.ui
.isSafeUrl( action
) ) {
12028 action
= './' + action
;
12033 .addClass( 'oo-ui-formLayout' )
12035 method
: config
.method
,
12037 enctype
: config
.enctype
12039 if ( Array
.isArray( config
.items
) ) {
12040 this.addItems( config
.items
);
12046 OO
.inheritClass( OO
.ui
.FormLayout
, OO
.ui
.Layout
);
12047 OO
.mixinClass( OO
.ui
.FormLayout
, OO
.ui
.mixin
.GroupElement
);
12052 * A 'submit' event is emitted when the form is submitted.
12057 /* Static Properties */
12063 OO
.ui
.FormLayout
.static.tagName
= 'form';
12068 * Handle form submit events.
12071 * @param {jQuery.Event} e Submit event
12074 OO
.ui
.FormLayout
.prototype.onFormSubmit = function () {
12075 if ( this.emit( 'submit' ) ) {
12081 * PanelLayouts expand to cover the entire area of their parent. They can be configured with scrolling, padding,
12082 * and a frame, and are often used together with {@link OO.ui.StackLayout StackLayouts}.
12085 * // Example of a panel layout
12086 * var panel = new OO.ui.PanelLayout( {
12090 * $content: $( '<p>A panel layout with padding and a frame.</p>' )
12092 * $( 'body' ).append( panel.$element );
12095 * @extends OO.ui.Layout
12098 * @param {Object} [config] Configuration options
12099 * @cfg {boolean} [scrollable=false] Allow vertical scrolling
12100 * @cfg {boolean} [padded=false] Add padding between the content and the edges of the panel.
12101 * @cfg {boolean} [expanded=true] Expand the panel to fill the entire parent element.
12102 * @cfg {boolean} [framed=false] Render the panel with a frame to visually separate it from outside content.
12104 OO
.ui
.PanelLayout
= function OoUiPanelLayout( config
) {
12105 // Configuration initialization
12106 config
= $.extend( {
12113 // Parent constructor
12114 OO
.ui
.PanelLayout
.parent
.call( this, config
);
12117 this.$element
.addClass( 'oo-ui-panelLayout' );
12118 if ( config
.scrollable
) {
12119 this.$element
.addClass( 'oo-ui-panelLayout-scrollable' );
12121 if ( config
.padded
) {
12122 this.$element
.addClass( 'oo-ui-panelLayout-padded' );
12124 if ( config
.expanded
) {
12125 this.$element
.addClass( 'oo-ui-panelLayout-expanded' );
12127 if ( config
.framed
) {
12128 this.$element
.addClass( 'oo-ui-panelLayout-framed' );
12134 OO
.inheritClass( OO
.ui
.PanelLayout
, OO
.ui
.Layout
);
12139 * Focus the panel layout
12141 * The default implementation just focuses the first focusable element in the panel
12143 OO
.ui
.PanelLayout
.prototype.focus = function () {
12144 OO
.ui
.findFocusable( this.$element
).focus();
12148 * HorizontalLayout arranges its contents in a single line (using `display: inline-block` for its
12149 * items), with small margins between them. Convenient when you need to put a number of block-level
12150 * widgets on a single line next to each other.
12152 * Note that inline elements, such as OO.ui.ButtonWidgets, do not need this wrapper.
12155 * // HorizontalLayout with a text input and a label
12156 * var layout = new OO.ui.HorizontalLayout( {
12158 * new OO.ui.LabelWidget( { label: 'Label' } ),
12159 * new OO.ui.TextInputWidget( { value: 'Text' } )
12162 * $( 'body' ).append( layout.$element );
12165 * @extends OO.ui.Layout
12166 * @mixins OO.ui.mixin.GroupElement
12169 * @param {Object} [config] Configuration options
12170 * @cfg {OO.ui.Widget[]|OO.ui.Layout[]} [items] Widgets or other layouts to add to the layout.
12172 OO
.ui
.HorizontalLayout
= function OoUiHorizontalLayout( config
) {
12173 // Configuration initialization
12174 config
= config
|| {};
12176 // Parent constructor
12177 OO
.ui
.HorizontalLayout
.parent
.call( this, config
);
12179 // Mixin constructors
12180 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
12183 this.$element
.addClass( 'oo-ui-horizontalLayout' );
12184 if ( Array
.isArray( config
.items
) ) {
12185 this.addItems( config
.items
);
12191 OO
.inheritClass( OO
.ui
.HorizontalLayout
, OO
.ui
.Layout
);
12192 OO
.mixinClass( OO
.ui
.HorizontalLayout
, OO
.ui
.mixin
.GroupElement
);
12195 * NumberInputWidgets combine a {@link OO.ui.TextInputWidget text input} (where a value
12196 * can be entered manually) and two {@link OO.ui.ButtonWidget button widgets}
12197 * (to adjust the value in increments) to allow the user to enter a number.
12200 * // Example: A NumberInputWidget.
12201 * var numberInput = new OO.ui.NumberInputWidget( {
12202 * label: 'NumberInputWidget',
12203 * input: { value: 5 },
12207 * $( 'body' ).append( numberInput.$element );
12210 * @extends OO.ui.TextInputWidget
12213 * @param {Object} [config] Configuration options
12214 * @cfg {Object} [minusButton] Configuration options to pass to the
12215 * {@link OO.ui.ButtonWidget decrementing button widget}.
12216 * @cfg {Object} [plusButton] Configuration options to pass to the
12217 * {@link OO.ui.ButtonWidget incrementing button widget}.
12218 * @cfg {number} [min=-Infinity] Minimum allowed value
12219 * @cfg {number} [max=Infinity] Maximum allowed value
12220 * @cfg {number|null} [step] If specified, the field only accepts values that are multiples of this.
12221 * @cfg {number} [buttonStep=step||1] Delta when using the buttons or up/down arrow keys.
12222 * Defaults to `step` if specified, otherwise `1`.
12223 * @cfg {number} [pageStep=10*buttonStep] Delta when using the page-up/page-down keys.
12224 * Defaults to 10 times `buttonStep`.
12225 * @cfg {boolean} [showButtons=true] Whether to show the plus and minus buttons.
12227 OO
.ui
.NumberInputWidget
= function OoUiNumberInputWidget( config
) {
12228 var $field
= $( '<div>' )
12229 .addClass( 'oo-ui-numberInputWidget-field' );
12231 // Configuration initialization
12232 config
= $.extend( {
12238 // For backward compatibility
12239 $.extend( config
, config
.input
);
12242 // Parent constructor
12243 OO
.ui
.NumberInputWidget
.parent
.call( this, $.extend( config
, {
12247 if ( config
.showButtons
) {
12248 this.minusButton
= new OO
.ui
.ButtonWidget( $.extend(
12250 disabled
: this.isDisabled(),
12252 classes
: [ 'oo-ui-numberInputWidget-minusButton' ],
12257 this.minusButton
.$element
.attr( 'aria-hidden', 'true' );
12258 this.plusButton
= new OO
.ui
.ButtonWidget( $.extend(
12260 disabled
: this.isDisabled(),
12262 classes
: [ 'oo-ui-numberInputWidget-plusButton' ],
12267 this.plusButton
.$element
.attr( 'aria-hidden', 'true' );
12272 keydown
: this.onKeyDown
.bind( this ),
12273 'wheel mousewheel DOMMouseScroll': this.onWheel
.bind( this )
12275 if ( config
.showButtons
) {
12276 this.plusButton
.connect( this, {
12277 click
: [ 'onButtonClick', +1 ]
12279 this.minusButton
.connect( this, {
12280 click
: [ 'onButtonClick', -1 ]
12285 $field
.append( this.$input
);
12286 if ( config
.showButtons
) {
12288 .prepend( this.minusButton
.$element
)
12289 .append( this.plusButton
.$element
);
12293 if ( config
.allowInteger
|| config
.isInteger
) {
12294 // Backward compatibility
12297 this.setRange( config
.min
, config
.max
);
12298 this.setStep( config
.buttonStep
, config
.pageStep
, config
.step
);
12299 // Set the validation method after we set step and range
12300 // so that it doesn't immediately call setValidityFlag
12301 this.setValidation( this.validateNumber
.bind( this ) );
12304 .addClass( 'oo-ui-numberInputWidget' )
12305 .toggleClass( 'oo-ui-numberInputWidget-buttoned', config
.showButtons
)
12311 OO
.inheritClass( OO
.ui
.NumberInputWidget
, OO
.ui
.TextInputWidget
);
12315 // Backward compatibility
12316 OO
.ui
.NumberInputWidget
.prototype.setAllowInteger = function ( flag
) {
12317 this.setStep( flag
? 1 : null );
12319 // Backward compatibility
12320 OO
.ui
.NumberInputWidget
.prototype.setIsInteger
= OO
.ui
.NumberInputWidget
.prototype.setAllowInteger
;
12322 // Backward compatibility
12323 OO
.ui
.NumberInputWidget
.prototype.getAllowInteger = function () {
12324 return this.step
=== 1;
12326 // Backward compatibility
12327 OO
.ui
.NumberInputWidget
.prototype.getIsInteger
= OO
.ui
.NumberInputWidget
.prototype.getAllowInteger
;
12330 * Set the range of allowed values
12332 * @param {number} min Minimum allowed value
12333 * @param {number} max Maximum allowed value
12335 OO
.ui
.NumberInputWidget
.prototype.setRange = function ( min
, max
) {
12337 throw new Error( 'Minimum (' + min
+ ') must not be greater than maximum (' + max
+ ')' );
12341 this.$input
.attr( 'min', this.min
);
12342 this.$input
.attr( 'max', this.max
);
12343 this.setValidityFlag();
12347 * Get the current range
12349 * @return {number[]} Minimum and maximum values
12351 OO
.ui
.NumberInputWidget
.prototype.getRange = function () {
12352 return [ this.min
, this.max
];
12356 * Set the stepping deltas
12358 * @param {number} [buttonStep=step||1] Delta when using the buttons or up/down arrow keys.
12359 * Defaults to `step` if specified, otherwise `1`.
12360 * @param {number} [pageStep=10*buttonStep] Delta when using the page-up/page-down keys.
12361 * Defaults to 10 times `buttonStep`.
12362 * @param {number|null} [step] If specified, the field only accepts values that are multiples of this.
12364 OO
.ui
.NumberInputWidget
.prototype.setStep = function ( buttonStep
, pageStep
, step
) {
12365 if ( buttonStep
=== undefined ) {
12366 buttonStep
= step
|| 1;
12368 if ( pageStep
=== undefined ) {
12369 pageStep
= 10 * buttonStep
;
12371 if ( step
!== null && step
<= 0 ) {
12372 throw new Error( 'Step value, if given, must be positive' );
12374 if ( buttonStep
<= 0 ) {
12375 throw new Error( 'Button step value must be positive' );
12377 if ( pageStep
<= 0 ) {
12378 throw new Error( 'Page step value must be positive' );
12381 this.buttonStep
= buttonStep
;
12382 this.pageStep
= pageStep
;
12383 this.$input
.attr( 'step', this.step
|| 'any' );
12384 this.setValidityFlag();
12390 OO
.ui
.NumberInputWidget
.prototype.setValue = function ( value
) {
12391 if ( value
=== '' ) {
12392 // Some browsers allow a value in the input even if there isn't one reported by $input.val()
12393 // so here we make sure an 'empty' value is actually displayed as such.
12394 this.$input
.val( '' );
12396 return OO
.ui
.NumberInputWidget
.parent
.prototype.setValue
.call( this, value
);
12400 * Get the current stepping values
12402 * @return {number[]} Button step, page step, and validity step
12404 OO
.ui
.NumberInputWidget
.prototype.getStep = function () {
12405 return [ this.buttonStep
, this.pageStep
, this.step
];
12409 * Get the current value of the widget as a number
12411 * @return {number} May be NaN, or an invalid number
12413 OO
.ui
.NumberInputWidget
.prototype.getNumericValue = function () {
12414 return +this.getValue();
12418 * Adjust the value of the widget
12420 * @param {number} delta Adjustment amount
12422 OO
.ui
.NumberInputWidget
.prototype.adjustValue = function ( delta
) {
12423 var n
, v
= this.getNumericValue();
12426 if ( isNaN( delta
) || !isFinite( delta
) ) {
12427 throw new Error( 'Delta must be a finite number' );
12430 if ( isNaN( v
) ) {
12434 n
= Math
.max( Math
.min( n
, this.max
), this.min
);
12436 n
= Math
.round( n
/ this.step
) * this.step
;
12441 this.setValue( n
);
12448 * @param {string} value Field value
12449 * @return {boolean}
12451 OO
.ui
.NumberInputWidget
.prototype.validateNumber = function ( value
) {
12453 if ( value
=== '' ) {
12454 return !this.isRequired();
12457 if ( isNaN( n
) || !isFinite( n
) ) {
12461 if ( this.step
&& Math
.floor( n
/ this.step
) !== n
/ this.step
) {
12465 if ( n
< this.min
|| n
> this.max
) {
12473 * Handle mouse click events.
12476 * @param {number} dir +1 or -1
12478 OO
.ui
.NumberInputWidget
.prototype.onButtonClick = function ( dir
) {
12479 this.adjustValue( dir
* this.buttonStep
);
12483 * Handle mouse wheel events.
12486 * @param {jQuery.Event} event
12488 OO
.ui
.NumberInputWidget
.prototype.onWheel = function ( event
) {
12491 if ( !this.isDisabled() && this.$input
.is( ':focus' ) ) {
12492 // Standard 'wheel' event
12493 if ( event
.originalEvent
.deltaMode
!== undefined ) {
12494 this.sawWheelEvent
= true;
12496 if ( event
.originalEvent
.deltaY
) {
12497 delta
= -event
.originalEvent
.deltaY
;
12498 } else if ( event
.originalEvent
.deltaX
) {
12499 delta
= event
.originalEvent
.deltaX
;
12502 // Non-standard events
12503 if ( !this.sawWheelEvent
) {
12504 if ( event
.originalEvent
.wheelDeltaX
) {
12505 delta
= -event
.originalEvent
.wheelDeltaX
;
12506 } else if ( event
.originalEvent
.wheelDeltaY
) {
12507 delta
= event
.originalEvent
.wheelDeltaY
;
12508 } else if ( event
.originalEvent
.wheelDelta
) {
12509 delta
= event
.originalEvent
.wheelDelta
;
12510 } else if ( event
.originalEvent
.detail
) {
12511 delta
= -event
.originalEvent
.detail
;
12516 delta
= delta
< 0 ? -1 : 1;
12517 this.adjustValue( delta
* this.buttonStep
);
12525 * Handle key down events.
12528 * @param {jQuery.Event} e Key down event
12530 OO
.ui
.NumberInputWidget
.prototype.onKeyDown = function ( e
) {
12531 if ( !this.isDisabled() ) {
12532 switch ( e
.which
) {
12533 case OO
.ui
.Keys
.UP
:
12534 this.adjustValue( this.buttonStep
);
12536 case OO
.ui
.Keys
.DOWN
:
12537 this.adjustValue( -this.buttonStep
);
12539 case OO
.ui
.Keys
.PAGEUP
:
12540 this.adjustValue( this.pageStep
);
12542 case OO
.ui
.Keys
.PAGEDOWN
:
12543 this.adjustValue( -this.pageStep
);
12552 OO
.ui
.NumberInputWidget
.prototype.setDisabled = function ( disabled
) {
12554 OO
.ui
.NumberInputWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
12556 if ( this.minusButton
) {
12557 this.minusButton
.setDisabled( this.isDisabled() );
12559 if ( this.plusButton
) {
12560 this.plusButton
.setDisabled( this.isDisabled() );
12568 //# sourceMappingURL=oojs-ui-core.js.map.json