This content covers features introduced in Thunderbird 3
The Activity Manager is a simple component that understands how to display a combination of user activity and history. See the Activity Manager page for a general description of the component. See the Activity Manager interfaces page for an overview of the related interfaces.
If the default implementation of nsIActivityProcess
, nsIActivityWarning
and nsIActivityEvent
are not sufficient for the activity initiator, activity developers can provide their own components to extend the capabilities. Default implementations can be found in nsActivity.js
file.
If activity developers would like to extend the default UI representation of the activity types, they can provide their own XBL elements for their own activity types. All custom activity XBL elements should inherit from "activity-base" binding. For XBL samples please see activity.xml
and activityBinding.css
files.
Showing a user-defined activity in the Activity Manager window
The following sample will show a process and an event for junk processing in the Activity Manager window.
// Step 1: Adding a Process into the activity manager const nsIAP = Components.interfaces.nsIActivityProcess; const nsIAE = Components.interfaces.nsIActivityEvent; const nsIAM = Components.interfaces.nsIActivityManager; let gActivityManager = Components.classes["@mozilla.org/activity-manager;1"].getService(nsIAM); let process = Components.classes["@mozilla.org/activity-process;1"].createInstance(nsIAP); // Assuming folder is an instance of nsIMsgFolder interface // Localization is omitted, initiator is not provided process.init("Processing folder: " + folder.prettiestName, null); // Note that we don't define a custom icon, default process icon // will be used process.contextType = "account"; // group this activity by account process.contextObj = 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' attributes process.state = Components.interfaces.nsIActivityProcess.STATE_COMPLETED; gActivityManager.removeActivity(process.id); let event = Components.classes["@mozilla.org/activity-event;1"].createInstance(nsIAE); // Localization is omitted, initiator is omitted event.init(folder.prettiestName + " is processed", null, "No junk found", process.startTime, // start time Date.now()); // completion time event.contextType = process.contextType; // optional event.contextObj = process.contextObj; // optional gActivityManager.addActivity(event);
Showing a user-defined activity with cancel capability (JavaScript)
This sample improves the previous one by providing an nsIActivityCancelHandler
to allow the user to cancel the process.
// Step 1: Create a nsIActivityCancelHandler implementation function CancelJunkProcess() { // user stuff here.. } CancelJunkProcess.prototype = { cancel: function(aActivity) { let initiator = aActivity.initiator; if (initiator) { let folder = aActivity.getSubjects({})[0]; .... // assuming that the initiator has some way to cancel // the junk processing for given folder if (initiator.cancelFolderOp(folder)) { aActivity.state = Components.interfaces.nsIActivityProcess.STATE_CANCELED; gActivityManager.removeActivity(aActivity.id); return Cr.NS_SUCCESS; } } return Cr.NS_FAILURE; } } // Step 2: Modify the previous sample to add initiator, subject // and associate a nsIActivityCancelHandler component ... // assuming that gJunkProcessor is the entity initiating the junk processing // activity, and it has cancelFolderOp method that cancels the operations on folders process.init("Processing folder: " + folder.prettiestName, gJunkProcessor); // folder is being filtered/processed process.addSubject(folder); process.cancelHandler = new CancelJunkProcess(); ...
Since nsIActivityCancelHandler
is provided with the activity, the UI will show a cancel button beside the activity. You can extrapolate this sample to nsIActivityRetryHandler
and nsIActivityPauseHandler
as well.
Showing a user-defined activity with undo capability (C++)
..... #include "nsIActivity.h" #include "nsIActivityManager.h" .....
////////////////////////////////////////////////////////////////////////////// //// Undo handler implementation class myCopyEventUndo : public nsIActivityUndoHandler { public: NS_DECL_ISUPPORTS NS_DECL_NSIACTIVITYUNDOHANDLER myCopyEventUndo() {} private: ~myCopyEventUndo() {} }; NS_IMPL_ISUPPORTS1(myCopyEventUndo, nsIActivityUndoHandler)
NS_IMETHODIMP myCopyEventUndo::Undo(nsIActivityEvent *event, nsresult *result) { nsresult rv; // get the subjects of this copy event PRUint32 length; nsIVariant **subjectList; rv = event->GetSubjects(&length, &subjectList); if(NS_FAILED(rv)) return rv; // first subject in the list is the source folder in this particular case nsCOMPtr<nsIMsgFolder> folder = do_QueryInterface(subjectList[0]); // get the initiator nsIVariant *initiator; event->GetInitiator(&initiator); if (initiator) { nsISupports* ptr; rv = object->GetAsISupports(&ptr); if(NS_FAILED(rv)) return rv; nsCOMPtr<nsIMsgCopyService> copyService = do_QueryInterface(ptr); if (copyService) copyService->Undo(folder); } return (*result = NS_OK); }
///////////////////////////////////////////////////////////////////////////// //// Creating an undoable copy event nsCOMPtr<nsIActivityUndoHandler> undoHandler = new myCopyEventUndo(); nsCOMPtr<nsIActivityEvent> copyEvent(do_CreateInstance("@mozilla.org/activity-event;1")); // The initiator of this particular event is CopyService. We want to // associate it with the event since we are going to use it in the // undo handler. // Same for the source folder, it is required for undo operation, but // since it is the subject of this activity (event), it goes into the // subject list. // wrap copyservice in a nsvariant component nsCOMPtr<nsIWritableVariant> initiator = do_CreateInstance(NS_VARIANT_CONTRACTID); initiator->SetAsISupports(reinterpret_cast<nsISupports*>(copyService)); // subject of the delete operation is the imap folder // wrap it in a nsvariant component nsCOMPtr<nsIWritableVariant> srcFolder = do_CreateInstance(NS_VARIANT_CONTRACTID); srcFolder->SetAsISupports(reinterpret_cast<nsISupports*>(imapFolder)); copyEvent->AddSubject(srcFolder); copyEvent->Init(NS_LITERAL_STRING("Message copy event"), initiator, NS_LITERAL_STRING("Completed successfully"), PR_Now() / PR_USEC_PER_MSEC, // start time PR_Now() / PR_USEC_PER_MSEC); // completion time // Do not forget to increase the ref counter if needed copyEvent->SetUndoHandler(undoHandler);
//////////////////////////////////////////////////////////////// //// Adding the event into Activity Manager nsCOMPtr<nsIActivityManager> activityMgr(do_GetService("@mozilla.org/activity-manager;1")); PRUint32 id; activityMgr->AddActivity(copyEvent, &id);
Adding an activity with a custom context type
This sample shows how to provide a custom context type for junk processing. As a result, all junk processing activities (assuming that we process accounts in parallel) dealing with messages coming from the same sender will be grouped together. (This example seems to be outdated and not working, see bug 557467 comment 1.)
//optional: define some convenience constants const nsActProcess = Components.Constructor("@mozilla.org/activity-process;1", "nsIActivityProcess", "init"); const nsActEvent = Components.Constructor("@mozilla.org/activity-event;1", "nsIActivityEvent", "init"); // Step 1: Implement nsIActivityContextDisplayHelper to show a // customized display text for our context type function SenderContextDisplayHelper() { // user stuff here.. } SenderContextDisplayHelper.prototype = { getContextDisplayText: function(contextType, contextObj) { // in this particular example we know that contextType is "Sender" // since we also pass the contextType along with the contextObject // in some cases, one helper can be registered for a group of context types // we know that the context object is the author of the message // Localization is omitted return "Messages coming from " + contextObj.surname + ", " + contextObj.firstname; } } // Step 2: Register the helper for this context type gActivityManager.registerContextDisplayHelper("Sender", new SenderContextDisplayHelper()); // Step 3: Create the process ... let process = new nsActProcess("Processing folder: " + folder.prettiestName, gJunkProcessor); process.cancelHandler = new CancelJunkProcess(); // folder is being filtered/processed process.addSubject(folder); process.contextType = "Sender"; // assuming msg is an instance of nsIMsgHdr process.contextObj = msg.author; ...
Adding a fully customized activity
In complex scenarios, extensions might implement their own version of the nsIActivityProcess
, nsIActivityWarning
and nsIActivityEvent
interfaces. In such cases, nsActivity.js
can be used as a model.