Purpose
Reads the current status of a control in the active dialog box.
Syntax
ReadControlValue( id_num ) id_num is an integer value indicating which control to read.
Return Value
Integer, logical, string, Pen, Brush, Symbol, or Font, depending on the type of control
Description
The ReadControlValue() function returns the current value of one of the controls in an active dialog box. A ReadControlValue() function call is only valid while there is an active dialog box; thus, you may only call the ReadControlValue() function from within a dialog box control's handler procedure.
The integer id_num parameter specifies which control MapBasic should read. If the id_num parameter has a value of -1 (negative one), the ReadControlValue() function returns the value of the last control which was operated by the user. To explicitly specify which control you want to read, pass ReadControlValue() an integer ID that identifies the appropriate control.
The table below summarizes what types of values will be returned by various controls. Note that special processing is required for handling MultiListBox controls: since the user can select more than one item from a MultiListBox control, a program may need to call ReadControlValue() multiple times to obtain a complete list of the selected items.
| Control Type | ReadControlValue() Return Value |
|---|---|
| EditText | String, up to 32,767 bytes long, representing the current contents of the text box; if the EditText is tall enough to accommodate multiple lines of text, the string may include Chr$(10) values, indicating that the user entered line-feeds (for example, in Windows, by pressing Ctrl+Enter). |
| CheckBox | TRUE if the check box is currently selected, FALSE otherwise. |
| DocumentWindow | Integer that represents the HWND for the window control. This HWND should be passed as the parent window handle in the Set Next Document statement. |
| RadioGroup | SmallInt value identifying which button is selected (1 for the first button). |
| PopupMenu | SmallInt value identifying which item is selected (1 for the first item). |
| ListBox | SmallInt value identifying the selected list item (1 for the first, 0 if none). |
| BrushPicker | Brush value. |
| FontPicker | Font value. |
| PenPicker | Pen value. |
| SymbolPicker | Symbol value. |
| MultiListBox | Integer identifying one of the selected items. The user can select one or more of the items in a MultiListBox control. Since ReadControlValue() can only return one piece of information at a time, your program may need to call ReadControlValue() multiple times in order to determine how many items are selected. The first call to ReadControlValue() returns the number of the first selected list item (1 if the first list item is selected); the second call will return the number of the second selected list item, etc. When ReadControlValue() returns zero, the list of selected items has been exhausted. Subsequent calls to ReadControlValue() then begin back at the top of the list of selected items. If ReadControlValue() returns zero on the first call, none of the list items are selected. |
Error Conditions
ERR_FCN_ARG_RANGE (644) error is generated if an argument is outside of the valid range.
ERR_INVALID_READ_CONTROL (842) error is generated if the ReadControlValue() function is called when no dialog box is active.
Example
The following example creates a dialog box that asks the user to type a name in a text edit box. If the user clicks OK, the application calls ReadControlValue() to read in the name that was typed.
Declare Sub Main
Declare Sub okhandler
Sub Main
Dialog
Title "Sign in, Please"
Control OKButton
Position 135, 120 Width 50
Title "OK"
Calling okhandler
Control CancelButton
Position 135, 100 Width 50
Title "Cancel"
Control StaticText
Position 5, 10
Title "Please enter your name:"
Control EditText
Position 55, 10 Width 160
Value "(your name here)"
Id 23 'arbitrary ID number
End Sub
Sub okhandler
' this sub is called when/if the user
' clicks the OK control
Note "Welcome aboard, " + ReadControlValue(23) + "!"
End Sub See Also:
Alter Control statement, Dialog statement, Dialog Preserve statement, Dialog Remove statement