Creating

Introduction

A producer is a single and complete module which record a set category of events and send it over to the Data Sink to be transferred to the Timeline User Interface.

Basic Structure

A producer can be either a function with the required sub-functions as its prototypes, or an object with the required functions as its properties. Here is an example of a very simple and general purpose producer:

let {classes: Cc, interfaces: Ci, utils: Cu} = Components;
Cu.import("chrome://graphical-timeline/content/data-sink/DataSink.jsm");

var EXPORTED_SYMBOLS = ["XYZProducer"];

/**
 * The producer object.
 */
let XYZProducer =
{
  /**
   * A getter to be used by DataSink.
   * This getter should list out the list of enabled features ([] if none).
   * The array should contain the ids of the features as provided while
   * registering this producer to the DataSink.
   * @required
   */
  get enabledFeatures()
  {
    // return the list of active sub features,
  },

  /**
   * The xyz producer initializer.
   *
   * @param [object] aWindowList
   *        List of content windows on which the Timeline User Interface is opened.
   * @param array aEnabledFeatures (optional)
   *        List of enabled features.
   * @required
   */
  init: function XP_init(aWindowList, aEnabledFeatures)
  {
    // use the window list if needed
    // enable the features in the aEnabledFeatures,
    // or choose some features to be enabled by default
  },

  /**
   * Function to be used by the Data Sink to enable sub features
   *
   * @param array aFeatures
   *        List of strings containing the ids of the sub features to be enabled.
   * @required
   */
  enableFeatures: function XP_enableFeatures(aFeatures)
  {
    // Enable the features in aFeatures and update the array
    // that is used in the enabledFeatures getter
  },

  /**
   * Function to be used by the Data Sink to disable sub features.
   *
   * @param array aFeatures
   *        List of strings containing the ids of the sub features to be disabled.
   * @required
   */
  disableFeatures: function XP_disableFeatures(aFeatures)
  {
    // Disable the features in aFeatures and update the array
    // that is used in the enabledFeatures getter
  },

  /**
   * Function used by the Data Sink to stop the producer.
   * @required
   */
  destroy: function XP_destroy()
  {
    // Disable all the sub features, stop the producer and free the memory.
  },
};

The above mentioned example is complete as per a requirement by the Data Sink, but is useless as it is not calling the DataSink.addEvent method to pass its captured event data to the Data Sink. thus, the producer object should have a function that is activated on the initialization of the producer inside the init function. One example is provided below.

DataSink.addEvent("XYZProducer", {
  type: DataSink.NormalizedEventType.POINT_EVENT, // any one of the NORMALIZED_EVENT_TYPE
  name: someName,
  groupID: uniqueGroupId,
  time: Date.now(),
  details: {
    // Any amount of information to be passed.
  }
});

Registering

Data Sink, at the time of its activation, enables all the producers (or some if explicitly mentioned) that are registered with it. Thus, a producer is required to register itself to the Data Sink in its jsm file. It can be done by calling the DataSink.registerProducer method just after the producer object declaration.

/**
 * The information packet sent to the Data Sink.
 */
let producerInfo = {
  // Id of the producer.
  id: "XYZProducer",
  // Name of the producer.
  name: "XYZ Producer",
  // Type of events that this producer listens to (one type per producer).
  type: DataSink.NormalizedEventType.POINT_EVENT,
  // Features of this producer that can be turned on or off.
  features: ["foo", "bar"],
  // detail view will show properties belonging represented by these names.
  // "propertyName": {name: "display name", type: "boolean", values:{true: "Yes", false: "No"}]
  details: {
    eventName: {name: "Name", type: "string"},
    time: {name: "Time", type: "date"},
    // Add more properties depending upon the producer.
  }
};

// Register this producer to Data Sink
DataSink.registerProducer(XYZProducer, producerInfo);

The details property of the producerInfo object can contain various types of details, e.g. string, boolean, object, date etc. You can find a complete supported list on list of detail types page.