As mentioned in Systems Application Architecture CUA Considerations, control windows are typically used in dialog boxes, and are hence accessed from the dialog procedure associated with their parent dialog box. Such communication is synchronous in nature, since it usually involves insertion or retrieval of data into or from control windows, or other tasks that are part of the modal dialog with the user.
Under OS/2 Version 2.0, some additional functions have been introduced into the Presentation Manager programming interface, to ease more complex communications, such as those involving list boxes. Since communication with list boxes is therefore somewhat different from that involving other control window classes, list boxes are discussed separately in List Boxes below.
General Control Windows
Communication between a dialog procedure and the control windows associated with its dialog box is typically achieved using the WinSendDlgItemMsg() function, which is documented in the IBM OS/2 Version 2.0 Presentation Manager Reference. This function is similar in function and behavior to the WinSendMsg() function, in that it passes a synchronous message to the destination window. However, instead of accepting the handle of the destination window as its first parameter, it accepts the handle of the control window's parent and the window identifier of the control window itself as the first two parameters of the call. For example, to send a message of class EM_SETTEXTLIMIT to an entry field named EF_PRODNAME, which is a child of the dialog box with handle hDlgBox, the function call shown in Figure "Communicating with a Control Window" is used.
It is possible to perform an equivalent function using the WinSendMsg() call, by obtaining the control window's handle using the WinWindowFromID() function. However, for purposes of standardization and in accordance with emerging conventions, it is recommended that the WinSendDlgItemMsg() function be used to send messages to control windows. Note that for this purpose, the definition of control windows includes both the system menu and menu bar; messages sent to these menus (in order to insert, modify or delete items) should be sent using the WinSendDlgItemMsg() function.
Similarly, it is recommended that the WinSetDlgItemText() and WinQueryDlgItemText() functions be used to set and query the contents of control windows from within the application. For example, assume that the user has completed interaction with a dialog box, and pressed the "Enter" or "OK" button, and the application wishes to obtain the contents of an entry field named EF_PRODNAME, which is child of the dialog box with handle hDlgBox. The function call call shown in Figure "Querying Information From a Control Window" is used.
The WinQueryDlgItemText() function copies the contents of the entry field into the string szBuffer, and returns the number of characters copied.
The WinSetDlgItemText() function is typically used in situations where some of the information necessary to complete an action is known; this information is then displayed in the appropriate entry fields within the dialog box, and the user fills in the missing fields. Another use of this function is to provide default values for entry fields. Both the WinSetDlgItemText() and WinQueryDlgItemText() functions are documented in the IBM OS/2 Version 2.0 Presentation Manager Reference.
List Boxes
The complexity of communication with list boxes has been greatly reduced under OS/2 Version 2.0. The Presentation Manager programming interface now includes a number of functions that allow most communication requirements to be achieved in a single step. Note that these functions may also be used for communication with a combo box (prompted entry field).
Insertion and deletion of list box items is carried out using the WinInsertLboxItem() and WinDeleteLboxItem() functions, which are new to OS/2 Version 2.0. The WinInsertLboxItem() function is illustrated in Figure "Inserting an Item Into a List Box".
An application may obtain the text of a selected item in the list box using the WinQueryLboxSelectedItem() and WinQueryLboxItemText() functions. The use of these functions is illustrated in Figure "Querying a Selected List Box Item".
Other functions include the WinQueryLboxCount() function, which returns the number of items in a list box, and the WinQueryLboxItemTextLength() function, which returns the length of list box item's text.
All of these list box manipulation functions are described in the IBM OS/2 Version 2.0 Presentation Manager Reference.