< OOUI

The OOUI library is based on the event model provided by OOjs. If you are not familiar with OOjs, you may wish to take a moment to familiarize yourself with its EventEmitter, as it is a convenient and powerful tool that will often be used in examples.

EventEmitter allows event handlers to be connected to an object, called when events occur, and disconnected when no longer needed. Events are tied to their context. For example, when a toggle button changes state, the event is not simply ‘change,’ but ‘change’ and the value of the toggle button’s state ( ‘on’ or ‘off’).

The most basic way to connect and disconnect an event handler is with the EventEmitter’s on() and off() methods. In the following example, the on() method is used to connect an onChange event handler to a toggle button, which is defined in the example as well.

// <translate nowrap><!--T:8--> The following example uses the <tvar name=1>on()</tvar> method to connect an event handler</translate> 
// <translate nowrap><!--T:9--> to a toggle button widget. The <tvar name=1>off()</tvar> method is later used to disconnect</translate>
// <translate nowrap><!--T:10--> the event handler.</translate>

// <translate nowrap><!--T:11--> Create a new toggle button</translate>
var button = new OO.ui.ToggleButtonWidget( { 
  label: 'I handle events' 
} );
// <translate nowrap><!--T:12--> Set up the event handler. In this example, the event handler is a</translate> 
// <translate nowrap><!--T:13--> function that will change the button label to 'All done!' when the</translate> 
// <translate nowrap><!--T:14--> state of the button changes. The <tvar name=1>off()</tvar> method is then used to</translate> 
// <translate nowrap><!--T:15--> disconnect the event handler from the toggle button so that the</translate> 
// <translate nowrap><!--T:16--> function will no longer be called.</translate>
button.onChange = function () {
  button.setLabel( 'All done!' );
  button.off( 'change', button.onChange );
} 
// <translate nowrap><!--T:17--> Use the ButtonWidget's <tvar name=1>on()</tvar> method to connect an event handler</translate> 
// <translate nowrap><!--T:18--> ('<tvar name=1>button.onChange</tvar>', defined above) to the button for the specified</translate> 
// <translate nowrap><!--T:19--> type of event ('<tvar name=1>change</tvar>').</translate> 
button.on( 'change', button.onChange );
// <translate nowrap><!--T:20--> Append the button to the DOM.</translate>
$( 'body' ).append( button.$element );

Often, the connect() and disconnect() methods are used to connect and disconnect multiple event handlers to objects. The following example illustrates these methods.

// <translate nowrap><!--T:23--> This example illustrates the <tvar name=1>connect()</tvar> and <tvar name=2>disconnect()</tvar> methods.</translate>
// <translate nowrap><!--T:24--> Here, the '<tvar name=1>onChange</tvar>' function, which changes the label of the toggle button</translate>
// <translate nowrap><!--T:25--> labeled '<tvar name=1>try me!</tvar>' to match the button's state ('<tvar name=2>on</tvar>' or '<tvar name=3>off</tvar>') will be</translate>
// <translate nowrap><!--T:26--> executed whenever the state of the toggle button changes. The '<tvar name=1>onToggleClick</tvar>'</translate>
// <translate nowrap><!--T:27--> function, which writes '<tvar name=1>Click!</tvar>' each time the toggle button is clicked, is</translate>
// <translate nowrap><!--T:28--> also connected to the toggle button via the <tvar name=1>connect()</tvar> method. The</translate>
// <translate nowrap><!--T:29--> <tvar name=1>disconnect()</tvar> method, connected to the '<tvar name=2>Disconnect EventHandlers</tvar>' button,</translate>
// <translate nowrap><!--T:30--> is used to remove both event handlers from the toggle button.</translate>

// <translate nowrap><!--T:31--> Create buttons and add them to a button group.</translate>
var toggle = new OO.ui.ToggleButtonWidget( {
  label: 'try me!'
} );

var button = new OO.ui.ButtonWidget( {
  label: 'Disconnect EventHandlers'
} );

var buttonGroup = new OO.ui.ButtonGroupWidget( {
  items: [ toggle, button ]
} );

// <translate nowrap><!--T:32--> Define the functions to connect (<tvar name=1>toggle.onChange</tvar>, <tvar name=2>toggle.onToggleClick</tvar>, and</translate>
// <translate nowrap><!--T:33--> <tvar name=1>button.onClick</tvar>, in this example)</translate>

toggle.onChange = function () {
  if ( toggle.getValue() === false ) {
    toggle.setLabel( 'off' );
  } else {
    toggle.setLabel( 'on' );
  }
};

toggle.onToggleClick = function () {
  $( 'body' ).append( '<p>Click!</p>' );
};

button.onClick = function () {
  toggle.disconnect( toggle, {
    change: 'onChange',
    click: 'onToggleClick'
  } );
};

// <translate nowrap><!--T:34--> Bind the functions to the widgets for the specified events.</translate>

toggle.connect( toggle, {
  change: 'onChange',
  click: 'onToggleClick'
} );

button.connect( button, {
  click: 'onClick'
} );

// <translate nowrap><!--T:35--> Append the button group to the DOM.</translate>
$( 'body' ).append( buttonGroup.$element );
A convention of OOjs is that any method that begins with "on" (e.g., onClick() and onKeyPress()) is private, except for the on() method itself.

For more details about EventEmitter, please see OOjs/Events.

This article is issued from Mediawiki. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.