Function Reference


Read state or data of a control.

GUICtrlRead ( controlID [, advanced = 0] )


controlID The control identifier (controlID) as returned by a GUICtrlCreate...() function, or -1 for the last created control.
advanced [optional] returns extended information of a control.
    $GUI_READ_DEFAULT (0) = (Default) Returns a value with state or data of a control.
    $GUI_READ_EXTENDED (1) = Returns extended information of a control (see Remarks).

Constants are defined in GUIConstantsEx.au3.

Return Value

Success: depends on the control (see below).
Failure: 0.

Type Value
Checkbox, Radio The checked state ($GUI_CHECKED or $GUI_UNCHECKED)
Combo, List The value selected
Input, Edit The text entered
Button The display text
Date The selected date in the format defined by the regional settings
Progress Current percentage
Slider Current value
Tab The index of the selected tabitem (0-based)
Menu, MenuItem State of the menu/item. See State table
TreeView Control identifier (controlID) of the selected TreeViewItem
TreeViewItem State of the TreeViewItem
ListView Control identifier (controlID) of the selected ListViewItem. 0 means no item is selected
ListViewItem The text of the selected item/lines in the ListView
Dummy The value set by GUICtrlSendToDummy() or GUICtrlSetData()


In 'advanced' mode the return value contains additional data of the control (see below).

Note: not all controls return additional data!

Type Additional Value
Checkbox, Radio The text of the control.
Menu, MenuItem The text of the control.
TreeView The text of the current selected TreeViewItem.
TreeViewItem The text of the TreeViewItem.
ListViewItem The state of the ListViewItem if $LVS_EX_CHECKBOXES exStyle used in advanced mode. See State table
Tab The controlID of the tabitem selected

For Checkbox and Radio controls only the $GUI_CHECKED (1), $GUI_UNCHECKED (4) or $GUI_INDETERMINATE (2) states are returned so the value can be used directly.

For Listview items several states can be returned as $GUI_CHECKED and $GUI_UNCHECKED (only for listview controls with LVS_EX_CHECKBOXES-exstyle and on 'advanced' return) . So use i.e. BitAND(GUICtrlRead($Item),$GUI_CHECKED) to test if the item is checked.

For Treeview items several states can be returned as $GUI_FOCUS, $GUI_EXPAND and $GUI_CHECKED, $GUI_UNCHECKED (only for treeview controls with TVS_CHECKBOXES-style . So use i.e. BitAND(GUICtrlRead($Item),$GUI_CHECKED) to test if the item is checked.


GUICtrlCreate..., GUICtrlGetState, GUICtrlSendMsg, GUICtrlSendToDummy, GUICtrlSetData, GUICtrlUpdate..., GUIEventOptions (Option), GUIGetMsg


#include <GUIConstantsEx.au3>
#include <MsgBoxConstants.au3>


Func Example()
    GUICreate("My GUICtrlRead") ; will create a dialog box that when displayed is centered

    Local $idMenu1 = GUICtrlCreateMenu("File")

    Local $idList = GUICtrlCreateList("", 10, 10, -1, 100)
    GUICtrlSetData(-1, "item1|item2|item3", "item2")

    Local $idButton = GUICtrlCreateButton("Read", 10, 110, 50)
    GUICtrlSetState(-1, $GUI_FOCUS) ; the focus is on this button

    GUISetState(@SW_SHOW) ; will display an empty dialog box

    Local $idMsg, $iMenustate, $sMenutext
    ; Loop until the user exits.
        $idMsg = GUIGetMsg()
        If $idMsg = $idButton Then
            MsgBox($MB_SYSTEMMODAL, "Selected listbox entry", GUICtrlRead($idList)) ; display the selected listbox entry
            $iMenustate = GUICtrlRead($idMenu1) ; return the state of the menu item
            $sMenutext = GUICtrlRead($idMenu1, $GUI_READ_EXTENDED) ; return the text of the menu item
            MsgBox($MB_SYSTEMMODAL, "State and text of the menuitem", "state:" & $iMenustate & @CRLF & "text:" & $sMenutext)
    Until $idMsg = $GUI_EVENT_CLOSE
EndFunc   ;==>Example