Enumerate and add categories

This example shows how to enumerate categories and add a category to the main category list.

Example

Note

The following code example is an excerpt from Programming Applications for Microsoft Office Outlook 2007.

The Outlook object model supports categories that help organize items in a user’s Inbox. To maintain a higher level of organization, you can do the following:

• Categorize Outlook items and display them by category.
• Apply multiple color categories to a single Outlook item.
• Group and sort Outlook items by color category.
• Assign shortcut keys to each color category, enabling users to more easily categorize items.
• Create, delete, and change color categories either programmatically, or by user action within the Outlook user interface.

To expose the functionality of categories, the Outlook object model provides a Category object that represents a single user-defined color category in the main category list. The main category list contains color categories that are presented in the Outlook user interface. The list is represented by the Categories collection of the NameSpace object. To create a Category object, use the Add(String, Object, Object) method of the Categories collection. When you create a Category object, a globally unique identifier (GUID) is created, and this identifier cannot be changed. It is represented by the CategoryID property. You can, however, change the name, color, and shortcut key associated with a color category by setting the Name, Color, and ShortcutKey properties, respectively, of the Category object. You can change the Color property by setting or getting its OlCategoryColor constant. To reproduce the color in a custom control, use the following read-only properties of the Category object:

• CategoryBorderColor

• CategoryGradientBottomColor

• CategoryGradientTopColor

These properties return an OLE_COLOR value, which is dependent on the Color property of the Category object.

Outlook items are displayed based on the category name. Each item object has a Categories property that stores a comma-delimited string that represents category names. (For example, for the MailItem object, you would use the MailItem Categories property). This enables you to add a category to the item, even if the category is not present in the main category list.

Note

If the Categories property of an item contains a category name that is not in the Categories collection of the NameSpace object, the category name associated with that Outlook item is displayed, but without an associated color. The Categories property on an Item object does not return a Categories collection.

In the following code example, the first procedure, EnumerateCategories, gets the current user’s main list of categories, represented by the Categories collection. It then enumerates the Category objects in that collection, and writes the Name and CategoryID properties to the trace listeners of the Listeners collection. The second procedure, AddACategory, gets the current user’s main list of categories and uses the CategoryExists method to check whether a category named “ISV” exists in the collection. If no category with the name “ISV” exists, AddACategory adds a category named “ISV” to the main category list and assigns it a dark blue color by using the Add method of the Categories collection. It also assigns CTRL+F11 as the shortcut key for the category.

using Outlook = Microsoft.Office.Interop.Outlook;

private void EnumerateCategories()
{
    Outlook.Categories categories =
        Application.Session.Categories;
    foreach (Outlook.Category category in categories)
    {
        Debug.WriteLine(category.Name);
        Debug.WriteLine(category.CategoryID);
    }
}

private void AddACategory()
{
    Outlook.Categories categories =
        Application.Session.Categories;
    if (!CategoryExists("ISV"))
    {
        Outlook.Category category = categories.Add("ISV",
            Outlook.OlCategoryColor.olCategoryColorDarkBlue,
            Outlook.OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF11);
    }
}

private bool CategoryExists(string categoryName)
{
    try
    {
        Outlook.Category category = 
            Application.Session.Categories[categoryName];
        if(category != null)
        {
            return true;
        }
        else
        {
            return false;
        }
    }
    catch { return false; }
}

See also

• Color categories