Using Dialog Boxes

All user interaction in the Address Book API is performed through abDialog. This function takes a pointer to an ABDIALOGINFO structure as its only parameter. The structure is used to pass in arguments and to get results back. As its return value, abDialog returns an HRESULT.

Before calling abDialog, you must set up an ABDIALOGINFO structure with the initial dialog box that you want to show and any other information that that initial dialog box requires.

The following table shows the available initial dialog boxes.

Initial view
Description
Dialog box
ABV_MAINVIEW Displays the Address Book List dialog box with an index and with the view set to the current contact
ABV_LOCATE Displays the Address Book List dialog box with an index, and sets an Auto PC mode to “locate.” The user can now say a custom command to find a contact.
ABV_CARDPHONE Displays the card view showing the Telephone tab
ABV_CARDHOME Displays the card view showing the Home Information tab
ABV_CARDWORK Displays the card view showing the Work Information tab
ABV_DIAL Displays the Dial dialog box, which asks the user if an Auto PC should dial the preferred telephone number for the current contact. If the user says No, the display returns to the ABV_CARDPHONE view.
ABV_RECEIVE Displays the Receive Address dialog box with an Auto PC looking for an infrared connection
ABV_SEND Displays the Send Address dialog box with an Auto PC attempting to send a specified number of contacts beginning at the current contact
ABV_NEW Displays the New Entry Wizard form.

For all views except ABV_RECEIVE and ABV_NEW, set the object identifier (CEOID) of the record that you want to display in the CEOID field of the ABDIALOGINFO structure. If you use ABV_SEND, you must set the number of records to transmit and specify the CEOID of the first record. For ABV_MAINVIEW, ABV_LOCATE, and ABV_CARD*, you can set a caption to display at the top of the screen.

In all cases, you can restrict the user’s ability to navigate to other screens by setting the ABE_* flags in the dwEnabled member of the ABDIALOGINFO structure. For example, you can block a user from deleting a record by not enabling navigation to the Delete dialog box in Address Book.

The structure returns the CEOID of the last contact record the user accessed and the identifier of the last view the user accessed.

For a code example that uses abDialog, see Reading and Writing Records.