User:Emre/tb/activitymanagerInterface: Difference between revisions

User:Emre/tb/activitymanagerInterface (view source)

Revision as of 01:13, 4 November 2008

5,066 bytes added , 4 November 2008

→‎Scenarios

Emre

270

edits

@@ Line 86: / Line 86: @@
 == Scenarios ==
+<i> A sample extension and C++ samples will follow </i>
-* Adding an activity for junk processing
+=== Showing an user-defined activity on the activity manager window ===
-* Adding an activity with cancelable capability
-*
+The following sample will show a process and an event for junk processing on the activity manager window.
+ // Step 1: Adding a Process into the activity manager
+ const nsIAP = Ci.nsIActivityProcess;
+ const nsIAE = Ci.nsIActivityEvent;
+ const nsIAM = Ci.nsIActivityManager;
+ let gActivityManager = Cc["@mozilla.org/activity-manager;1"].getService(nsIAM);
+ let process = Cc["@mozilla.org/activity-process;1"].createInstance(nsIAP);
+ // Assuming <i>folder</i> is an instance of nsIMsgFolder interface
+ // Localization is omitted, initiator is not provided
+ process.init("Processing folder: " + folder.prettiestName, null);
+ process.type = "junk_filtering";     // type of the activity
+ process.contextType = "account";     // group this activity by account
+ process.contextVal = folder.server;  // account in question
+ gActivityManager.addActivity(process);
+ // Step 2: Showing some progress
+ let percent = 50;
+ process.setProgress(percent, "Junk processing 25 of 50 messages", 25, 50);
+ // Step 3: Removing the process and adding an Event using Process' properties
+ process.state = ci.nsIActivity.ACTIVITY_COMPLETED;
+ gActivityManager.removeActivity(process.id);
+ let event = Cc["@mozilla.org/activity-event;1"].createInstance(nsIAE);
+ // Localization is omitted
+ event.init(folder.prettiestName + " is processed", "No junk found",
+            process.startTime, Date.now());
+ event.type = process.type;               // optional
+ event.contextType = process.contextType; // optional
+ event.contextVal = process.contextVal;   // optional
+ gActivityManager.addActivity(event);
+Optionally, if the initiator prefers to show each activity of this activity type standalone, it can do so by registering junk_filtering as VIEW_TYPE_STANDALONE:
+ gActivityManager.registerActivityViewType("junk_filtering", VIEW_TYPE_STANDALONE);
+=== Showing an user-defined activity with cancel capability ===
+This sample will improve the previous one by providing an nsIActivityCancelable to allow the user cancel the process.
+ // Step 1: Create a nsIActivityCancelable implementation
+ function CancelJunkProcess()
+ {
+  // user stuff here..
+ }
+ CancelJunkProcess.prototype = {
+  cancel: function(aActivity) {
+    let initiator = aActivity.initiator;
+    let folder = aActivity.getSubjects({})[0];
+    ....
+    // assuming that the initiator has a method to cancel the
+    // junk processing for given folder
+    if (initiator.Cancel(folder)) {
+     aActivity.state = Ci.nsIActivity.ACTIVITY_CANCELED;
+     gActivityManager.removeActivity(aActivity.id);
+     return Cr.NS_SUCCESS;
+    }
+   return Cr.NS_FAILURE;
+  }
+ }
+ // Step 2: Modify the previous sample to add initiator, subject
+ // and nsIActivityCancelable interface
+ ...
+ // assuming that gJunkProcessor is the entity initiating the junk processing
+ // activity
+ process.initWithHandlers("Processing folder: " + folder.prettiestName,
+                           gJunkProcessor,
+                           new CancelJunkProcess(),
+                           null, null);
+ // folder is being filtered/processed
+ process.addSubject(folder);
+ ...
+Since nsIActivityCancelable is provided with the activity, UI will show a cancel button besides the activity. You can extrapolate this sample to nsIActivityRetryable and nsIActivityPausable as well.
+=== Adding an activity with custom context type ===
+This sample shows how to provide a custom context type for the junk processing. As a result, all junk processing activities (assuming that we process accounts in parallel) processing the messages coming from the same sender will be grouped together.
+  // Step 1: Implement nsIActivityContextDisplayHelper to show a
+  //         customized   display text for our context type
+ function SenderContextDisplayHelper()
+ {
+  // user stuff here..
+ }
+ SenderContextDisplayHelper.prototype = {
+  getContextDisplayText: function(aActivity) {
+    let context = aActivity.contextVal;
+    ...
+    // we know that the context object is the author of the message
+    // Localization is omitted
+    return "Messages coming from " + context;
+  }
+ }
+ // Step 2: Register the helper for this context type
+ gActivityManager.registerContextDisplayHelper("Sender",
+                                              new SenderContextDisplayHelper());
+ // Step 3: Create the process
+ ...
+ // assuming msg is an instance of nsIMsgHdr
+ process.initWithHandlers("Processing folder: " + folder.prettiestName,
+                           gJunkProcessor,
+                           new CancelJunkProcess(),
+                           null, null);
+ // folder is being filtered/processed
+ process.addSubject(folder);
+ process.contextType = "Sender";
+ process.contextVal = msg.author;
+ ...
+=== Adding a fully customized activity ===
+In complex scenarios, it might be inevitable for extensions to implement their own version nsIActivityProcess and nsIActivityEvent interfaces. In such case, nsActivity.js can be used as a model.
+=== Changing the activity bindings ===
+ TBD
 == Relevant Links ==