entries/callbacks.lock.xml

<?xml version="1.0"?>
<entry name="callbacks.lock" type="method" return="Callbacks">
  <title>callbacks.lock()</title>
  <signature>
    <added>1.7</added>
  </signature>
  <desc>Lock a callback list in its current state.</desc>
  <longdesc>
    <p>This method returns the Callbacks object onto which it is attached (<code>this</code>).</p>
    <p>If the Callbacks object is created with the <code>"memory"</code> flag as its argument, additional functions may be added and fired after the callback list is locked.</p>
  </longdesc>
  <example>
    <desc>Use <code>callbacks.lock()</code> to lock a callback list to avoid further changes being made to the list state:</desc>
    <code><![CDATA[
// A sample logging function to be added to a callbacks list
var foo = function( value ) {
  console.log( "foo:" + value );
};

var callbacks = $.Callbacks();

// Add the logging function to the callback list
callbacks.add( foo );

// Fire the items on the list, passing an argument
callbacks.fire( "hello" );
// Outputs "foo: hello"

// Lock the callbacks list
callbacks.lock();

// Try firing the items again
callbacks.fire( "world" );

// As the list was locked, no items were called,
// so "world" isn't logged
]]></code>
  </example>
  <example>
    <desc>Use <code>callbacks.lock()</code> to lock a callback list with "memory," and then resume using the list:</desc>
    <html><![CDATA[
<div id="log"></div>
]]></html>
    <code><![CDATA[
// Simple function for logging results
var log = function( value ) {
  $( "#log" ).append( "<p>" + value + "</p>" );
};

// Two sample functions to be added to a callbacks list
var foo = function( value ) {
  log( "foo: " + value );
};
var bar = function( value ) {
  log( "bar: " + value );
};

// Create the callbacks object with the "memory" flag
var callbacks = $.Callbacks( "memory" );

// Add the foo logging function to the callback list
callbacks.add( foo );

// Fire the items on the list, passing an argument
callbacks.fire( "hello" );
// Outputs "foo: hello"

// Lock the callbacks list
callbacks.lock();

// Try firing the items again
callbacks.fire( "world" );
// As the list was locked, no items were called,
// so "foo: world" isn't logged

// Add the foo function to the callback list again
callbacks.add( foo );

// Try firing the items again
callbacks.fire( "silentArgument" );
// Outputs "foo: hello" because the argument value was stored in memory

// Add the bar function to the callback list
callbacks.add( bar );

callbacks.fire( "youHadMeAtHello" );
// Outputs "bar: hello" because the list is still locked,
// and the argument value is still stored in memory
]]></code>
  </example>
  <category slug="callbacks-object"/>
  <category slug="version/1.7"/>
</entry>