Add documentation for filtered events.

chrome/renderer/resources/extensions/event.js

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
   var DCHECK = requireNative('logging').DCHECK;
   var eventBindingsNatives = requireNative('event_bindings');
   var AttachEvent = eventBindingsNatives.AttachEvent;
   var DetachEvent = eventBindingsNatives.DetachEvent;
   var AttachFilteredEvent = eventBindingsNatives.AttachFilteredEvent;
   var DetachFilteredEvent = eventBindingsNatives.DetachFilteredEvent;
@@ skipping 140 matching lines @@
       this.detachListener(this.listenerMap_[i], manual);
   };
 
   FilteredAttachmentStrategy.prototype.getListenersByIDs = function(ids) {
     var result = [];
     for (var i = 0; i < ids.length; i++)
       result.push(this.listenerMap_[ids[i]]);
     return result;
   };
 
+  chromeHidden.parseEventOptions = function(opt_eventOptions) {
+    function merge(dest, src) {
+      for (var k in src) {
+        if (!dest.hasOwnProperty(k)) {
+          dest[k] = src[k];
+        }
+      }
+    }
+
+    var options = opt_eventOptions || {};
+    merge(options,
+        {supportsFilters: false,
+         supportsListeners: true,
+         supportsRules: false,
+        });
+    return options;
+  };
+
   // Event object.  If opt_eventName is provided, this object represents
   // the unique instance of that named event, and dispatching an event
   // with that name will route through this object's listeners. Note that
   // opt_eventName is required for events that support rules.
   //
   // Example:
   //   chrome.tabs.onChanged = new chrome.Event("tab-changed");
   //   chrome.tabs.onChanged.addListener(function(data) { alert(data); });
   //   chromeHidden.Event.dispatch("tab-changed", "hi");
   // will result in an alert dialog that says 'hi'.
   //
   // If opt_eventOptions exists, it is a dictionary that contains the boolean
   // entries "supportsListeners" and "supportsRules".
   chrome.Event = function(opt_eventName, opt_argSchemas, opt_eventOptions) {
     this.eventName_ = opt_eventName;
     this.listeners_ = [];
-    this.eventOptions_ = opt_eventOptions ||
-        {supportsFilters: false,
-         supportsListeners: true,
-         supportsRules: false,
-        };
+    this.eventOptions_ = chromeHidden.parseEventOptions(opt_eventOptions);
 
     if (this.eventOptions_.supportsRules && !opt_eventName)
       throw new Error("Events that support rules require an event name.");
 
     if (this.eventOptions_.supportsFilters) {
       this.attachmentStrategy_ = new FilteredAttachmentStrategy(this);
     } else {
       this.attachmentStrategy_ = new UnfilteredAttachmentStrategy(this);
     }
 
     // Validate event arguments (the data that is passed to the callbacks)
     // if we are in debug.
     if (opt_argSchemas &&
         chromeHidden.validateCallbacks) {
 
       this.validateEventArgs_ = function(args) {
         try {
           validate(args, opt_argSchemas);
         } catch (exception) {
           return "Event validation error during " + opt_eventName + " -- " +
                  exception;
         }
       };
     } else {
       this.validateEventArgs_ = function() {}
     }
   };
 
+
   chromeHidden.Event = {};
 
   // callback is a function(args, dispatch). args are the args we receive from
   // dispatchEvent(), and dispatch is a function(args) that dispatches args to
   // its listeners.
   chromeHidden.Event.registerArgumentMassager = function(name, callback) {
     if (eventArgumentMassagers[name])
       throw new Error("Massager already registered for event: " + name);
     eventArgumentMassagers[name] = callback;
   };
@@ skipping 249 matching lines @@
       if (event)
         event.detach_();
     }
   };
 
   chromeHidden.dispatchError = function(msg) {
     console.error(msg);
   };
 
   exports.Event = chrome.Event;