Frequently you are trying to figure out the code that implements a specific feature of the user interface. How do you find that out? As an example, I received the following inquiry, and I decided to follow my usual path and document what I do:
Hello i would like to add colours and tags to specific emails...by
using nsiMsgTagService, can this be done?
Here is my (edited) response:
nsIMsgTagService is used to store the list of valid tags, so it is not the correct way to tag messages. Tags are applied using the message database property "keyword". I know the underlying code, but I don't remember the user interface level function to do it. But here is how I find out.
There are two key tools that you need. The first is the DOM inspector extension which I have routinely installed in all of my Thunderbird installations. (For debug builds, you can make it appear by default using "ac_add_options --enable-extensions=default,venkman,inspector" which is part of my standard configuration). The second is mozilla's source code search tool mxr. I keep two prominent links to this on my Firefox toolbar, one to comm-central string search, and one to comm-central file search.
So, how did I use those to figure out how to do this? I know there is a menu command "Tag" to tag the message - how does it do it? Using DOM inspector, I find the Tag menu item, and I see that it uses command "cmd_tag". Then I use mxr and look for "cmd_tag". I see it occurs in mail3PaneWindowCommands.js a couple of times. I look at the last occurrence, and see it is just an enable item with no real action involved. Oops, I guess I need to get the submenu instead. Repeating this process, I see that the submenu items all call a function ToggleMessageTagMenu. Looking that up in mxr, its underlying function uses a very strange call prevHdrFolder[toggler](messages, key) to change the key. Trying to figure that out from the code, I see that is just a clever way to do the addKeywordsToMessages or removeKeywordsFromMessages method call. (Please don't do that guys, it really makes code search difficult!)
So the answer the your question is, use the nsIMsgFolder method "addKeywordsToMessages" (and now I remember that I knew that!).
If you want examples, scan mxr for addKeywordsToMessages. You'll find that the only decent examples are in unit tests, my test_bug428427.js or asuth's messageModifier.js