Button
The button interface. Implemented by, among others, ButtonView,
SplitButtonView and
DropdownButtonView.
Properties
-
ariaLabel : string | undefinedmodule:ui/button/button~Button#ariaLabel(Optional) The ARIA property reflected by the
aria-labelDOM attribute used by assistive technologies. -
ariaLabelledBy : string | undefinedmodule:ui/button/button~Button#ariaLabelledBy(Optional) The ARIA property reflected by the
aria-ariaLabelledByDOM attribute used by assistive technologies. -
class : undefined | stringmodule:ui/button/button~Button#class(Optional) The additional CSS class set on the button.
-
icon : undefined | stringmodule:ui/button/button~Button#icon(Optional) An XML content of the icon. When defined, an
iconViewshould be added to the button.The user must provide the entire XML string, not just the path. See the UI library guide for details.
-
isEnabled : booleanmodule:ui/button/button~Button#isEnabledControls whether the button view is enabled, i.e. it can be clicked and execute an action.
To change the "on" state of the button, use
isOninstead.Defaults to
true -
isOn : booleanmodule:ui/button/button~Button#isOnControls whether the button view is "on". It makes sense when a feature it represents is currently active, e.g. a bold button is "on" when the selection is in the bold text.
To disable the button, use
isEnabledinstead.Defaults to
true -
isToggleable : booleanmodule:ui/button/button~Button#isToggleableControls whether the button view is a toggle button (two–state) for assistive technologies.
Defaults to
false -
isVisible : booleanmodule:ui/button/button~Button#isVisibleControls whether the button view is visible. Visible by default, buttons are hidden using a CSS class.
Defaults to
true -
keystroke : undefined | stringmodule:ui/button/button~Button#keystroke(Optional) The keystroke associated with the button, i.e. CTRL+B, in the string format compatible with
keyboard.Note: Use
withKeystrokeif you want to display the keystroke information next to the label. -
label : undefined | stringmodule:ui/button/button~Button#label -
labelStyle : undefined | stringmodule:ui/button/button~Button#labelStyle(Optional) The value of the
styleattribute of the label. -
role : string | undefinedmodule:ui/button/button~Button#role(Optional) The property reflected by the
roleDOM attribute to be used by assistive technologies. -
tabindex : numbermodule:ui/button/button~Button#tabindex(Optional) Controls the
tabindexHTML attribute of the button. By default, the button is focusable but does not included in the Tab order.Defaults to
-1 -
tooltip : string | boolean | ( label: string, keystroke: undefined | string ) => stringmodule:ui/button/button~Button#tooltip(Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.
- If defined as a
Boolean(e.g.true), then combination oflabelandkeystrokewill be set as a tooltip. - If defined as a
String, tooltip will equal the exact text of thatString. - If defined as a
Function,labelandkeystrokewill be passed to that function, which is to return a string with the tooltip text.
const view = new ButtonView( locale ); view.tooltip = ( label, keystroke ) => `A tooltip for ${ label } and ${ keystroke }.`Copy codeDefaults to
false - If defined as a
-
tooltipPosition : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'module:ui/button/button~Button#tooltipPosition(Optional) The position of the tooltip. See
TooltipManagerto learn more about the tooltip system.Note: It makes sense only when the
tooltipattribute is defined.Defaults to
's' -
type : 'button' | 'menu' | 'reset' | 'submit'module:ui/button/button~Button#type -
withKeystroke : booleanmodule:ui/button/button~Button#withKeystroke -
withText : booleanmodule:ui/button/button~Button#withText(Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
Defaults to
false
Events
-
change:ariaLabel( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:ariaLabelFired when the
ariaLabelproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
ariaLabel).value : stringNew value of the
ariaLabelproperty with given key ornull, if operation should remove property.oldValue : stringOld value of the
ariaLabelproperty with given key ornull, if property was not set before.
-
change:ariaLabelledBy( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:ariaLabelledByFired when the
ariaLabelledByproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
ariaLabelledBy).value : stringNew value of the
ariaLabelledByproperty with given key ornull, if operation should remove property.oldValue : stringOld value of the
ariaLabelledByproperty with given key ornull, if property was not set before.
-
change:class( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:classFired when the
classproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
class).value : undefined | stringNew value of the
classproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
classproperty with given key ornull, if property was not set before.
-
change:icon( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:iconFired when the
iconproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
icon).value : undefined | stringNew value of the
iconproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
iconproperty with given key ornull, if property was not set before.
-
change:isEnabled( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:isEnabledFired when the
isEnabledproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
isEnabled).value : booleanNew value of the
isEnabledproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
isEnabledproperty with given key ornull, if property was not set before.
-
change:isOn( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:isOnFired when the
isOnproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
isOn).value : booleanNew value of the
isOnproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
isOnproperty with given key ornull, if property was not set before.
-
change:isToggleable( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:isToggleableFired when the
isToggleableproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
isToggleable).value : booleanNew value of the
isToggleableproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
isToggleableproperty with given key ornull, if property was not set before.
-
change:isVisible( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:isVisibleFired when the
isVisibleproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
isVisible).value : booleanNew value of the
isVisibleproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
isVisibleproperty with given key ornull, if property was not set before.
-
change:keystroke( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:keystrokeFired when the
keystrokeproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
keystroke).value : undefined | stringNew value of the
keystrokeproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
keystrokeproperty with given key ornull, if property was not set before.
-
change:label( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:labelFired when the
labelproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
label).value : undefined | stringNew value of the
labelproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
labelproperty with given key ornull, if property was not set before.
-
change:labelStyle( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:labelStyleFired when the
labelStyleproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
labelStyle).value : undefined | stringNew value of the
labelStyleproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
labelStyleproperty with given key ornull, if property was not set before.
-
change:role( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:roleFired when the
roleproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
role).value : stringNew value of the
roleproperty with given key ornull, if operation should remove property.oldValue : stringOld value of the
roleproperty with given key ornull, if property was not set before.
-
change:tabindex( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:tabindexFired when the
tabindexproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
tabindex).value : numberNew value of the
tabindexproperty with given key ornull, if operation should remove property.oldValue : numberOld value of the
tabindexproperty with given key ornull, if property was not set before.
-
change:tooltip( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:tooltipFired when the
tooltipproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
tooltip).value : string | boolean | ( label: string, keystroke: undefined | string ) => stringNew value of the
tooltipproperty with given key ornull, if operation should remove property.oldValue : string | boolean | ( label: string, keystroke: undefined | string ) => stringOld value of the
tooltipproperty with given key ornull, if property was not set before.
-
change:tooltipPosition( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:tooltipPositionFired when the
tooltipPositionproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
tooltipPosition).value : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'New value of the
tooltipPositionproperty with given key ornull, if operation should remove property.oldValue : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'Old value of the
tooltipPositionproperty with given key ornull, if property was not set before.
-
change:type( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:typeFired when the
typeproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
type).value : 'button' | 'menu' | 'reset' | 'submit'New value of the
typeproperty with given key ornull, if operation should remove property.oldValue : 'button' | 'menu' | 'reset' | 'submit'Old value of the
typeproperty with given key ornull, if property was not set before.
-
change:withKeystroke( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:withKeystrokeFired when the
withKeystrokeproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
withKeystroke).value : booleanNew value of the
withKeystrokeproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
withKeystrokeproperty with given key ornull, if property was not set before.
-
change:withText( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:change:withTextFired when the
withTextproperty changed value.Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
withText).value : booleanNew value of the
withTextproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
withTextproperty with given key ornull, if property was not set before.
-
execute( eventInfo )module:ui/button/button~Button#event:execute -
set:ariaLabel( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:ariaLabelFired when the
ariaLabelproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
ariaLabel).value : stringNew value of the
ariaLabelproperty with given key ornull, if operation should remove property.oldValue : stringOld value of the
ariaLabelproperty with given key ornull, if property was not set before.
-
set:ariaLabelledBy( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:ariaLabelledByFired when the
ariaLabelledByproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
ariaLabelledBy).value : stringNew value of the
ariaLabelledByproperty with given key ornull, if operation should remove property.oldValue : stringOld value of the
ariaLabelledByproperty with given key ornull, if property was not set before.
-
set:class( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:classFired when the
classproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
class).value : undefined | stringNew value of the
classproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
classproperty with given key ornull, if property was not set before.
-
set:icon( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:iconFired when the
iconproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
icon).value : undefined | stringNew value of the
iconproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
iconproperty with given key ornull, if property was not set before.
-
set:isEnabled( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:isEnabledFired when the
isEnabledproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
isEnabled).value : booleanNew value of the
isEnabledproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
isEnabledproperty with given key ornull, if property was not set before.
-
set:isOn( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:isOnFired when the
isOnproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
isOn).value : booleanNew value of the
isOnproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
isOnproperty with given key ornull, if property was not set before.
-
set:isToggleable( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:isToggleableFired when the
isToggleableproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
isToggleable).value : booleanNew value of the
isToggleableproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
isToggleableproperty with given key ornull, if property was not set before.
-
set:isVisible( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:isVisibleFired when the
isVisibleproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
isVisible).value : booleanNew value of the
isVisibleproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
isVisibleproperty with given key ornull, if property was not set before.
-
set:keystroke( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:keystrokeFired when the
keystrokeproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
keystroke).value : undefined | stringNew value of the
keystrokeproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
keystrokeproperty with given key ornull, if property was not set before.
-
set:label( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:labelFired when the
labelproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
label).value : undefined | stringNew value of the
labelproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
labelproperty with given key ornull, if property was not set before.
-
set:labelStyle( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:labelStyleFired when the
labelStyleproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
labelStyle).value : undefined | stringNew value of the
labelStyleproperty with given key ornull, if operation should remove property.oldValue : undefined | stringOld value of the
labelStyleproperty with given key ornull, if property was not set before.
-
set:role( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:roleFired when the
roleproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
role).value : stringNew value of the
roleproperty with given key ornull, if operation should remove property.oldValue : stringOld value of the
roleproperty with given key ornull, if property was not set before.
-
set:tabindex( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:tabindexFired when the
tabindexproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
tabindex).value : numberNew value of the
tabindexproperty with given key ornull, if operation should remove property.oldValue : numberOld value of the
tabindexproperty with given key ornull, if property was not set before.
-
set:tooltip( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:tooltipFired when the
tooltipproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
tooltip).value : string | boolean | ( label: string, keystroke: undefined | string ) => stringNew value of the
tooltipproperty with given key ornull, if operation should remove property.oldValue : string | boolean | ( label: string, keystroke: undefined | string ) => stringOld value of the
tooltipproperty with given key ornull, if property was not set before.
-
set:tooltipPosition( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:tooltipPositionFired when the
tooltipPositionproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
tooltipPosition).value : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'New value of the
tooltipPositionproperty with given key ornull, if operation should remove property.oldValue : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'Old value of the
tooltipPositionproperty with given key ornull, if property was not set before.
-
set:type( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:typeFired when the
typeproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
type).value : 'button' | 'menu' | 'reset' | 'submit'New value of the
typeproperty with given key ornull, if operation should remove property.oldValue : 'button' | 'menu' | 'reset' | 'submit'Old value of the
typeproperty with given key ornull, if property was not set before.
-
set:withKeystroke( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:withKeystrokeFired when the
withKeystrokeproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
withKeystroke).value : booleanNew value of the
withKeystrokeproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
withKeystrokeproperty with given key ornull, if property was not set before.
-
set:withText( eventInfo, name, value, oldValue )module:ui/button/button~Button#event:set:withTextFired when the
withTextproperty is going to be set but is not set yet (before thechangeevent is fired).Parameters
eventInfo : EventInfoAn object containing information about the fired event.
name : stringName of the changed property (
withText).value : booleanNew value of the
withTextproperty with given key ornull, if operation should remove property.oldValue : booleanOld value of the
withTextproperty with given key ornull, if property was not set before.