DialogControlGet

Returns text and state information associated with a control.

Syntax:

DialogControlGet( dialog-handle, control-name, request-code [,request-value] )

Parameters:

(i) dialog-handle: handle to dialog

(s) control-name: name of control to retrieve information from

(i) request-code:  information to return

(s) request-value: (optional) depends on request code. See Function Return Values in the table below.

Returns:

(a/s/i)   requested information

 

The DialogControlGet function returns text and state information associated with a control.

 

dialog-handle

The first parameter must be the dialog-handle passed as the first parameter to your dialog procedure.

control-name

The second parameter is the name of the control you wish to retrieve information from (for legacy dialog formats, i.e. earlier than 6.2, use the control's number in this parameter.)

request code

The third parameter is a request code. The request code depends on the type of the control you are querying. The following table shows the possible request codes, the control they apply to and the returned information.

Request

Applicable Controls

Function Return Values

@dcCheck (1)

CHECKBOX

REPORTVIEW

CHECKBOX: (i) 1 box checked, 0 box unchecked

REPORTVIEW: (i) 1 if the REPORTVIEW control has the checkbox (@csColCheck) style and the indicated item is checked, 0 for unchecked. The functions optional fourth parameter (request-value)  must be used to indicate the text of the item to test.

 

@dcDot (2)

RADIOBUTTON

(i) 1 button is dotted, 0 button is not dotted

 

@dcText (3)

EDITBOX

MULTILINEBOX

DATETIME

 

(s) All text currently in the control.

@dcTitle (4)

PICTURE

RADIOBUTTON

CHECKBOX

PICTUREBUTTON

VARYTEXT

STATICTEXT

GROUPBOX

PUSHBUTTON

MENUITEM

 

(s) Control’s title.

@dcContents (5)

ITEMBOX

FILELISTBOX

DROPLISTBOX

REPORTVIEW

 

ITEMBOX, FILELISTBOX and DROPLISTBOX: (s) Tab delimited list of all the items currently in the control, or a file wildcard mask if a FILELISTBOX is specified (i.e., "c:\temp\*.*").

REPORTVIEW: (a) One or two dimension array containing the contents of a REPORTVIEW control. Supports variant safe arrays.

 

@dcSelect (6)

ITEMBOX

FILELISTBOX

DROPLISTBOX

REPORTVIEW

 

ITEMBOX, FILELISTBOX and DROPLISTBOX: (s) Tab delimited list of the currently selected item(s) in the control. An empty string, if no item is selected.

REPORTVIEW: (a) One or two dimension array containing all selected rows of a REPORTVIEW control. Supports variant safe arrays.

 

@dcDate (7)

CALENDAR

DATETIME

CALENDAR: (s) Date shown in the control in YYYY:MM:DD:HH:MM:SS format

DATETIME: (s) Request code to obtain the date/time shown in the control in YYYY:MM:DD:HH:MM:SS format. The @dcTitle request code cannot be used to obtain the displayed date.

@dcSpin (8)

SPINNER

(s) Current value displayed in control

 

@dcTabStop (9)

 

No operation. Valid for DialogControlSet only

 

@dcScroll (10)

ITEMBOX

FILELISTBOX

MULTILINEBOX

 

(i) One based index of the first currently visible item in the list

 

@dcBackColor (11)

RADIOBUTTON

CHECKBOX

VARYTEXT

STATICTEXT

GROUPBOX

PUSHBUTTON

ITEMBOX

FILELISTBOX

DROPLISTBOX

REPORTVIEW

SPINNER

EDITBOX

MULTILINEBOX

DATETIME

 

(s) Background color specified by three vertical bar (|) delimited numbers ranging from 0 to 255. If the control is using the system default color, the string "DEFAULT" is returned.

@dcBitmap (12)

PICTURE

PICTUREBUTTON

(s) File specification of the controls currently displayed bitmap. If the control is not displaying a bitmap, the "DEFAULT" key string is returned.

 

@dcTextColor (13)

RADIOBUTTON

CHECKBOX

VARYTEXT

STATICTEXT

GROUPBOX

PUSHBUTTON

ITEMBOX

FILELISTBOX

DROPLISTBOX

REPORTVIEW

SPINNER

EDITBOX

MULTILINEBOX

DATETIME

 

(l) control's text color specified by three vertical bar (|) delimited numbers ranging from 0 to 255. If the control is using the dialog's default text color, the string "DEFAULT" is returned.

 

@dcAddItem(14)

 

Valid only for DialogControlSet.

 

@dcRemItem(15)

 

Valid only for DialogControlSet.

 

@dcGroupDot (16)

RADIOBUTTON

(i) Control-name (control-number for legacy dialogs) of the radio button from a group of radio buttons with the dot. If no radio button of the group has the dot, an empty string ("") or zero (0) for legacy dialogs is returned. The function’s second parameter can be the control-name of any radio button in the target group. (Radio buttons are grouped together by giving each button the same variable attribute.)

 

@dcPosition (17)

ALL CONTROLS
(Except MENUBAR and MENUITEM)

 

(s) Space delimited list of a control's position and size in dialog units relative to the dialog's client area. The first two numbers are the horizontal and vertical location of the upper-left corner of the control while the third and fourth numbers are the width and height of the control.

@dcMenuNames (18)

ALL CONTROLS
(Except GROUPBOX)

 

(s) Tab delimited list of menu item names associated with the control, menu item or menu bar.

@dchWnd (19)

 

 ALL CONTROLS
(Except MENUBAR and MENUITEM)

 

(i)  Window handle of a dialog control. Note:  The request cannot be used on MENUITEM and MENUBAR controls because these controls are not windows.

 

@dcHeaderText (20)

REPORTVIEW

(s) Tab delimited list of REPORTVIEW column headings.

 

@dcColWidth (21)

REPORTVIEW

(s) Space delimited list of the width of each REPORTVIEW column in dialog units.

 

@dcAppendCol(22)

 

Valid only for DialogControlSet.

 

@dcRemoveCol(23)

 

Valid only for DialogControlSet.

 

@dcFind (24)

REPORTVIEW

(a) One or two dimension array containing all REPORTVIEW rows which have first column text matching one of the items specified as a tab delimited list in the functions fourth parameter (request-value) .

 

@dcCancelEdit (25)

REPORTVIEW

(i) 1 if the next user edit of an item will be canceled upon completion. This request code only applies to REPORTVIEW controls with the edititem (@csColEdit) style.

 

@dcGetChecked (26)

REPORTVIEW

(a) One or two dimension array containing all checked rows of a REPORTVIEW control. This request code is only relevant when a REPORTVIEW control has the checkbox (@csColCheck) style.

 

@dcColFormat (27)

REPORTVIEW

(s) Space delimited list of format specification for each REPORTVIEW column. The returned values have the following meanings:

0 - left justify text
1 - center justify text
2 - right justify text

 

@dcFormat(28)

DATETIME

(s) Returns a DATETIME control's current format as a string.  The function returns an empty string if no format was previously specified.

 

 @dcItemColor (29)

REPORTVIEW

(l) Returns a space delimited list containing two color descriptors representing the colors of a REPORTVIEW control item's text and background color.  Each color descriptor consists of 3 vertical bar(|) delimited numbers representing red, green, and blue values each ranging from 0 to 255. The functions optional "request-value" parameter  must be used to indicate the one-based row and column number of the REPORTVIEW item whose colors are to be returned.  The row and column numbers must be separated by a space.

 

@dcItemRow (30)

REPORTVIEW

(i) Returns the one-based row number of column 1, the left-most column, REPORTVIEW item with text that matches the text placed in the function's "request-value"  parameter.

Note that if more than one first column item of a control contains the same value, the  text may need to contain a tab-delimited (@Tab)  list indicating which occurrences of the item to return.

 

@dcItemText (31)

REPORTVIEW

(s/l) Returns the column 1, the left-most column, text of the one-based  REPORTVIEW row indicated in the function's "request-value"  parameter.

 Note that if more than one first column item of a control contains the same value, the returned text may contain a tab-delimited (@Tab) list of multiple occurrences of the targeted item's text.

 

 

Example:
#DefineSubRoutine GetExample(DialogHandle,DialogMessage,DialogControlID,DialogEventInfo,DialogChangeInfo)
Switch  (DialogMessage)
   Case @deinit
      DialogProcOptions(DialogHandle, @deibselect, 1); Pass item listbox selection changes.
      break;
   Case @deibselect
      sSelection = DialogControlGet(DialogHandle,"Itembox_Colors",@dcselect); Get selection
      DialogControlSet(DialogHandle,"Static_Color",@dctitle,sSelection); Set text
      break;
EndSwitch
Return @retdefault
#EndSubRoutine
ItemList = "Red":@tab:"Green":@tab:"Blue":@tab:"Yellow":@tab:"Cyan":@tab:"Magenta"
GetExampleFormat=`WWWDLGED,6.2`
GetExampleCaption=`Control Get Example`
GetExampleX=529
GetExampleY=060
GetExampleWidth=206
GetExampleHeight=122
GetExampleNumControls=004
GetExampleProcedure=`GetExample`
GetExampleFont=`DEFAULT`
GetExampleTextColor=`DEFAULT`
GetExampleBackground=`DEFAULT,DEFAULT`
GetExampleConfig=0
GetExampleDPI=`96,8,16`
GetExample001=`023,099,160,014,PUSHBUTTON,"PushButton_1",DEFAULT,"Ok Already",1,1,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
GetExample002=`111,031,054,012,STATICTEXT,"Label_1",DEFAULT,"Your Selection:",DEFAULT,2,0,DEFAULT,DEFAULT,DEFAULT`
GetExample003=`111,045,078,010,STATICTEXT,"Static_Color",DEFAULT,"",DEFAULT,3,0,DEFAULT,DEFAULT,DEFAULT`
GetExample004=`005,011,068,072,ITEMBOX,"Itembox_Colors",ItemList,DEFAULT,DEFAULT,4,0,DEFAULT,DEFAULT,DEFAULT`
ButtonPushed=Dialog("GetExample",1)
Exit
See Also:

DialogProcOptions, DialogControlState, DialogControlSet