This documentation is archived and is not being maintained.

Sorting and Categorization

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Sorting a table places rows in an order that makes sense for its viewer. For example, one viewer might prefer to see the contents table of a folder sorted by message subject so that all the threads of a conversation are together while another viewer might want the messages sorted by the name of the sender. A newly instantiated table is not necessarily sorted in any particular order.

There are two types of sorting:

  • Standard sorting

  • Categorized sorting

With standard sorting, all of the rows are displayed in a flat list using one or more columns as a sort key. With categorized sorting, the rows are displayed hierarchically with one or more columns as the sort key. Within each category, there is a special heading row that contains the following columns:

The column or columns that make up the sort key

PR_CONTENT_UNREAD (PidTagContentUnreadCount)

PR_INSTANCE_KEY (PidTagInstanceKey)

PR_DEPTH (PidTagDepth)

PR_ROW_TYPE (PidTagRowType)

Indented under the heading row are all the rows from the table that contain columns with values that match the sort key. These rows are called the leaf rows. Leaf rows contain all the columns in the column set minus the sort key columns.

The contents tables of folders often support categorized sorting in addition to standard sorting. The contents tables of address book containers typically support only standard sorting.

A category can have two states: collapsed and expanded. When a category is in the collapsed state, only the heading row is returned from IMAPITable::QueryRows. When a category is in the expanded state, all of the rows related to the category are returned. This includes the heading row and the leaf rows.

Each category in a table view can be expanded or collapsed independently. That is, not all categories must be in the same state at the same time; some categories can be collapsed while others are expanded.

The user of a categorized table decides how it is displayed. One common option is to use a control provided in the Windows SDK called the treeview control. Treeview controls are list boxes that support information in a tree-like structure. Heading rows for categories in the expanded state are marked with a minus sign while heading rows for categories in the collapsed state are marked with a plus sign. Expanded categories are displayed with the leaf rows indented under the heading rows.

To collapse and expand a category, a client application or service provider uses the following IMAPITable : IUnknown methods: