API Reference | developer.brewmp.com API Reference | developer.brewmp.com


API Reference


Brew Release
Brew MP 1.0.2
The IDialog interface consists of two functions that operate on dialogs created using the functions in the IShell interface. (Refer to the IShell interface documentation for more details about its dialog-related functions.)
IDIALOG_GetControl() obtains interface pointers to the date, menu, text, and time controls that make up the dialog. Use these pointers to modify the properties and rectangles of the controls, or to retrieve the data the device user has entered or selected in each control.
IDIALOG_SetFocus() specifies which control in a multi-control currently has the focus. (This control receives keypad input from the device user.) Many controls generate control tabbing events when the device user presses the LEFT and RIGHT arrow keys. Dialogs use these control tabbing events to enable the device user to navigate between controls. IDIALOG_SetFocus() can be used with controls that do not support control tabbing (such as Soft Key menus), or to designate the control that has focus initially.
NOTE: Dialog titles are not supported in the current version of Brew MP.
NOTE: In a multi-control dialog, the left and right arrow keys should tab up and down in the list of the dialog controls. In the current version of Brew MP, the left arrow key tabs down, and the right arrow key does nothing.
To use IDIALOG_GetControl() and IDIALOG_SetFocus()
1. Create the controls in your dialog using the Brew MP Resource Manager or by populating the required dialog data structures in your code.
2. Call ISHELL_CreateDialog() to create the dialog and display it on the screen.
3. Call ISHELL_GetActiveDialog() to obtain an IDialog interface pointer to the dialog created in step 2. (The ISHELL_CreateDialog() does not return such a pointer.)
4. Call IDIALOG_GetControl() to access the controls in the dialog, supplying as input the interface pointer obtained in step 3 and the control IDs you specified when you created the controls in step 1. Use this function immediately after the dialog has been created to customize the appearance and properties of its controls.
5. Call IDIALOG_SetFocus() as needed while the dialog is active to allow the device user to select the control in which data is to be selected or entered. For example, if your dialog uses a Soft Key menu, provide a menu item that allows the device user to return to a previous control to change the data entered.
6. Call IDIALOG_GetControl() when data entry is complete to obtain the values the device user has entered or selected in each control.
7. Call ISHELL_EndDialog() to terminate the dialog.