callbacks.lock()

Categories: Callbacks Object

callbacks.lock()Returns: Callbacks

Description: Lock a callback list in its current state.

This method returns the Callbacks object onto which it is attached (this).

If the Callbacks object is created with the "memory" flag as its argument, additional functions may be added and fired after the callback list is locked.

Examples:

Use callbacks.lock() to lock a callback list to avoid further changes being made to the list state:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
// 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

Use callbacks.lock() to lock a callback list with "memory," and then resume using the list:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>callbacks.lock demo</title>
  <script src="jquery-1.10.2.js"></script>
</head>
<body>
 
<div id="log"></div>
 
<script>
// 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
</script>
 
</body>
</html>

Demo: