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:
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:
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 Platform 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.
The following illustration shows a categorized contents table with an expanded category to illustrate the difference between how an expanded and collapsed category can appear to the user. The table is sorted by sender name — the PR_SENDER_NAME property. Heading rows contain the sender name and the computed properties for the row. The category where sender name is equal to Bill Lee is expanded to include five leaf rows. All of the leaf rows are visible and there is a minus sign next to the heading row, indicating that no further expansion of the category is possible.
In the following illustration, the category is collapsed with none of the leaf rows included in the display. The heading row has a plus sign indicating that the category can be expanded further.
To collapse and expand a category, a client application or service provider uses the following IMAPITable methods: