chrome.events

Contents

1. Methods
2. Declarative Event Handlers
   1. Rules
   2. Event objects
   3. Adding rules
   4. Removing rules
   5. Retrieving rules
3. API reference: chrome.events
   1. Types
      1. Event
         1. Methods
            1. addListener
            2. addRules
            3. getRules
            4. hasListener
            5. hasListeners
            6. removeListener
            7. removeRules
      2. Rule
      3. UrlFilter

An Event is an object that allows you to be notified when something interesting happens. Here's an example of using the chrome.tabs.onCreated event to be notified whenever there's a new tab:

chrome.tabs.onCreated.addListener(function(tab) {
  appendToLog('tabs.onCreated --'
              + ' window: ' + tab.windowId
              + ' tab: '    + tab.id
              + ' index: '  + tab.index
              + ' url: '    + tab.url);
});

As the example shows, you register for notification using addListener(). The argument to addListener() is always a function that you define to handle the event, but the parameters to the function depend on which event you're handling. Checking the documentation for chrome.tabs.onCreated, you can see that the function has a single parameter: a Tab object that has details about the newly created tab.

Methods

You can invoke the following methods on any Event object:

void addListener(function callback(...))
void removeListener(function callback(...))
bool hasListener(function callback(...))

Declarative Event Handlers

The declarative event handlers provide a means to define rules consisting of declarative conditions and actions. Conditions are evaluated in the browser rather than the JavaScript engine which reduces roundtrip latencies and allows for very high efficiency.

Declarative event handlers are used for example in the Declarative Web Request API and possibly further extension APIs in the future. This page describes the underlying concepts of all declarative event handlers.

Rules

The simplest possible rule consists of one or more conditions and one or more actions:

var rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

If any of the conditions is fulfilled, all actions are executed.

In addition to conditions and actions you may give each rule an identifier, which simplifies unregistering previously registered rules, and a priority to define precedences among rules. Priorities are only considered if rules conflict each other or need to be executed in a specific order.

var rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Event objects

Event objects may support rules. These event objects don't call a callback function when events happer but test whether any registered rule has at least one fulfilled condition and execute the actions associated with this rule. Event objects supporting the declarative API have three relevant methods: addRules(), removeRules(), and getRules().

Adding rules

To add rules call the addRules() function of the event object. It takes an array of rule instances as its first parameter and a callback function that is called on completion.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

If the rules were inserted successfully, the details parameter contains an array of inserted rules appearing in the same order as in the passed rule_list where the optional parameters id and priority were filled with the generated values. If any rule is invalid, e.g., because it contained an invalid condition or action, none of the rules are added and the lastError variable is set when the callback function is called. Each rule in rule_list must contain a unique identifier that is not currently used by another rule or an empty identifier.

Removing rules

To remove rules call the removeRules() function. It accepts an optional array of rule identifiers as its first parameter and a callback function as its second parameter.

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

If rule_ids is an array of identifiers, all rules having identifiers listed in the array are removed. If rule_ids lists an identifier, that is unknown, this identifier is silently ignored. If rule_ids is undefined, all registered rules of this extension are removed. The callback() function is called when the rules were removed.

Retrieving rules

To retrieve a list of currently registered rules, call the getRules() function. It accepts an optional array of rule identifiers with the same semantics as removeRules and a callback function.

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});

The details parameter passed to the calback() function refers to an array of rules including filled optional parameters.