Platform SDK: MAPI

BuildDisplayTable and Related Structures

Creating a display table is similar to writing a program with a scripting language. You can create a display table either by calling BuildDisplayTable or writing custom code to populate the rows and columns of the table. MAPI recommends the BuildDisplayTable technique because it is simpler.

Before you can call BuildDisplayTable to prompt MAPI to create a display table, there is a hierarchy of structures that you must build. The top level structure, the DTPAGE structure, describes a single tabbed property page. Within every DTPAGE structure is a DTCTL structure describing a single control, such as an edit box or a radio button. Each DTCTL structure contains a structure that is specific to the type of control. For example, if the DTCTL structure is describing an edit box control, it will contain a DTBLEDIT structure. The DTCTL structure for a radio button contains a DTBLRADIOBUTTON structure.

These structures relate directly to BuildDisplayTable; they have no meaning outside the context of this function. When you call BuildDisplayTable, you pass one or more DTPAGE structures as input parameters. The DTPAGE structures contain an array of DTCTL structures and a count of the number of DTCTL structures in the array. There is one structure for every control to appear in the dialog box. DTPAGE structures also have a character string that represents the name of a corresponding help file and dialog resource.

Each DTCTL structure in a DTPAGE structure contains data that is used to set properties for the control:

DTCTL structures also contain a resource identifier and, for edit and combo box controls, a character filter.

The control structure member of a DTCTL structure describes the data that is unique for the type of control. MAPI defines a different structure for each control type. For example, the data of an edit control is represented by a DTBLEDIT structure; the data of a list box by a DTBLLBX structure.

The relationship between these three types of display table structures is illustrated in the following diagram. The dialog box described by this display table has two controls: a label and an edit control. The DTBLLBX structure has a label offset member, as do several of the control structures, that describes where the character string for the label begins. Label character strings are typically placed in memory immediately following the structure.