ClarifyCRM® eFrontOffice 11.

ClearBasic Control Reference

Part Number. M30032-00E11050000

September, 2002
© 1995–2002, Amdocs. All Rights Reserved.
Amdocs Confidential
This manual and the software described herein are subject to your Amdocs Software License and are copyrighted with all rights reserved. This
manual and the software may not be copied, in whole or in part, without written consent of Amdocs, except as permitted by your Amdocs Software
License.
The information in this manual is furnished for informational use only by authorized persons, is subject to change without notice, and should not be
construed as a commitment by Amdocs. Amdocs assumes no responsibility or liability for any errors or inaccuracies that may appear in this book.
The trademark and service marks of the respective Amdocs companies, including the Amdocs mark and logo, are the exclusive property of such
companies, and may not be used without permission. All other marks mentioned in this material are the property of their respective owners.

For technical assistance, visit http://clearanswer.clarify.com to submit a case at any time.

Contents

About This Guide

Audience for This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
How to Use This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
What’s New in This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

ActiveX control

Animation control

Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Play . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Bitmap control

Check Box control

Caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Parent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Command Button control

BackColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
ForeColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

ClearBasic Control Reference 3

Contents

Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Control object

Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
SetFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
ControlType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
hWnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Id. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Left . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Top . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
GotFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
LostFocus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Dropdown Combo Box control

AppendItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Contains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
GetList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
GetSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
RemoveByItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
RemoveSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
ReplaceItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
SelectedIndexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
SelectedList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
SetSelected. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
UnSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
ListCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
ListIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
NewIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

4
ClearBasic Control Reference
 Contents

Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Sorted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Dropdown List Box control

AppendItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Clear. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
GetList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
GetSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
RemoveByItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
RemoveSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
ReplaceItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
SelectedIndexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
SelectedList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
SetSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
UnSelect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
ListCount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
ListIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
NewIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Parent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Sorted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
UserData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Graph control

ClearData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
GetLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
GetLegend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
GetPoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
SetLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
SetLegend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
SetPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

5
ClearBasic Control Reference
Contents

BackColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
BackStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
BorderStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
GraphType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
LegendPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
NumSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
ShowLegend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Grid control

AbortCellChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
AbortRowChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
AppendContextMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
AppendItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
ClearContextMenu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
ColorCells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Contains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
GetChangedCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
GetChangedRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
GetChoiceList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
GetChoiceListDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
GetChoiceListUserData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
GetColumnControlType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
GetColumnMaxLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
GetColumnNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
GetList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
GetSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
GetSelectedColumns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
HideColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
IsColumnEditable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
IsColumnRequired. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
RemoveByItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
RemoveSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
ReplaceItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
SaveAnyChanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
SelectedIndexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
SelectedList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
SetCellColoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
SetCellFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
SetCellReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

6
ClearBasic Control Reference
 Contents

SetCellText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
SetContextMenuEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
SetContextMenuVisible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
SetEditStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
SetNewRowIndicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
SetRowReadOnly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
SetSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
UndoRowChanges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
UnSelect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
AppendRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
CObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Dirty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
ListCount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
ListIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
MultiSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
NewIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
PagingEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Parent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
PromptOnSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
SelCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Sorted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
TopIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
TotalRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
AdhocCellChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Cell_Btn_Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
CellChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Cell_Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Cell_List_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
ContextMenuDisplaying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
ContextMenu_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
DblClick. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
DoAdhocQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
NewRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Refresh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
RowChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
SortColumn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

7
ClearBasic Control Reference
Contents

Label control

BackColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
ForeColor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

List Box control

AppendItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Contains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
GetList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
GetSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
RemoveByItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
RemoveSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
ReplaceItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
SelectedIndexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
SelectedList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
SetSelected. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
UnSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
ListCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
ListIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
MultiSelect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
NewIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
SelCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Sorted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
TopIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
UserData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
DblClick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Multiline Text Box control

AppendContextMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

8
ClearBasic Control Reference
 Contents

ClearContextMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
SetContextMenuEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
SetContextMenuVisible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
BackColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
ForeColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
MaxLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
MultiLine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Parent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
RequiredColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
SelLength. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
SelStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
SelText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
ContextMenuDisplaying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
ContextMenu_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
KeyPress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Option Button control

Caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Parent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

ProgressBar control

Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Select CBX control

AppendAdhocFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
AppendDefaultSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
AppendItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
AppendPreFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
ClearAdhocRow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
ClearAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
ClearPreFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

9
ClearBasic Control Reference
 Contents

EnableAdhoc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
GenerateSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
GetAdhocRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
GetChangedCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
GetCObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
GetCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
GetList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
GetNext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
GetObjIds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
GetPageSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
GetPrevious. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
GetSelCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
GetSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
InsertItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
OwnsGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
RefreshItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Regenerate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
RejectAdhocCellEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
RemoveSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
ReplaceSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
ResetDefaultSort. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
ResetPreFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
SelectedList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
SetAdhocCellReadOnly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
SetAdhocCellText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
SetCObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
SetCurrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
SetSelected. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
SetSelectedById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
UnSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
UpdateItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Slider control

Max. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Scroll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Tab Button control

DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

10
ClearBasic Control Reference
 Contents

Parent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Text Box control

AppendContextMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
ClearContextMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
SetContextMenuEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
SetContextMenuVisible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
BackColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
ForeColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
MaxLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
MultiLine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Parent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
RequiredColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
SelLength. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
SelStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
SelText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
ContextMenuDisplaying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
ContextMenu_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
KeyPress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

TreeView control

Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Clear. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Expand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
GetItemText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
GetSelectedItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
SetImageList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
SetItemOverlayImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
SetItemText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
SetOverlayImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
SetSelectedItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

11
ClearBasic Control Reference
 Contents

Collapse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
NodeClick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

UpDown control

Max. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
DownClick. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
UpClick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

Appendix A Supported Methods, Properties, and Events

Control and Method Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

Control and Property Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Control and Event Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

Index

12
ClearBasic Control Reference
About This Guide

This reference provides information about the ClearBasic controls and their methods,
properties, and events. It is a companion volume to the ClearBasic Object Reference,
which provides information about the ClearBasic objects. This reference is also a
companion to the ClearBasic Programmer’s Guide, which provides information about
using ClearBasic to perform tasks, and to the ClearBasic Language Reference, which
documents the ClearBasic language.

Audience for This Guide

This reference is intended for developers involved in extending and customizing the
ClarifyCRM eFrontOffice (CeFO) applications and databases.

Related Documentation
The following referenced documentation is available on the CeFO Documentation
CD-ROM:
■ ClearBasic Object Reference
■ ClearBasic Programmer’s Guide
■ ClearBasic Language Reference
■ ClearBasic Customization Guide
■ User Interface Editor Guide

How to Use This Guide

This guide describes the ClearBasic controls and control-related objects defined for
use with ClarifyCRM eFrontOffice. This guide contains the following sections:
■ A table of contents.
■ An alphabetical list of controls, with accompanying descriptions. Immediately
following the description of each control are descriptions of its methods,
properties, and events.
■ An appendix with a comprehensive list of the methods, properties, and events
associated with each control, organized in tables for quick reference.
■ An index listing all of the controls, objects, methods, properties, and events
alphabetically.

ClearBasic Control Reference 13

 What’s New in This Document
This reference introduces a new way of organizing ClearBasic controls, methods,
properties, and events. The new organization groups the methods, properties, and
events related to a control with the description for that control. The new organization
lets you search for related methods and properties of the control quickly. Refer to the
improved index if you want to view an alphabetical listing of controls, methods,
properties, and events.

The online version of this document also introduces the use of live links. The control
description contains the list of methods, properties, and events for the control.
Clicking one of these entries takes you to the description of that entry. In addition, the
See Also sections associated with individual entries now contain live links to elements
within the same book. References to objects, methods, properties, or events outside of
this book do not use live links.

Conventions
These special formats are used:

NOTE: Provides additional information that is useful but not always essential.

More Information: Refers you to other sections of this guide or to other documents for more
information.

IMPORTANT: Highlights key considerations to keep in mind.

CAUTION: Highlights important situations that could potentially damage data or cause
system failure.

■ Monospace is used for programming elements (such as code fragments,

objects, methods, parameters, and HTML tags) and system elements (such as
file names, directories, paths, and URLs).
■ Monospace bold is used in syntax descriptions to identify statement
elements you must type exactly as shown
■ Monospace italic is used in syntax descriptions to identify placeholders, which
are general names that you replace with names in your code
■ Straight brackets signal options in command-line syntax.
deRead [-llf log_filename] [-debug]
■ An underscore character [_] at the end of a code line indicates that the
ClearBasic statement continues on the next line.

14 About This Guide

ClearBasic Control Reference
 ActiveX control

Description The ActiveX control lets you incorporate third-party controls into your forms. You
can use any control that conforms to the ActiveX interface. For more information, see
the User Interface Editor Guide

Referring to ActiveX You cannot create control objects directly using ClearBasic code. You must associate
Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the ActiveX
control called YourActiveXControl:
Dim YourControl As Control
Set YourControl = YourActiveXControl

Methods The methods available for an ActiveX control are defined by the control vendor. See
the documentation that came with your control for a complete list.

Properties The properties available for an ActiveX control are defined by the control vendor. See
the documentation that came with your control for a complete list.

ClearBasic Control Reference 15

 ActiveX control

16
ClearBasic Control Reference
 Animation control

Description An animation control handles the display of a movie clip in AVI (Audio Video
Interleaved) format. Movie clips are stored in an AVI clip file, which is a self-
contained file containing the video and audio information.

You can use this control to display only simple movie clips. The movie clips you
associate with this control must meet the following criteria:
■ The clip must contain exactly ONE video stream.
■ The video stream must have at least one frame.
■ There can be at most TWO streams in the AVI clip file. (The other stream must
be an audio stream.)
■ The clip must be either uncompressed or compressed using RLE8 compression.
Other compression formats are not supported.
■ The video stream must not contain any palette changes

Animation controls display only the video portion of a movie clip. If the AVI clip file
contains an audio stream, the control ignores that stream.

To load a new AVI clip file into the control, call the control’s Open method. This
method opens the clip file and prepares it for playback. To close a clip file, call the
Close method.

If the control’s AutoPlay property was set to Yes in the User Interface Editor, the Open
method opens the clip file and begins playing the entire movie clip. If the AutoPlay
property is set to No, you must call the Play method to initiate playback. The Play
method lets you specify the start and end frames of the movie clip and control the
number of times the clip is repeated.

If a movie clip is larger or smaller than the control rectangle in which it appears, the
Animation control does not attempt to scale the movie clip. As a result, larger clips
may be partially obscured and smaller clips may leave some empty space. In both
cases, the upper-left corner of the movie clip frame is always situated in the upper-left
corner of the control rectangle.

Referring to You cannot create control objects directly using ClearBasic code. You must associate
Animation Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the animation
control called YourAnimationControl:
Dim YourControl As Control
Set YourControl = YourAnimationControl

ClearBasic Control Reference 17

 Animation control

Methods This object supports the following methods:

■ Close method
■ Open method
■ Play method
■ Stop method

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ Height property [C]
■ Id property [C]
■ Left property [C]
■ Name property [C]
■ Top property [C]
■ Visible property [C]
■ Width property [C]

See Also Control object

18
ClearBasic Control Reference
 Animation control

method Close

Syntax YourControl.Close

Applies To Animation

Description The Close method closes the AVI clip file associated with the Animation control. If
the control does not have a clip file associated with it, this method does nothing.

After calling this method, the Animation control displays an empty space until you
load another clip file. To load a new clip file, call the Open method.

Return Values None

Example The following example illustrates one way to use the Close method. The movie clip
is closed when the user clicks the Close button. The name of the animation control is
animControl.
Sub Close_Click()
animControl.Close
End Sub

See Also Open method

Close 19
ClearBasic Control Reference
 Animation control

method Open

Syntax YourBoolean = YourControl.Open (FileName)

Applies To Animation control

Description The Open method opens the specified AVI clip file and prepares it for playback. If the
control’s AutoPlay property is set to False, your code must call the Play method to
begin playback of the movie clip.

If the control’s AutoPlay property is set to True, this method begins playing the movie
clip immediately after it is opened. The entire movie clip is played repeatedly until the
Close method is called. To play only a selection of the movie clip, you must set the
AutoPlay property to No and then call the Play method.

Parameters The Open method accepts the following parameter:

Parameter Type Description

FileName String Specify a string containing the Windows pathname of the AVI
clip file. You can specify a relative or full pathname.

Return Values Returns True if it successfully opens and prepares the clip file, otherwise returns False.

Example The following example uses the Open method to open a new AVI clip file. The name
of the clip file is stored in the FileName text box control. The name of the animation
control is animControl.
Sub OpenFile_Click()
Dim strName as string
strName = FileName.Value
ret = animControl.Open(strName)
End Sub

See Also Close method

Play method

20 Open
ClearBasic Control Reference
 Animation control

method Play

Syntax YourBoolean = YourControl.Play (Repeat, Start, End)

Applies To Animation control

Description The Play method plays the movie clip associated with this animation control. The
movie clip is played in a background thread so that other tasks may continue.

If you only want to play a portion of the movie clip, specify values for the Start and
End parameters. These values let you specify the beginning and ending frames of the
movie clip. If you specify a Repeat value, only the portion between the Start and
End frames is repeated.

Parameters The Play method accepts the following parameters:

Parameter Type Description

Repeat Long Specify an integer with the number of times you want to repeat
the clip. Specifying a value of -1 causes the movie clip to be
repeated indefinitely.
This parameter is optional and has a default value of -1.
Start Long Specify the index of the frame at which you want to start
playback of the movie clip. This parameter accepts integer values
between 0 and 65535, where 0 indicates the first frame of the clip.
This parameter is optional and is set to first frame of the movie
clip (index 0) by default.
End Long Specify the index of the frame at which you want to end playback
of the movie clip. This parameter accepts integer values between -
1 and 65535. Values between 0 and 65535 indicate a specific frame
index. A value of -1 indicates that play should continue through
to the last frame of the clip.
This parameter is optional and is set to -1 by default.

Return Values This method returns True if it began playing the movie clip, otherwise it returns False.

Example The following example illustrates how to begin playing the movie clip. When the
Start button is pressed, the animControl animation control begins playing its
current movie clip.
Sub Start_Click()
ret = animControl.Play()
End Sub

See Also Open method

Stop method

Play 21
ClearBasic Control Reference
 Animation control

method Stop

Syntax YourControl.Stop

Applies To Animation control

Description The Stop method stops the movie clip currently being played. If no clip is being
played, this method does nothing.

Return Values None

Example The following example illustrates how to stop the playback of a movie clip. When the
Stop button is pressed, the animControl animation control stops playing its current
movie clip.
Sub Stop_Click()
animControl.Stop
End Sub

See Also Play method

22 Stop
ClearBasic Control Reference
 Bitmap control

Description The Bitmap control is a static control for displaying graphics on your form. You can
use the bitmap control to display background graphics or icons. For more
information, see the User Interface Editor Guide

Referring to Bitmap You cannot create control objects directly using ClearBasic code. You must associate
Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the Bitmap
control called YourBitmapControl:
Dim YourControl As Control
Set YourControl = YourBitmapControl

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ Height property [C]
■ Id property [C]
■ Left property [C]
■ Name property [C]
■ Top property [C]
■ Visible property [C]
■ Width property [C]

ClearBasic Control Reference 23

 Bitmap control

24
ClearBasic Control Reference
 Check Box control

Description The check box control represents a two-state button you can use to store user
selections. Typically, you use check boxes to provide the user with simple Yes/No or
True/False choices.

The state of a check box control is independent from all other check box controls. This
distinguishes check boxes from option buttons, which support the selection of only
one button in a group of option buttons.

You can use a check box control to set or retrieve the current value of a check box. The
Value property keeps track of the check box control’s current value.

Referring to Check You cannot create control objects directly using ClearBasic code. You must associate
Box Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the check box
control called YourCheckBoxControl:
Dim YourControl As Control
Set YourControl = YourCheckBoxControl

Source At design time, you have the option of linking a source contextual object to this
control. When a form containing the check box is displayed, the label for the control is
retrieved from the source contextual object. If you do not assign a source contextual
object, the control obtains the label from the Caption property of its property sheet.

Using a source contextual object is advantageous in situations where you may want
the label of the check box control to change dynamically. For example, you could
assign a contextual object whose contents contained the value in a particular database
field. As the value in that field change, so does the control label.

NOTE: Whether you use a source contextual object or a fixed string for the check box label,
you can always change the label by assigning a new value to the control’s Caption property.

Destination At design time, you must link a destination contextual object to the control to store the
value for that control. The destination contextual object must contain a Long integer
value. When the check box is checked, it stores the value 1 in this contextual object;
otherwise it stores the value 0 in the contextual object.

ClearBasic Control Reference 25

 Check Box control

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ Refresh method [C]
■ SetFocus method [C]

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ Caption property
■ ControlType property [C]
■ DataChanged property
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ Name property [C]
■ Parent property
■ Tag property
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

Events This object supports the following events. Events marked with a [C] are documented
with the Control object.
■ Click event
■ GotFocus event [C]
■ LostFocus event [C]

See Also Control object

26
ClearBasic Control Reference
 Check Box control

property Caption

Syntax YourControl.Caption = "CaptionTextString"

controlCaption = YourControl.Caption

Applies To Check Box

Description The Caption property contains a string with the label currently displayed by the
check box control. You assign the initial value for this property at design time by
modifying the values on the control’s property sheet. If the control uses a source
contextual object, the initial value for this property is obtained from that object.

You can change the control’s label at runtime by assigning a new string value to this
property. If you plan to change the control’s label at runtime, set the AutoSize
property of the control to Yes in the User Interface Editor. The AutoSize property
expands the control size to accommodate the new label.

If the control uses a source contextual object for the label, getting this property returns
the value in the contextual object. Assigning a value to this property changes the
value in the source contextual object. If the source contextual object is linked to a
database field, the value in that field is also updated to reflect the changes.

IMPORTANT: On some platforms, your caption changes may not persist when you display or
redisplay the form. If this happens, modify the corresponding Form_Load event procedure
and have it set the caption for the control explicitly.

Caption 27
ClearBasic Control Reference
 Check Box control

property DataChanged

Syntax RetBoolean = YourControl.DataChanged

Applies To Check Box

Description The DataChanged property contains a boolean value indicating whether the user
modified the contents of this control. This value only indicates whether modifications
were made by the user; it does not reflect changes made to the control by your
ClearBasic code.

If you modify the control programmatically, you can set this property to reflect your
changes. Set this property to True to indicate you made modifications; otherwise, set it
to False to indicate the control is unchanged.

28 DataChanged
ClearBasic Control Reference
 Check Box control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To Check Box

Description The Parent property returns the form that contains the control. This property is read-
only.

Parent 29
ClearBasic Control Reference
 Check Box control

property Tag

Syntax YourControl.Tag = "YourStringHere"

controlTag = YourControl.Tag

Applies To Check Box

Description The Tag property contains a custom string that you can assign at runtime. You can
use this string to identify the object internally in your application. You can also use
this property to store extra information about the object.

30 Tag
ClearBasic Control Reference
 Check Box control

property Value

Syntax YourControl.Value = Setting

Setting = YourControl.Value

Applies To Check Box

Description The Value property contains the current value in the check box control. This value
corresponds to the check box state seen by the user. The value in this property is 1 if
the control is checked, otherwise 0.

NOTE: The value in this property may not coincide with the value currently in the control’s
destination contextual object. You can call the control’s Refresh method to synchronize the
two values.

You can assign a new value to this property to change the current state of the control.
Changing the value in this property also changes the value in the associated
destination contextual object.

Value 31
ClearBasic Control Reference
 Check Box control

event Click

Syntax Sub YourControl_Click

Applies To Check Box

Description The Click event occurs when the user presses and releases the mouse button with
the cursor on or in the control. You can use this event to respond to user interactions
with the control.

32 Click
ClearBasic Control Reference
 Command Button control

Description A command button implements a push button you can use to trigger actions. You can
associate command buttons with CeFO-defined actions or with actions you define.
You can also associate a Click event handler with a button to implement your actions
in ClearBasic.

If you use ClearBasic with your command buttons, you can use this object to retrieve
information about the command button. In addition to the common control
properties, the command button control contains additional properties such as the
color of the button and its label, the label text, and whether the button is the default
button of the form.

To implement button actions using ClearBasic, define a Click event for your button.
In your event handler, you can access the command button control methods and
properties, or any other objects using ClearBasic code.

Referring to You cannot create control objects directly using ClearBasic code. You must associate
Command Button controls with a form, frame, or tab using the User Interface Editor. When the form,
Controls frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the command
button control called YourButtonControl:
Dim YourControl As Control
Set YourControl = YourButtonControl

Source At design time, you have the option of linking a source contextual object to this
control. When a form containing the command button is displayed, the label for the
control is retrieved from the source contextual object. If you do not assign a source
contextual object, the control obtains the label from the Caption property of its
property sheet.

Using a source contextual object is advantageous in situations where you may want
the label of the command button control to change dynamically. For example, you
could assign a contextual object whose contents contained the value in a particular
database field. As the value in that field change, so does the control label.

NOTE: Whether you use a source contextual object or a fixed string for the command button
label, you can always change the label by assigning a new value to the control’s Caption
property.

Destination You cannot link a destination contextual object to this control.

ClearBasic Control Reference 33

 Command Button control

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ Refresh method [C]
■ SetFocus method [C]

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ BackColor property
■ Caption property
■ ControlType property [C]
■ Default property
■ Enabled property [C]
■ ForeColor property
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ Name property [C]
■ Parent property
■ Tag property
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

Events This object supports the following events. Events marked with a [C] are documented
with the Control object.
■ Click event
■ GotFocus event [C]
■ LostFocus event [C]

34
ClearBasic Control Reference
 Command Button control

property BackColor

Syntax YourControl.BackColor = "ColorLabel"

CtlBackColor = YourControl.BackColor

Applies To Command Button

Description The BackColor property allows you to set the background color of a control. You can
set this property directly for the control, or indirectly by setting the property on the
contextual object that is linked to the control.

Before using this property, you must establish a color scheme using either the
CreateColorScheme or SetColorScheme method.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored in UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The
label must be in the color scheme that is currently in effect for the form
in which you are performing color operations. (See
CreateColorScheme and SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the text box label and the command button foreground text are
assigned the same color, red, and the background color for the text box is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", _
"Important", "Weak"
ColorList1.AppendItem "red", _

BackColor 35
ClearBasic Control Reference
 Command Button control

"cyan", "blue"

App.CreateColorScheme "Form2020", _
LabelList1,ColorList1
End Sub

Sub Form_Load
App.SetColorScheme "Form2020"

Btn1_Label.ForeColor = "Urgent"
Btn1.ForeColor = "Urgent"
Btn1.BackColor = "Important"
End Sub

See Also CreateColorScheme method (App object in the ClearBasic Object Reference)
SetColorScheme method (App object in the ClearBasic Object Reference)

36 BackColor
ClearBasic Control Reference
 Command Button control

property Caption

Syntax YourControl.Caption = "CaptionTextString"

controlCaption = YourControl.Caption

Applies To Command Button

Description Use the Caption property to get or set the text label for the control. If you want to
assign a new value to this property at runtime, make sure you set the Autosizable
property of the control to Yes in the User Interface Editor.

The Caption property works on a control whether you assigned it a fixed text label
or whether you linked the control to a source contextual object. If the control is linked
to a source contextual object, modifying this property also modifies the value in the
specified field of that contextual object.

IMPORTANT: On some platforms, your caption changes may persist when you display or
redisplay the form. If this happens, set the caption in the Form_Load event procedure for that
form. Also, if the control supports labeling through use of a source contextual object, and you
make this source link at design time, you can use the Fill method on the contextual object to get
the caption to display properly.

One way to use the caption property is to change the caption on a control during the
execution of some procedure to indicate that the procedure is executing.

Settings This property accepts the following settings:

Setting Description
CaptionTextString Specify the text string.
The default caption is the string defined for the form or control at
design time using the User Interface Editor.

Return Values In read mode, this property returns the title of the control or form. If the control is
source linked to a contextual object field, the value of the field is returned.

Caption 37
ClearBasic Control Reference
 Command Button control

property Default

Syntax YourControl.Default = Setting

Setting = YourControl.Default

Applies To Command Button

Description The Default property contains a boolean value indicating whether the command
button is the default button of its form. In addition to receiving mouse clicks like other
buttons, the default button also receives a Click event when the user presses the
Enter key while its form is active.

Setting this property to True makes this button the default button of the form. Setting
this property to False resets the default button to the one that was specified using the
User Interface Editor.

If you set this button to be the form’s default button at design time using the User
Interface Editor, you must not modify this property. For information on setting the
default button of a form using the User Interface Editor, see the User Interface Editor
Guide.

IMPORTANT: If the form containing the command button also contains a multiline text box,
do not set this property to True. Doing so would prevent users from entering carriage returns
in the text box.

See Also Click event

38 Default
ClearBasic Control Reference
 Command Button control

property ForeColor

Syntax YourControl.ForeColor = "ColorLabel"

CtlForeColor = YourControl.ForeColor

Applies To Command Button

Description The ForeColor property allows you to set the color of the control label text. You can
set this property directly for the control, or indirectly by setting the property on the
contextual object that is linked to the control.

Before using this property, you must establish a color scheme using either the
CreateColorScheme or SetColorScheme method.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored in UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The
label must be in the color scheme that is currently in effect for the form
in which you are performing color operations. (See
CreateColorScheme and SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the text box label and the command button foreground text are
assigned the same color, red, and the background color for the text box is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", "Important",

"Weak"

ForeColor 39
ClearBasic Control Reference
 Command Button control

ColorList1.AppendItem "red", "cyan", "blue"

App.CreateColorScheme"Form2020",
LabelList1,ColorList1

End Sub

Sub Form_Load
App.SetColorScheme "Form2020"

TextBox1_Label.ForeColor = "Urgent"
TextBox1.ForeColor = "Urgent"
TextBox1.BackColor = "Important"
End Sub

See Also CreateColorScheme method (App object in the ClearBasic Object Reference)
SetColorScheme method (App object in the ClearBasic Object Reference)

40 ForeColor
ClearBasic Control Reference
 Command Button control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To Command Button

Description The Parent property contains the form object that owns the button. You can use this
property to retrieve a reference to the form object containing the button.

This property is read-only.

Parent 41
ClearBasic Control Reference
 Command Button control

property Tag

Syntax YourControl.Tag = "YourStringHere"

controlTag = YourControl.Tag

Applies To Command Button

Description The Tag property contains a custom string that you assign at runtime. You can use
this string to identify the command button control internally to your application. You
can also use this property to store extra information about the control.

42 Tag
ClearBasic Control Reference
 Command Button control

property Value

Syntax YourControl.Value = Setting

Setting = YourControl.Value

Applies To Command Button

Description The Value property lets you simulate a user click in the command button. The Value
property for a command button is normally set to 0. When you set it to 1, the button
initiates its Click event handler and resets the property to 0.

See Also Click event

Value 43
ClearBasic Control Reference
 Command Button control

event Click

Syntax Sub YourControl_Click

Applies To Command Button

Description The Click event handler for your button is called when a user or program action
triggers the command button. Your Click event handler is called in the following
situations:
■ the user clicks the button using the mouse.
■ the user presses the Enter key while this button is the default button.
■ your code sets the Value property of the command button control to 1.

See Also Value event

44 Click
ClearBasic Control Reference
 Control object

Description The Control object is the physical representation of controls in ClearBasic. You use this
object only in situations where you need to pass a control to a ClearBasic procedure or
function. To use this object, declare a variable of type Control and then set the
variable to the control you want to reference, as shown in the following example:
Dim YourControl As Control
Set YourControl = YourCheckBox1

A procedure or function that receives a Control object can use the ControlType
property to determine the control’s exact type. The code can use this information to
perform different operations for different control types, as shown in the following
example:
Sub ProcessControlInfo(ctrl_obj as Control)
Select Case ctrl_obj.ControlType
Case "CheckBox"
' Process checkboxes
Case "Text Box"
' Process text boxes

...
End Select
End Sub

ClearBasic Control Reference 45

 Control object

Types of Controls ClearBasic supports the following types of controls:

■ Animation control
■ Bitmap control
■ Check Box control
■ Command Button control
■ Dropdown Combo Box control
■ Dropdown List Box control
■ Graph control
■ Grid control
■ Label control
■ List Box control
■ Multiline Text Box control
■ Option Button control
■ ProgressBar control
■ Select CBX control
■ Slider control
■ Tab Button control
■ Text Box control
■ TreeView control
■ UpDown control

For more information on ClearBasic controls, refer to the descriptions for each of the
controls.

Common Control Whenever you need information about the methods, properties, or events of a specific
Information control, the first place to look is the documentation for that control. The
documentation for each control always contains the most up-to-date information
about the control, including a complete list of its methods, properties, and events.

Some controls list methods, properties, and events as being documented with the
Control object. An entry marked this way indicates common functionality that is
shared by all controls. The documentation for these entries is included with the
Control object. The following sections describe the common control functionality.

Control Properties Most controls have a visual interface that the user can interact with on a form. You can
access some of the properties governing this interface at runtime using ClearBasic
code. For example, you can use the Left, Right, Height, and Width properties of a
control to determine the control’s bounding rectangle. The hWnd property available
for some controls gives you access to the native platform data structure associated
with the control.

46
ClearBasic Control Reference
 Control object

Controls also contain several properties that are useful for identification purposes.
The Name property contains the name you assigned to the control using the User
Interface Editor. The Id property contains the form-specific ID associated with the
control.

State information for controls is maintained in two properties. The Visible and
Enabled properties control the end user’s ability to see and modify the control. You
can modify both of these properties at runtime to change the state of the control.

NOTE: The Select CBX control coordinates the interactions between several other controls and
does not have an interface of its own. As a result, Select CBX does not support any of the
common properties supported by other controls.

Managing the Focus When ClarifyCRM eFrontOffice displays a form, it assigns the focus to one of the
form’s controls. Only one control at a time may own the focus for a given form.

The control with the focus is the control that responds when certain keys are typed on
the keyboard. For example, focused buttons simulate a click in the button whenever
the user presses the Enter key. Other controls may respond to the arrow keys or other
navigation related keys.

A control can receive the focus as a result of any of the following actions:
■ At run time, a user clicks on the control to select it.
■ At run time, a user selects the control using an access key, such as the Tab key
or one of the Arrow (←→↑ ↓) keys.
■ A CB procedure or function calls the SetFocus method of the control.

Changes in focus are accompanied by calls to the LostFocus and GotFocus event
handlers of the appropriate controls. If your controls need to respond to changes in
focus, you can use these event handlers to implement your response.

Methods Most controls support the following methods. See the specific control for an exact list
of the methods it supports.
■ Refresh method
■ SetFocus method

47
ClearBasic Control Reference
 Control object

Properties Most controls support the following properties. See the specific control for an exact
list of the properties it supports.
■ ControlType property
■ Enabled property
■ Height property
■ hWnd property
■ Id property
■ Left property
■ Name property
■ Top property
■ Visible property
■ Width property

Events Most controls support the following events. See the specific control for an exact list of
the events it supports.
■ GotFocus event
■ LostFocus event

48
ClearBasic Control Reference
 Control object

method Refresh

Syntax YourControl.Refresh

Applies To Control

Description The Refresh method forces the control to redraw itself. This method also causes the
control to retrieve updated information from its contextual objects, if any. You can call
this method after a series of operations to update the appearance of the control.

In order to save time during operations, some methods and functions do not
automatically redraw the appearance of controls. In those situations, you can call this
method to update the display of a specific control.

Parameters None

Return Values None

See Also Refresh method (ContextualObject object in the ClearBasic Object Reference)

Refresh 49
ClearBasic Control Reference
 Control object

method SetFocus

Syntax YourControl.SetFocus

Applies To Control

Description The SetFocus method acquires the focus for the specified control. You can use this
method to direct system-level events such as keystrokes to the control.

When you call this method, ClearBasic sends a LostFocus event to the control that
currently owns the focus. It then sends a GotFocus event to notify the specified
control that it has received the focus.

Parameters None

Return Values None

See Also GotFocus event

LostFocus event

50 SetFocus
ClearBasic Control Reference
 Control object

property ControlType

Syntax YourControl.ControlType

Applies To Controls

Description The ControlType property contains a string describing the type of the control. If
you need to pass a control object as a parameter to a method, you can use this
property to verify the control type on the receiving end.

This property is read-only and can return one of the following strings:

String Control
"Animation" Animation
"CheckBox" Check box
"CommandButton" Command button
"Control" Graph
"CustomList" Grid
"Dropdown ComboBox" Dropdown Combo Box
"Dropdown ListBox" Dropdown List Box
"GroupBox" Group Box
"Label" Label
"Line" Line
"ListBox" List Box
"Multiline TextBox" Multiline Text Box
"OptionButton" Option Button
"PictureBox" Bitmap
"ProgressBar" Progress Bar
"Slider" Slider
"Tab" Tab
"Text Box" Text Box
"TreeView" Treeview
"UpDown" UpDown

NOTE: ActiveX and Select CBX controls do not support the ControlType property.

Example The following code illustrates one use of this property.

Sub ControlCheck_Click
Dim str1 As string
Dim logstring As string

str1 = List_B1.ControlType
If str1 = "ListBox" Then
logstring = "The control type is List Box"

ControlType 51
ClearBasic Control Reference
 Control object

Else
logstring = "The control type is " + str1
End If
End Sub

52 ControlType
ClearBasic Control Reference
 Control object

property Enabled

Syntax YourControl.Enabled = Setting

Setting = YourControl.Enabled

Applies To Control

Description The Enabled property contains a boolean value indicating whether or not the control
is enabled. You can enable or disable the control by changing the value in this
property. Specify True to enable the control; specify False to disable it.

The Enabled property is affected by calls to the EnableControls and

DisableControls methods of a form. Calling either of these methods changes the
current setting of the Enabled property for each of the specified controls.

See Also EnableControls method (Form object in the ClearBasic Object Reference)
DisableControls method (Form object in the ClearBasic Object Reference)

Enabled 53
ClearBasic Control Reference
 Control object

property Height

Syntax ControlHeight = YourControl.Height

Applies To Control

Description The Height property contains an integer value indicating the height of the control (in
pixels). This property is read-only.

IMPORTANT: At design time in the User Interface Editor, the size of the form and controls are
created with machine-independent coordinates. At runtime, these coordinates are replaced
with machine-dependent coordinates, which can result in slight variations in size properties
for forms and controls.

See Also Left property

Top property
Width property

54 Height
ClearBasic Control Reference
 Control object

property hWnd

Syntax hWndValue = YourControl.hWnd

Applies To Control

Description The hWnd property contains the native platform designator (handle) for the control.
You can use this property in situations where you need to pass the control to a C
function available at runtime. This property is read-only.

Do not cache the value in this property. The hWnd property of a control can change at
runtime. If you store a previous version, it may be invalid by the time you need to use
it.

The data type of the value returned by hWnd varies by platform:

Platform Data Type

Unix Window
Windows HWND

Example In the following test procedure, a check box handle is returned as a string to be
displayed in a text box. The text box Text property is then checked to make sure the
handle was passed properly.
Sub CheckHandle
Results_TBox.text=str$(Checkbox1.hWnd)

If Results_TBox.text <> "" and _

val(Results_TBox.Text) <> 0 Then
App.MsgBox "Displaying the value"
Else
App.MsgBox "Not Displaying the value"
End If
End Sub

hWnd 55
ClearBasic Control Reference
 Control object

property Id

Syntax ControlID = YourControl.Id

Applies To Control

Description The Id property contains an integer value that identifies a control relative to its form.
The User Interface Editor assigns the value of this property automatically at design
time.

Control IDs are unique within the form containing the controls. However, controls on
different forms may use the same control ID.

56 Id
ClearBasic Control Reference
 Control object

property Left

Syntax ControlLeft = YourControl.Left

Applies To Control

Description The Left property contains an integer indicating the position of the left edge of the
control. The position is measured in pixels. This property is read-only.

IMPORTANT: At design time in the User Interface Editor, the size of the form and controls are
created with machine-independent coordinates. At runtime, these coordinates are replaced
with machine-dependent coordinates, which can result in slight variations in size properties
for forms and controls.

See Also Height property

Top property
Width property

Left 57
ClearBasic Control Reference
 Control object

property Name

Syntax ControlName = YourControl.Name

Applies To Control

Description The Name property contains a string with the name of the control. You can use this
string as a unique identifier for controls on a given form. You must assign the name of
the control at design time using the User Interface Editor.

This property is read-only.

58 Name
ClearBasic Control Reference
 Control object

property Top

Syntax ControlTop = YourControl.Top

Applies To Control

Description The Top property contains an integer indicating the position of the top edge of the
control. The position is measured in pixels. This property is read-only.

IMPORTANT: At design time in the User Interface Editor, the size of the form and controls are
created with machine-independent coordinates. At runtime, these coordinates are replaced
with machine-dependent coordinates, which can result in slight variations in size properties
for forms and controls.

See Also Left property

Left property
Width property

Top 59
ClearBasic Control Reference
 Control object

property Visible

Syntax YourControl.Visible = Setting

Setting = YourControl.Visible

Applies To Control

Description The Visible property contains a boolean value that determines whether the control
is hidden or visible. You can read this property to determine the control’s current
visibility or you can set the property to change the visibility. Other methods such as
ShowControls and ShowControlsDeep may also set the value of this property.

Set this property to False to hide the control. Set it to True to make the control visible.

See Also ShowControls method (Form object in the ClearBasic Object Reference)
ShowControlsDeep method (Form object in the ClearBasic Object Reference)

60 Visible
ClearBasic Control Reference
 Control object

property Width

Syntax ControlWidth = YourControl.Width

Applies To Control

Description The Width property contains an integer value indicating the width of the control (in
pixels). This property is read-only.

IMPORTANT: At design time in the User Interface Editor, the size of the form and controls are
created with machine-independent coordinates. At runtime, these coordinates are replaced
with machine-dependent coordinates, which can result in slight variations in size properties
for forms and controls.

See Also Height property

Left property
Top property

Width 61
ClearBasic Control Reference
 Control object

event GotFocus

Syntax Sub YourControl_GotFocus

Applies To Control

Description The GotFocus event notifies a control that it has received the focus. This event occurs
immediately after the control actually receives the focus. The control must be enabled
and visible to receive this event.

The focus determines which control receives keyboard events. You can use your
GotFocus event handler to update the control’s appearance or state information.

At runtime, a control gains the focus in any of the following situations:

■ The user selects the control using the mouse.
■ The user selects the control using the Tab key.
■ The form’s ClearBasic code calls the SetFocus method of the control.

Controls do not gain focus as the result of user selections in the menu bar.

Example The following example illustrates the use of the GotFocus and LostFocus events.
Sub YourControl_GotFocus
Debug.Print "Your control got focus."
End Sub

Sub YourControl_LostFocus
Debug.Print "Your control lost focus."
End Sub

See Also SetFocus method

LostFocus event

62 GotFocus
ClearBasic Control Reference
 Control object

event LostFocus

Syntax Sub YourControl_LostFocus

Applies To Control

Description The LostFocus event notifies the control that it is about to lose the focus. This event
occurs immediately before the control actually loses the focus. The control must be
enabled and visible to receive this event.

The focus determines which control receives keyboard events. You can use your
LostFocus event handler to validate control information or handle any focus-related
updates.

At runtime, a control loses the focus in the following situations:

■ The user selects a different control on the same form.
■ The user selects a different form.
■ The form’s ClearBasic code calls the SetFocus method of a different control.

Controls do not lose focus as the result of user selections in the menu bar. Controls
also do not lose focus when the user clicks one of the window’s built-in scroll bars.

Example The following example illustrates the use of the GotFocus and LostFocus events.
Sub YourControl_GotFocus
Debug.Print "Your control got focus."
End Sub

Sub YourControl_LostFocus
Debug.Print "Your control lost focus."
End Sub

See Also SetFocus method

GotFocus event

LostFocus 63
ClearBasic Control Reference
 Control object

64 LostFocus
ClearBasic Control Reference
 Dropdown Combo Box
control

Description The dropdown combo box control consists of a writable text box with a dropdown list
box arrow. The text box displays only the selected item from among a list of items. The
remaining list items are displayed when the dropdown list box arrow is clicked. (The
dropdown combo box control is similar to the dropdown list box control except that
the dropdown list box control is read-only.)

The user can select an item from the dropdown combo box control in one of the
following ways:
■ By clicking the dropdown list box arrow and selecting an item from the
displayed list
■ By typing the name of the item in the text box. (The item name must be an item
in the item list.)

You should use this control to display a list of items when space is limited and you
expect the user to know what’s on the list. For example, you might want to use this
control to allow the user to select from among a list of states or provinces in your
country.

You can use the methods of the dropdown combo box control to modify the list at
runtime. You can add new items to the list or remove existing items. You can move
existing items up or down in the list. You can also get and set the current selection for
the list.

This control does not include a label automatically. To add a label, create a label
control and place it next to this control.

Referring to You cannot create control objects directly using ClearBasic code. You must associate
Dropdown Combo controls with a form, frame, or tab using the User Interface Editor. When the form,
Box Controls frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the dropdown
combo box control called YourDDComboBoxControl:
Dim YourControl As Control
Set YourControl = YourDDComboBoxControl

Source The source contextual object of a dropdown combo box control stores the list of items
to be displayed in the control. Each item in the list is a string containing the text to
display for the item. You can specify the items for this list at design time using the
User Interface Editor or at runtime using the methods of the dropdown combo box
control.

ClearBasic Control Reference 65

 Dropdown Combo Box control

Destination The destination contextual object of a dropdown combo box control stores the list item
that is currently selected. This contextual object must specify a string data type.

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ AppendItem method
■ Clear method
■ Contains method
■ Down method
■ GetList method
■ GetSelected method
■ Refresh method [C]
■ RemoveByItem method
■ RemoveItem method
■ RemoveSelected method
■ ReplaceItem method
■ SelectedIndexes method
■ SelectedList method
■ SetFocus method [C]
■ SetSelected method
■ UnSelect method
■ Up method

66
ClearBasic Control Reference
 Dropdown Combo Box control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ DataChanged property
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ ListCount property
■ ListIndex property
■ Name property [C]
■ NewIndex property
■ Parent property
■ Selected property
■ Sorted property
■ Tag property
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

Events This object supports the following events. Events marked with a [C] are documented
with the Control object.
■ Click event
■ GotFocus event [C]
■ LostFocus event [C]

67
ClearBasic Control Reference
 Dropdown Combo Box control

method AppendItem

Syntax YourControl.AppendItem ItemToAppend

YourControl.AppendItem ListOfItems

Applies To Dropdown Combo Box

Description The AppendItem method appends a single item or list of items to the control. The
control must have a source contextual object to store the items added by this method.
This method automatically updates the items in the source contextual object.

You can use this method in a Form_Load procedure to initialize the control. If you
had not previously initialized the control’s source contextual object, you must do so
by calling its Fill method before calling this method.

This method updates the value in the NewIndex property to reflect the index of the
newly added item. When you add a list of items, the NewIndex property reflects the
index of the first item in the list.

Parameters This method accepts one of the following parameters:

Parameters Type Values

ItemToAppend String Specify a string with the item text.
ListOfItems List Specify a List object containing one or more strings.
Each string contains the text for a single item.

Return Values None

Example In the following example, NewCourse is added to the combo box Combo1, then the
combo box is refreshed to display the added item.
Sub AppendToControl
Combo1.AppendItem "NewCourse"
Combo1.Refresh
End Sub

See Also Contains method

RemoveItem method
NewIndex property

68 AppendItem
ClearBasic Control Reference
 Dropdown Combo Box control

method Clear

Syntax YourControl.Clear

Applies To Dropdown Combo Box

Description The Clear method removes all of the items from the dropdown combo box control
and from the control’s source contextual object. This method also resets the value of
the NewIndex property to -1.

After calling this method, call the form’s ForceRedraw method to update the
control’s display.

Parameters None

Return Values None

See Also NewIndex property

Empty method (ContextualObject object in the ClearBasic Object Reference)
ForceRedraw method (Form object in the ClearBasic Object Reference)

Clear 69
ClearBasic Control Reference
 Dropdown Combo Box control

method Contains

Syntax YourBoolean = YourControl.Contains (ItemToFind)

Applies To Dropdown Combo Box

Description The Contains method returns a boolean value indicating whether the specified item
is in the list.

Parameters This method takes the following parameter:

Parameter Type Description

ItemToFind String Specify the string you want to search for in the combo box list.

Return Values Returns True if the item is already in the control, or False if the item is not in the
control.

Example The following test routine shows one use of the Contains method. In the example,
the method is used to verify that an item has been properly added to a control.

Notice that the count of items in the control is taken before the new item is added.
This means that the index of Clover should be equal to the count.
Sub TestSub_Click
Dim I As integer
Dim J As integer

I= ComboBox1.ListCount
ComboBox1.AppendItem "Clover"
ComboBox1.Refresh
J= ComboBox1.NewIndex

If (J = I) Then
If ComboBox1.Contains("Clover") Then
App.MsgBox "Clover is here!"
Else
App.MsgBox "Clover is not here!"
End If
Else
App.MsgBox "Item not added properly"
End If
End Sub

70 Contains
ClearBasic Control Reference
 Dropdown Combo Box control

method Down

Syntax YourControl.Down

Applies To Dropdown Combo Box

Description The Down method moves the currently selected item down one position in the
control’s list. Any displaced items are moved up to make room for the item. If the
selected item is already at the bottom of the list, it remains there.

If no item is selected, this method does nothing.

Parameters None

Return Values None

Example In the following example, a loop loads five strings into an empty dropdown combo
box. The strings are sequenced Item 1 to Item 5, and Item 2 is moved down. At this
point, the index of Item 2 should become 2 and the index of Item 3 should become 1.
GetList is used to check this, returning the item at index 1 in the control. If Item 3 is at
that index, the appropriate notification is stored in Logstr.
Sub DownTest
Dim Hold1 As string
Dim Logstr As string

Combo1.clear

For i = 1 to 5
Combo1.AppendItem "item"+Str$(i)
Combo1.Refresh
Next i

Combo1.setSelected "item 2"

Combo1.down 1
Combo1.refresh

Hold1 = Combo1.GetList(1)

If Hold1 = "item 3" Then

Logstr = "Second item moved one position _
down"
Else
Logstr = "Second item did not move down"
End If
End Sub

See Also Up method

Down 71
ClearBasic Control Reference
 Dropdown Combo Box control

method GetList

Syntax Set YourList = YourControl.GetList

YourRetVar = YourControl.GetList (Index)

Applies To Dropdown Combo Box

Description The GetList method returns items currently in the dropdown combo box. If you
specify an index of an item in the list, this method returns that item. If you do not
specify any parameters, this method returns the entire list of items.

The source contextual object associated with the control must be initialized before
calling this method.

Parameters This method accepts the following parameter:

Parameter Type Description

Index Long This parameter is optional. You can specify the index of the
item you want returned.
If you don’t specify an index, the entire list is returned.

Return Values Returns a List object containing zero or more strings. Each string in the list
corresponds to an item in the dropdown combo box control.

If the Index parameter was specified, this method returns a String containing the text
of the desired item.

Example In the following example, a loop loads five strings into an empty dropdown combo
box. The strings are sequenced Item 1 to Item 5, and Item 2 is moved down. At this
point, the index of Item 2 should become 2 and the index of Item 3 should become 1.
GetList is used to check this, returning the item at index 1 in the control. If Item 3 is at
that index, the appropriate notification is stored in Logstr.
Sub DownTest
Dim Hold1 As string
Dim Logstr As string
Combo1.Clear

For i = 1 to 5
Combo1.AppendItem "item"+Str$(i)
Combo1.Refresh
Next i

Combo1.setSelected "item 2"

Combo1.down 1
Combo1.refresh

Hold1 = Combo1.GetList(1)

72 GetList
ClearBasic Control Reference
 Dropdown Combo Box control

If Hold1 = "item 3" Then

Logstr = "Second item moved one position _
down"
Else
Logstr = "Second item did not move down"
End If
End Sub

See Also GetSelected method

GetList 73
ClearBasic Control Reference
 Dropdown Combo Box control

method GetSelected

Syntax YourBool = YourControl.GetSelected(SelectedItem)

If YourControl.GetSelected(SelectedItem) Then
...

Applies To Dropdown Combo Box

Description The GetSelected method returns the currently selected item in the dropdown
combo box control. The text for the item is returned in the SelectedItem parameter,
which you must provide when you call the method. The method returns a boolean
value indicating whether or not an item was actually selected.

Parameters This method accepts the following parameter:

Parameter Type Description

SelectedItem String Specify the name of a String variable. The selected item is
placed into that variable.

Return Values Returns True if an item was selected, otherwise False.

See Also SelectedIndexes method

SelectedList method
SetSelected method

74 GetSelected
ClearBasic Control Reference
 Dropdown Combo Box control

method RemoveByItem

Syntax Set BadItems = YourControl.RemoveByItem ItemToRemove

Set BadItems = YourControl.RemoveByItem ListOfItems

Applies To Dropdown Combo Box

Description The RemoveByItem method removes one or more items from the dropdown combo
box control. After removing the items, this method sets the value in the NewIndex
property to -1. You can use this method to selectively remove items from the
dropdown combo box control.

As the method processes the list of items, it keeps track of those items that were not in
the control’s list. Upon completion, the method returns the list of missing items to
you. Duplicate entries are considered missing items and are therefore returned in this
list.

Parameters This method accepts one of the following parameters:

Parameter Type Description

ItemToRemove String Specify a name of the item you want to remove.
ListOfItems List Specify a list of String objects. Each string in the list
contains the name of an item you want to remove.

Return Values Returns a List object containing zero or more strings. Each string contains the name
of an item that was not in the control’s list.

See Also RemoveItem method

ReplaceItem method
NewIndex property

RemoveByItem 75
ClearBasic Control Reference
 Dropdown Combo Box control

method RemoveItem

Syntax YourControl.RemoveItem Index

Applies To Dropdown Combo Box

Description The RemoveItem method removes the specified item from the dropdown combo box
control. If the specified item is currently selected, this method clears the selection
before removing the item. After removing the item, this method sets the value in the
NewIndex property to -1

Parameters This method accepts the following parameters:

Parameter Type Description

Index Long Specify the index of the item to remove. This index is 0
based, that is, the first item is at index 0, the second at index
1, and so on.
If the index you specify is less than 0 or greater than the
number of items in the control, this method generates an
error.

Return Values None

See Also AppendItem method

RemoveByItem method
NewIndex property

76 RemoveItem
ClearBasic Control Reference
 Dropdown Combo Box control

method RemoveSelected

Syntax RetInteger = YourControl.RemoveSelected

Applies To Dropdown Combo Box

Description The RemoveSelected method removes the currently selected items from the
dropdown combo box control. This method clears the current selection and sets the
value in the NewIndex property to -1.

Parameters None

Return Values Returns a Long integer with the number of items remaining in the control after the
removal of the selected items.

Example The following code snippet shows one application of this method. Selected items are
removed from MyControl and the number of items remaining in the control are
returned to Count. If no more items are left in the control, the REMOVE button is
disabled.
Count = MyControl.RemoveSelected
If Count = 0 Then
Remove.Enabled = False
End If

See Also RemoveByItem method

RemoveItem method
ReplaceItem method
NewIndex property

RemoveSelected 77
ClearBasic Control Reference
 Dropdown Combo Box control

method ReplaceItem

Syntax YourControl.ReplaceItem NewItemText, Index

Applies To Dropdown Combo Box

Description The ReplaceItem method replaces the item at the specified index with the desired
string. This method does not affect the current selection or the value in the NewIndex
property.

Parameters This method takes the following parameters:

Parameter Type Description

NewItemText String Specify a string containing the replacement text.
Index Long Specify the index of the item to replace. This index is 0
based, that is, the first item is at index 0, the second at index
1, and so on.
If the index you specify is less than 0 or greater than the
number of items in the control, this method generates an
error.

Return Values None

See Also AppendItem method

RemoveItem method

78 ReplaceItem
ClearBasic Control Reference
 Dropdown Combo Box control

method SelectedIndexes

Syntax Set YourList = YourControl.SelectedIndexes

Applies To Dropdown Combo Box

Description The SelectedIndexes method returns a list of indexes corresponding to the

currently selected items. For dropdown combo box controls, this list can contain at
most one item.

This method is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected items from each.

Parameters None

Return Values Returns a List object containing zero or one long integer. The integer is a 0-based
index into the control’s list of items.

See Also GetSelected method

SelectedList method
Selected property

SelectedIndexes 79
ClearBasic Control Reference
 Dropdown Combo Box control

method SelectedList

Syntax Set YourRetList = YourControl.SelectedList

Applies To Dropdown Combo Box

Description The SelectedList method returns a list containing the currently selected items in
the control. Because dropdown combo boxes only allow the selection of one item at a
time, this list can contain at most one item.

This method is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected items from each.

Parameters None

Return Values Returns a List object containing zero or more strings. Each string in the list
corresponds to a selected item in the control. If no items are selected, the returned list
is empty.

See Also GetSelected method

RemoveSelected method
SelectedIndexes method

80 SelectedList
ClearBasic Control Reference
 Dropdown Combo Box control

method SetSelected

Syntax YourControl.SetSelected ItemToSelect

Applies To Dropdown Combo Box

Description The SetSelected method selects the specified item. If there was an existing
selection, this method clears it before selecting the new item.

Only one item at a time may be selected for a dropdown combo box control. If you
specify an item that does not exist in the control’s list, this method exits without
clearing the previous selection.

Parameters This method takes the following parameters:

Parameter Type Description

ItemToSelect String Specify the item text corresponding to the item you want to
select. This string is case-sensitive and must match the item
text in the control exactly.

Return Values None

See Also Contains method

GetSelected method

SetSelected 81
ClearBasic Control Reference
 Dropdown Combo Box control

method UnSelect

Syntax YourControl.Unselect

Applies To Dropdown Combo Box

Description The UnSelect method clears the control’s current selection.

Parameters None

Return Values None

See Also SetSelected method

Selected property

82 UnSelect
ClearBasic Control Reference
 Dropdown Combo Box control

method Up

Syntax YourControl.Up

Applies To Dropdown Combo Box

Description The Up method moves the currently selected item up one position in the control’s list.
Any displaced items are moved down to make room for the item. If the selected item
is already at the beginning of the list, it remains there.

If no item is selected, this method does nothing.

Parameters None

Return Values None

See Also Down method

Up 83
ClearBasic Control Reference
 Dropdown Combo Box control

property DataChanged

Syntax RetBoolean = YourControl.DataChanged

YourControl.DataChanged = NewSetting

Applies To Dropdown Combo Box

Description The DataChanged property contains a boolean value indicating whether the user
modified the contents of this control. This value only indicates whether modifications
were made by the user; it does not reflect changes made to the control by your
ClearBasic code.

If you modify the control programmatically, you can set this property to reflect your
changes. Set this property to True to indicate you made modifications; otherwise, set it
to False to indicate the control is unchanged.

84 DataChanged
ClearBasic Control Reference
 Dropdown Combo Box control

property ListCount

Syntax ItemCount = YourControl.ListCount

Applies To Dropdown Combo Box

Description The ListCount property contains a Long integer indicating the total number of
items in the dropdown combo box control.

This property is read-only.

See Also ListIndex property

ListCount 85
ClearBasic Control Reference
 Dropdown Combo Box control

property ListIndex

Syntax SelectedItem = YourControl.ListIndex

Applies To Dropdown Combo Box

Description The ListIndex property returns the index of the control’s currently selected item. A
dropdown combo box control always has exactly one item selected. The selected item
appears in the text box portion of the control.

List indexes are 0-based, that is, the first item is at index 0, the second at index 1, and
so on. As a result, the maximum index is always one less than the total number of
items as stored in the ListCount property.

This property is read-only.

Example The following procedure illustrates the use of this property.

Sub MyClick_Click
Dim MyRetInt As Integer

MyRetInt = MyComboBox.ListIndex

If MyRetInt = -1 Then
App.MsgBox "No Selection"
Else
‘Do this
...
End If
End Sub

See Also ListCount property

86 ListIndex
ClearBasic Control Reference
 Dropdown Combo Box control

property NewIndex

Syntax ItemIndex = YourControl.NewIndex

Applies To Dropdown Combo Box

Description The NewIndex property contains a long integer with the index of the most recently
added item. You can pass this index to other methods to modify (or subsequently
remove) the item.

When you add a new item, the AppendItem method updates this property to reflect
the position of any new items. Methods that remove items reset the value in this
property to -1.

This property is read-only.

See Also AppendItem method

Clear method
RemoveByItem method
RemoveItem method
RemoveSelected method
ReplaceItem method

NewIndex 87
ClearBasic Control Reference
 Dropdown Combo Box control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To Dropdown Combo Box

Description The Parent property contains the form object that owns the control. You can use this
property in to retrieve a reference to the form object containing the dropdown combo
box.

This property is read-only.

88 Parent
ClearBasic Control Reference
 Dropdown Combo Box control

property Selected

Syntax SelectedItem = YourControl.Selected

Applies To Dropdown Combo Box

Description The Selected property contains the item currently selected in the control. For
dropdown combo boxes, the item is a string. Dropdown combo boxes always have
exactly one item selected.

This property is read-only.

This property is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected item from each.

See Also GetSelected method

SelectedIndexes method
SelectedList method

Selected 89
ClearBasic Control Reference
 Dropdown Combo Box control

property Sorted

Syntax IsSorted = YourList.Sorted

Applies To Dropdown Combo Box

Description The Sorted property contains a boolean value indicating whether the items in the
control’s list are sorted. This property contains the value True if the items in the
control’s source contextual object are sorted, otherwise False.

This property is read-only.

See Also Sort method (ContextualObject object in the ClearBasic Object Reference)

90 Sorted
ClearBasic Control Reference
 Dropdown Combo Box control

property Tag

Syntax YourControl.Tag = "YourStringHere"

ControlTag = YourControl.Tag

Applies To Dropdown Combo Box

Description The Tag property contains a custom string that you assign at runtime. You can use
this string to identify the control internally to your application. You can also use this
property to store extra information about the control.

Tag 91
ClearBasic Control Reference
 Dropdown Combo Box control

property Value

Syntax YourControl.Value = Setting

ControlValue = YourControl.Value

Applies To Dropdown Combo Box

Description The Value property contains a string with the item text for the currently selected
item. You can get this property to retrieve the item text for the selected item.

If you assign a value to this property, you must specify a string the name of the item
you want to select. This string is case-sensitive and must match the name of an item in
the list exactly. The string you specify is stored in the control’s destination contextual
object.

NOTE: It is possible to update the contents of the control’s destination contextual object
without changing the value in this property. Before getting this property, you can call the
Refresh method to ensure the control’s caches are up-to-date.

92 Value
ClearBasic Control Reference
 Dropdown Combo Box control

property Click

Syntax Sub YourControl_Click

Applies To Dropdown Combo Box

Description The Click event handler for your dropdown combo box is called when the user
presses and releases the mouse button over the control. A Click event usually
indicates the selection of an item from the control’s list. However, this event does not
distinguish between the selection of a new item or of the same item.

You can use the Click event handler to perform other actions based on the selection
of an item.

Click 93
ClearBasic Control Reference
 Dropdown Combo Box control

94 Click
ClearBasic Control Reference
 Dropdown List Box control

Description The dropdown list box control consists of a read-only text box with a dropdown list
box arrow. The text box displays only the selected item from among a list of items. The
remaining list items are displayed when the dropdown list box arrow is clicked.

You should use this control to display a list of items when space is too limited to use a
list box control. This control is similar to both the list box and dropdown combo box
control. The control displays a fixed set of list items like the list box control but takes
up the same amount of space as a dropdown combo box control.

You can use dropdown list boxes to display several different types of data. When you
create the control in the User Interface Editor, you associate one of three list types to
the control. These list types let you fill the contents of the control with static items or
with items loaded dynamically from the database.

You can use the methods of the dropdown list box control to modify the contents of
the list at runtime. You can add new items to the list or remove existing items. You can
move existing items up or down in the list. You can also get and set the current
selection for the list.

This control does not include a label automatically. To add a label, create a label
control and place it next to this control.

Referring to You cannot create control objects directly using ClearBasic code. You must associate
Dropdown List Box controls with a form, frame, or tab using the User Interface Editor. When the form,
Controls frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the dropdown
list box control called YourDDLIstBoxControl:
Dim YourControl As Control
Set YourControl = YourDDListBoxControl

Source The source contextual object of a dropdown list box control stores the list of items to
be displayed in the control. Each item in the list is a string containing the text to
display for the item. You can specify the items for this list at design time using the
User Interface Editor or at runtime using the methods of the dropdown list box
control.

Destination The destination contextual object of a dropdown list box control stores the list item
that is currently selected. This contextual object must specify a string data type.

ClearBasic Control Reference 95

 Dropdown List Box control

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ AppendItem method
■ Clear method
■ Contains method
■ Down method
■ GetList method
■ GetSelected method
■ Refresh method [C]
■ RemoveByItem method
■ RemoveItem method
■ RemoveSelected method
■ ReplaceItem method
■ SelectedIndexes method
■ SelectedList method
■ SetFocus method [C]
■ SetSelected method
■ UnSelect method
■ Up method

96
ClearBasic Control Reference
 Dropdown List Box control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ DataChanged property
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ ListCount property
■ ListIndex property
■ Name property [C]
■ NewIndex property
■ Parent property
■ Selected property
■ Sorted property
■ Tag property
■ Top property [C]
■ UserData property
■ Value property
■ Visible property [C]
■ Width property [C]

Events This object supports the following events. Events marked with a [C] are documented
with the Control object.
■ Click event
■ GotFocus event [C]
■ LostFocus event [C]

97
ClearBasic Control Reference
 Dropdown List Box control

method AppendItem

Syntax YourControl.AppendItem ItemToAppend

YourControl.AppendItem ListOfItems

Applies To Dropdown List Box

Description The AppendItem method appends a single item or list of items to the control. The
control must have a source contextual object to store the items added by this method.
This method automatically updates the items in the source contextual object.

You can use this method in a Form_Load procedure to initialize the control. If you
had not previously initialized the control’s source contextual object, you must do so
by calling its Fill method before calling this method.

This method updates the value in the NewIndex property to reflect the index of the
newly added item. When you add a list of items, the NewIndex property reflects the
index of the first item in the list.

Parameters This method accepts the following parameters:

Parameters Type Values

ItemToAppend String Specify a string with the item text.
ListOfItems List Specify a List object containing one or more strings. Each
string contains the text for a single item.

Return Values None

Example In the following example, NewCourse is added to the dropdown list box DDListBox1,
then the control is refreshed to display the added item.
Sub AppendToControl
DDListBox1.AppendItem "NewCourse"
DDListBox1.Refresh
End Sub

See Also Contains event

RemoveItem event
NewIndex property

98 AppendItem
ClearBasic Control Reference
 Dropdown List Box control

method Clear

Syntax YourControl.Clear

Applies To Dropdown List Box

Description The Clear method removes all of the items from the dropdown list box control and
from the control’s source contextual object. This method also resets the value of the
NewIndex property to -1.

After calling this method, call the form’s ForceRedraw method to update the
control’s display.

Parameters None

Return Values None

See Also NewIndex property

Empty method (Contextual Object object in the ClearBasic Object Reference)
ForceRedraw method (Form object in the ClearBasic Object Reference)

Clear 99
ClearBasic Control Reference
 Dropdown List Box control

method Contains

Syntax YourBoolean = YourControl.Contains (ItemToFind)

Applies To Dropdown List Box

Description The Contains method returns a boolean value indicating whether the specified item
is in the list.

Parameters This method accepts the following parameter:

Parameter Type Description

ItemToFind String Specify the string you want to search for in the control’s list
of items.

Return Values Returns True if the item is already in the control, or False if the item is not in the
control.

Example The following test routine shows one use of the Contains method. In the example,
Contains is used to verify that an item has been properly added to a control.

Notice that the count of items in the control is taken before the new item is added.
This means that the index of Clover should be equal to the count.
Sub TestSub_Click
Dim I As integer
Dim J As integer

I= DDListBox1.ListCount
DDListBox1.AppendItem "Clover"
DDListBox1.Refresh
J= DDListBox1.NewIndex

If (J = I) Then
If DDListBox1.Contains("Clover") Then
App.MsgBox "Clover is here!"
Else
App.MsgBox "Clover is not here!"
End If
Else
App.MsgBox "Item not added properly"
End If
End Sub

100 Contains
ClearBasic Control Reference
 Dropdown List Box control

method Down

Syntax YourControl.Down

Applies To Dropdown List Box

Description The Down method moves the currently selected item down one position in the
control’s list. Any displaced items are moved up to make room for the item. If the
selected item is already at the bottom of the list, it remains there.

If no item is selected, this method does nothing.

Parameters None

Return Values None

Example In the following example, a loop loads five strings into an empty dropdown list box.
The strings are sequenced Item 1 to Item 5, and Item 2 is moved down. At this point,
the index of Item 2 should become 2 and the index of Item 3 should become 1. GetList
is used to check this, returning the item at index 1 in the control. If Item 3 is at that
index, the appropriate notification is stored in Logstr.
Sub DownTest
Dim Hold1 As string
Dim Logstr As string

DDListBox1.Clear

For i = 1 to 5
DDListBox1.AppendItem "item"+Str$(i)
DDListBox1.Refresh
Next i

DDListBox1.setSelected "item 2"

DDListBox1.down 1
DDListBox1.refresh

Hold1 = DDListBox1.GetList(1)

If Hold1 = "item 3" Then

Logstr = "Second item moved one position _
down"
Else
Logstr = "Second item did not move down"
End If
End Sub

See Also Up method

Down 101
ClearBasic Control Reference
 Dropdown List Box control

method GetList

Syntax Set YourList = YourControl.GetList

YourRetVar = YourControl.GetList (Index)

Applies To Dropdown List Box

Description TheGetList method returns items currently in the dropdown list box. If you specify
an index of an item in the list, this method returns that item. If you do not specify any
parameters, this method returns the entire list of items.

The source contextual object associated with the control must be initialized before
calling this method.

Parameters This method accepts the following parameter:

Parameter Type Description

Index Long This parameter is optional. You can specify the index of the
item you want returned.
If you don’t specify an index, the entire list is returned.

Return Values Returns a List object containing zero or more strings. Each string in the list
corresponds to an item in the dropdown list box control.

If the Index parameter was specified, this method returns a String containing the text
of the desired item.

Example In the following example, a loop loads five strings into an empty dropdown list box.
The strings are sequenced Item 1 to Item 5, and Item 2 is moved down. At this point,
the index of Item 2 should become 2 and the index of Item 3 should become 1. GetList
is used to check this, returning the item at index 1 in the control. If Item 3 is at that
index, the appropriate notification is stored in Logstr.
Sub DownTest
Dim Hold1 As string
Dim Logstr As string
DDListBox1.clear

For i = 1 to 5
DDListBox1.AppendItem "item"+Str$(i)
DDListBox1.Refresh
Next i

DDListBox1.setSelected "item 2"

DDListBox1.down 1
DDListBox1.refresh

Hold1 = DDListBox1.GetList(1)

102 GetList
ClearBasic Control Reference
 Dropdown List Box control

If Hold1 = "item 3" Then

Logstr = "Second item moved one position _
down"
Else
Logstr = "Second item did not move down"
End If
End Sub

See Also GetSelected method

GetList 103
ClearBasic Control Reference
 Dropdown List Box control

method GetSelected

Syntax YourBool = YourControl.GetSelected(SelectedItem)

If YourControl.GetSelected(SelectedItem) Then
...

Applies To Dropdown List Box

Description The GetSelected method returns the currently selected item in the dropdown list
box. The text for the item is returned in the SelectedItem parameter, which you
must provide when you call the method. The method returns a boolean value
indicating whether or not an item is selected.

Parameters This method accepts the following parameter:

Parameter Type Description

SelectedItem String Specify the name of a String variable. The selected item is
placed into that variable.

Return Values Returns True if an item was selected, otherwise False.

See Also SelectedIndexes method

SelectedList method
SetSelected method

104 GetSelected
ClearBasic Control Reference
 Dropdown List Box control

method RemoveByItem

Syntax Set BadItems = YourControl.RemoveByItem ItemToRemove

Set BadItems = YourControl.RemoveByItem ListOfItems

Applies To Dropdown List Box

Description The RemoveByItem method removes one or more items from the dropdown list box.
After removing the items, this method sets the value in the NewIndex property to -1.
You can use this method to selectively remove items from the dropdown list box
control.

As the method processes the list of items, it keeps track of those items that were not in
the control’s list. Upon completion, the method returns the list of missing items to
you. Duplicate entries are considered missing items and are therefore returned in this
list.

Parameters This method accepts the following parameters:

Parameter Type Description

ItemToRemove String Specify a name of the item you want to remove.
ListOfItems List Specify a list of String objects. Each string in the list
contains the name of an item you want to remove.

Return Values Returns a List object containing zero or more strings. Each string contains the name
of an item that was not in the control’s list.

See Also RemoveItem method

ReplaceItem method
NewIndex property

RemoveByItem 105
ClearBasic Control Reference
 Dropdown List Box control

method RemoveItem

Syntax YourControl.RemoveItem Index

Applies To Dropdown List Box

Description The RemoveItem method removes the specified item from the dropdown list box
control. If the specified item is currently selected, this method clears the selection
before removing the item. After removing the item, this method sets the value in the
NewIndex property to -1

Parameters This method accepts the following parameters:

Parameter Type Description

Index Long Specify the index of the item to remove. This index is 0 based,
that is, the first item is at index 0, the second at index 1, and so
on.
If the index you specify is less than 0 or greater than the number
of items in the control, this method generates an error.

Return Values None

See Also AppendItem method

RemoveByItem method
NewIndex property

106 RemoveItem
ClearBasic Control Reference
 Dropdown List Box control

method RemoveSelected

Syntax RetInteger = YourControl.RemoveSelected

Applies To Dropdown List Box

Description The RemoveSelected method removes the currently selected items from the
dropdown list box control. This method clears the current selection and sets the value
in the NewIndex property to -1.

Parameters None

Return Values Returns a Long integer with the number of items remaining in the control after the
removal of the selected items.

Example The following code snippet shows one application of this method. Selected items are
removed from MyControl and the number of items remaining in the control are
returned to Count. If no more items are left in the control, the REMOVE button is
disabled.
Count = MyControl.RemoveSelected
If Count = 0 Then
REMOVE.Enabled = False
End If

See Also RemoveByItem method

RemoveItem method
ReplaceItem method
NewIndex property

RemoveSelected 107
ClearBasic Control Reference
 Dropdown List Box control

method ReplaceItem

Syntax YourControl.ReplaceItem NewItemText, Index

Applies To Dropdown List Box

Description The ReplaceItem method replaces the item at the specified index with the desired
string. This method does not affect the current selection or the value in the NewIndex
property.

Parameters This method accepts the following parameters:

Parameter Type Description

NewItemText String Specify a string containing the replacement text.
Index Long Specify the index of the item to replace. This index is 0
based, that is, the first item is at index 0, the second at index
1, and so on.
If the index you specify is less than 0 or greater than the
number of items in the control, this method generates an
error.

Return Values None

See Also AppendItem method

RemoveItem method

108 ReplaceItem
ClearBasic Control Reference
 Dropdown List Box control

method SelectedIndexes

Syntax Set YourList = YourControl.SelectedIndexes

Applies To Dropdown List Box

Description The SelectedIndexes method returns a list of indexes corresponding to the

currently selected items. For dropdown list box controls, this list can contain at most
one item.

This method is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected items from each.

Parameters None

Return Values Returns a List object containing zero or one long integer. The integer is a 0-based
index into the control’s list of items.

See Also GetSelected method

SelectedList method
Selected property

SelectedIndexes 109
ClearBasic Control Reference
 Dropdown List Box control

method SelectedList

Syntax Set YourRetList = YourControl.SelectedList

Applies To Dropdown List Box

Description The SelectedList method returns a list containing the currently selected items in
the control. Because dropdown list boxes only allow the selection of one item at a
time, this list can contain at most one item.

This method is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected items from each.

Parameters None

Return Values Returns a List object containing zero or more strings. Each string in the list
corresponds to a selected item in the control. If no items are selected, the returned list
is empty.

See Also GetSelected method

RemoveSelected method
SelectedIndexes method

110 SelectedList
ClearBasic Control Reference
 Dropdown List Box control

method SetSelected

Syntax YourControl.SetSelected ItemToSelect

Applies To Dropdown List Box

Description The SetSelected method selects the specified item. If there was an existing
selection, this method clears it before selecting the new item.

Only one item at a time may be selected for a dropdown list box control. If you specify
an item that does not exist in the control’s list, this method exits without clearing the
previous selection.

Parameters This method accepts the following parameters:

Parameter Type Description

ItemToSelect String Specify the item text corresponding to the item you want to
select. This string is case-sensitive and must match the item
text in the control exactly.

Return Values None

See Also Contains method

GetSelected method
Selected property

SetSelected 111
ClearBasic Control Reference
 Dropdown List Box control

method UnSelect

Syntax YourControl.Unselect

Applies To Dropdown List Box

Description The UnSelect method clears the control’s current selection.

Parameters None

Return Values None

See Also SetSelected property

Selected property

112 UnSelect
ClearBasic Control Reference
 Dropdown List Box control

method Up

Syntax YourControl.Up

Applies To Dropdown List Box

Description The Up method moves the currently selected item up one position in the control’s list.
Any displaced items are moved down to make room for the item. If the selected item
is already at the beginning of the list, it remains there.

If no item is selected, this method does nothing.

Parameters None

Return Values None

See Also Down method

Up 113
ClearBasic Control Reference
 Dropdown List Box control

property DataChanged

Syntax RetBoolean = YourControl.DataChanged

YourControl.DataChanged = NewSetting

Applies To Dropdown List Box

Description The DataChanged property contains a boolean value indicating whether the user
modified the contents of this control. This value only indicates whether modifications
were made by the user; it does not reflect changes made to the control by your
ClearBasic code.

If you modify the control programmatically, you can set this property to reflect your
changes. Set this property to True to indicate you made modifications; otherwise, set it
to False to indicate the control is unchanged.

114 DataChanged
ClearBasic Control Reference
 Dropdown List Box control

property ListCount

Syntax ItemCount = YourControl.ListCount

Applies To Dropdown List Box

Description The ListCount property contains a Long integer indicating the total number of
items in the dropdown list box control.

This property is read-only.

See Also ListIndex property

ListCount 115
ClearBasic Control Reference
 Dropdown List Box control

property ListIndex

Syntax SelectedItem = YourControl.ListIndex

Applies To Dropdown List Box

Description The ListIndex property returns the index of the control’s currently selected item. A
dropdown list box control always has exactly one item selected. The selected item
appears in the text box portion of the control.

List indexes are 0-based, that is, the first item is at index 0, the second at index 1, and
so on. As a result, the maximum index is always one less than the total number of
items as stored in the ListCount property.

Example The following procedure illustrates the use of this property.

Sub MyClick_Click
Dim MyRetInt As Integer

MyRetInt = MyDDListBox.ListIndex

If MyRetInt = -1 Then
App.MsgBox "No Selection"
Else
‘Do this
...
End If
End Sub

See Also ListCount property

116 ListIndex
ClearBasic Control Reference
 Dropdown List Box control

property NewIndex

Syntax YourRetInt = YourControl.NewIndex

Applies To Dropdown List Box

Description The NewIndex property contains a long integer with the index of the most recently
added item. You can pass this index to other methods to modify (or subsequently
remove) the item.

When you add a new item, the AppendItem method updates this property to reflect
the position of any new items. Methods that remove items reset the value in this
property to -1.

This property is read-only.

See Also AppendItem method

Clear method
RemoveByItem method
RemoveItem method
RemoveSelected method
ReplaceItem method

NewIndex 117
ClearBasic Control Reference
 Dropdown List Box control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To Dropdown List Box

Description The Parent property contains the form object that owns the control. You can use this
property in to retrieve a reference to the form object containing the dropdown list box.

This property is read-only.

118 Parent
ClearBasic Control Reference
 Dropdown List Box control

property Selected

Syntax SelectedItem = YourControl.Selected

Applies To Dropdown List Box

Description The Selected property contains the item currently selected in the control. For
dropdown list boxes, the item is a string. Dropdown list boxes always have exactly
one item selected.

This property is read-only.

This property is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected item from each.

See Also GetSelected method

SelectedIndexes method
SelectedList method

Selected 119
ClearBasic Control Reference
 Dropdown List Box control

property Sorted

Syntax IsSorted = YourList.Sorted

Applies To Dropdown List Box

Description The Sorted property contains a boolean value indicating whether the items in the
control’s list are sorted. This property contains the value True if the items in the
control’s source contextual object are sorted, otherwise False.

This property is read-only.

See Also Sort method (ContextualObject object in the ClearBasic Object Reference)

120 Sorted
ClearBasic Control Reference
 Dropdown List Box control

property Tag

Syntax YourControl.Tag = "YourStringHere"

ControlTag = YourControl.Tag

Applies To Dropdown List Box

Description The Tag property contains a custom string that you assign at runtime. You can use
this string to identify the control internally to your application. You can also use this
property to store extra information about the control.

Tag 121
ClearBasic Control Reference
 Dropdown List Box control

property UserData

Syntax ControlData = YourControl.UserData

Applies To Dropdown List Box

Description The UserData property contains the string associated with the currently selected
item. At design time, you can associate a string with each item of a dropdown list.
This string may contain a database path or any other type of value that you designate.

Only dropdown list box controls that display a static list can include user data. You
can assign user data to any of the items in your list or omit the user data as
appropriate for each item.

This property is read-only. For information on associating user data with dropdown
list box items, see the User Interface Editor Guide.

122 UserData
ClearBasic Control Reference
 Dropdown List Box control

property Value

Syntax YourControl.Value = Setting

ControlValue = YourControl.Value

Applies To Dropdown List Box

Description The Value property contains a string with the item text for the currently selected
item. You can get this property to retrieve the item text for the selected item.

If you assign a value to this property, you must specify a string the name of the item
you want to select. This string is case-sensitive and must match the name of an item in
the list exactly. The string you specify is stored in the control’s destination contextual
object.

NOTE: It is possible to update the contents of the control’s destination contextual object
without changing the value in this property. Before getting this property, you can call the
Refresh method to ensure the control’s caches are up-to-date.

Value 123
ClearBasic Control Reference
 Dropdown List Box control

event Click

Syntax Sub YourControl_Click

Applies To Dropdown List Box

Description The Click event handler for your dropdown list box is called when the user presses
and releases the mouse button over the control. A Click event usually indicates the
selection of an item from the control’s list. However, this event does not distinguish
between the selection of a new item or of the same item.

You can use the Click event handler to perform other actions based on the selection
of an item.

124 Click
ClearBasic Control Reference
 Graph control

Description A graph control displays table data using a bitmap image. You can use graph controls
in your forms to help the user visualize large amounts of information, which may
point out useful trends in the data.

The graph control supports several different styles for displaying data, including bar
graphs, pie graphs, polar graphs, scatter graphs, and so on. The graph control also
supports both 2D and 3D variations of most graphs.

Data Sets and Data A graph control organizes data into data sets and data points. A data point
Points corresponds to a single value plotted on the graph. A data set represents a group of
related data points. The data points of a data set are organized along the columns or
rows of the data table. For example, Figure 1: shows some sales figures in a table. Each
cell containing a number represents a data point in the resulting graph. (The entries in
the first column and along the top row represent the labels associated with each
group. See Graph Labels and Legends.)

Figure 1: Graph data in table format

When you organize the table data along column boundaries, you get the data sets
shown on the left side of Figure 2:. Similarly, if you organize the table along row
boundaries, you get the data sets shown on the right side of Figure 2:.

Figure 2: Data Sets based on columns and rows

If you were to display graphs for both the column-based data sets and the row-based
data sets, you would get the graphs shown in Figure 3:

ClearBasic Control Reference

 Graph control

Figure 3: Graphs based on column and row data sets

Graph Labels and To make it easier for users to read the graph, the graph control labels graph elements.
Legends The location of labels depends on the type of graph being displayed by the control.
For example, labels for a vertical bar graph would be along the top or bottom of the
graph while labels for a horizontal bar graph would be along the left or right side.

Each group of related data points has an associated label. The label identifies a
common property shared by the data points. For example, in Figure 3:, the data points
in the left graph are grouped by month.

You can assign labels to a graph programmatically or using a contextual object. If your
graph uses a contextual objects to acquire the data points then it must acquire the
labels from a contextual object as well. If you are entering data points using ClearBasic
code, you can use the SetLabel method of the graph control to specify labels.

In addition to assigning labels to groups of data points, the graph control renders the
data points in each data set using a unique color or pattern. The special shading
attributes allow you to distinguish among the data points displayed with a particular
label.

Each data set is assigned a specific color to make it easier for users to quickly identify
elements in the data set. You can set the text for each data set’s legend entry using the
SetLegend method.

Figure 4: shows a table and its corresponding 2D bar graph. In this table, the two
columns of data correspond to the data sets of the graph. The labels and legend text
entries are highlighted in the table and can be seen in the corresponding graph.

Figure 4: Labels and legend text for a table and graph.

126
ClearBasic Control Reference
 Graph control

Specifying Data The graph control lets you specify the graph data in one of two ways. If you associate
Sets a contextual object with the graph control, the control always obtains the data from
that object. If you do not associate a contextual object with the control, you must
specify the data manually using the methods of the graph control.

If you use a contextual object with your graph control, the graph obtains all of the
graph data from that object. On the property sheet of the graph control, you specify
the rows or columns from which to obtain both the data sets and labels for the graph.
You cannot call the SetPoint, SetLabel, or SetLegend methods.

If you do not use a contextual object, you must call the SetPoint method from your
ClearBasic code to enter graph data. After you enter the graph data, you can assign
labels to each group of data points using the SetLabel method. You can also assign a
legend entry for each data set using the SetLegend method.

Aggregation In addition to graphing tabular data row by row and column by column, the graph
control has the ability to aggregate entries dynamically. One example of aggregation is
where you want to count the number of times a particular choice-list item appears.
The graph control can count the number of times each choice appears and display
those numbers as data points.

Another aggregation example supported by the graph control is the situation where a
set of data points share a common label. In this instance, the graph control can
perform a summation of the data points with the same label and present the result as
a single data point.

To enable aggregation, you must modify property sheet of the graph control using the
User Interface Editor. You cannot enable aggregation using ClearBasic code. When
enabled, the graph control automatically aggregates data provided by a contextual
object or by your code.

Referring to Graph You cannot create control objects directly using ClearBasic code. You must associate
Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the graph
control called YourGraphControl:
Dim YourControl As Control
Set YourControl = YourGraphControl

Source You can specify the graph data points and labels using contextual objects or
ClearBasic code. Graph controls support contextual objects with the following
primitive types:
■ Long
■ Single
■ Date
■ String

127
ClearBasic Control Reference
 Graph control

Methods This object supports the following methods:

■ ClearData method
■ GetLabel method
■ GetLegend method
■ GetPoint method
■ SetLabel method
■ SetLegend method
■ SetPoint method

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ BackColor property
■ BackStyle property
■ BorderStyle property
■ ControlType property [C]
■ Enabled property [C]
■ GraphType property
■ Height property [C]
■ Id property [C]
■ Left property [C]
■ LegendPos property
■ Name property [C]
■ NumSets property
■ ShowLegend property
■ Top property [C]
■ Visible property [C]
■ Width property [C]

128
ClearBasic Control Reference
 Graph control

method ClearData

Syntax YourControl.ClearData

Applies To Graph

Description The ClearData method removes all data points that were added using the
SetPoint method. Use this method to reset the graph data before adding a new set
of points.

If the graph uses a contextual object to acquire its data, this method does nothing.

Parameters None

Return Values None

Example The following example clears the current graph data before assigning any new data.
In this case, the Graph control displays data from some custom fields added to the
wipelm_case view.
Sub Form_Load()
Dim myrec as Record
Dim mybulk as New BulkRetrieve
Dim mylist as List
Dim i as Integer
Dim grp as Integer

' Clear out any existing data before adding

' any new data.
CBGraph.ClearData

grp = 0
mybulk.SimpleQuery 0, "wipelm_case"
mybulk.RetrieveRecords

Set mylist = mybulk.GetRecordList(0)

For i = 0 to mylist.Count -1
Set myrec = mylist.ItemByIndex(i)
CBGraph.SetPoint grp, i, _
myrec.GetField("case_x_data1")
CBGraph.SetPoint grp + 1, i, _
myrec.GetField("case_x_data2")
CBGraph.SetPoint grp + 2, i, _
myrec.GetField("case_x_data2")
CBGraph.SetLabel grp, i, _
myrec.GetField("case_x_sales")
Next i

CBGraph.SetLegend grp, "1901"

ClearData 129
ClearBasic Control Reference
 Graph control

CBGraph.SetLegend grp + 1, "1902"

CBGraph.SetLegend grp + 2, "1903"
CBGraph.Refresh
End Sub

See Also SetPoint method

130 ClearData
ClearBasic Control Reference
 Graph control

method GetLabel

Syntax LabelText = YourGraph.GetLabel (0, DataPointIndex)

Applies To Graph

Description The GetLabel method returns the label text associated with one data point. The
graph control displays this label text next to the graph element represented by that
data point.

NOTE: The graph control lets you associate a label with each data point in the graph, even if
the graph contains multiple data sets. You should always assign the same label to points whose
DataPointIndex parameter is the same.

Parameters This method uses the following parameters:

Parameter Type Description

DataPointIndex Long Specify the index of the point in the specified data set whose
label you want to retrieve. This value is a zero-based index,
that is, the first point is at index 0, the second at index 1, and
so on.

Return Values Returns a String containing the label text.

Example The following code fragment retrieves the label associated with the second group of
points.
Dim secondLabel as String

secondLabel = grphDataTrend.GetLabel(0,2)

See Also GetLegend method

SetLabel method

GetLabel 131
ClearBasic Control Reference
 Graph control

method GetLegend

Syntax LegendText = YourCustomList.GetLegend (DataSetIndex)

Applies To Graph

Description The GetLegend method returns the legend text associated with the specified data set.
The legend text serves as an identifier for the data in a particular data set.

You can use this method to retrieve the text for legend entries even if the legend is not
currently visible. Entries in the legend are color-coded to match the elements
displayed in the graph. The position of the legend is controlled by the LegendPos
property.

Parameters This method uses the following parameters:

Parameter Type Description

DataSetIndex Long Specify the index of the data set whose legend text you want
to retrieve. This index is zero-based, that is, the first data set
is at index 0, the second at index 1, and so on.

Return Values Returns a String containing the legend text.

Example The following code fragment retrieves the legend text associated with the third data
set in the graph.
Dim thirdLegend as String
thirdLegend = grphDataTrend.GetLegend(3)

See Also GetLabel method

SetLegend method
LegendPos property
ShowLegend property

132 GetLegend
ClearBasic Control Reference
 Graph control

method GetPoint

Syntax DataPoint = YourCustomList.GetPoint DataSetIndex, XValue

Applies To Graph

Description The GetPoint method returns the value of one point in the specified data set. When
you call this method, you must specify the location of the point in the data set. In turn,
this method returns the value stored at that point.

Parameters This method uses the following parameters:

Parameter Type Description

DataSetIndex Long Specify the index of the data set you are retrieving. This
index is zero-based, that is, the first data set is at index 0,
the second at index 1, and so on.
XValue Long Specify the index of the desired point in the data set. This
index is zero-based, that is, the first point is at index 0, the
second at index 1, and so on.

Return Values Returns the value at the specified location in the graph. The type of the returned value
can vary but must be one of the following types: Float, Double, Long, Integer.

Example The following code fragment returns the third point in the second data set.
Dim pointValue as Long
pointValue = grphDataTrend.GetPoint(2,3)

See Also SetPoint method

GetPoint 133
ClearBasic Control Reference
 Graph control

method SetLabel

Syntax YourCustomList.SetLabel 0, DataPointIndex, LabelText

Applies To Graph

Description The SetLabel method sets the label text for a related group of data points. Labels
identify the category to which the group of items belong. Individual items within the
group are further distinguished by the legend. See Graph Labels and Legends on
page 126 for more information.

The position of the label text is determined by the type of the graph. If the graph uses
a contextual object to acquire its data, this method does nothing.

Parameters This method uses the following parameters:

Parameter Type Description

DataPointIndex Long Specify the index of the group of points whose label you
want to set. This value is a zero-based index, that is, the
first point is at index 0, the second at index 1, and so on.
LabelText String Specify the label you want to associate with the specified
point.

Return Values None

Example The following code fragment generates a set of random data for a graph. The graph
contains four data sets. The labels of the graph are the even integers from 0 to 16,
inclusive.
Dim i as Integer
Dim j as Integer

For i = 0 to 3
For j = 0 to 16 Step 2
graphDataTrend.SetPoint i,j,Random(0,100)
graphDataTrend.SetLabel 0,j,CStr(j)
Next j
graphDataTrend.SetLegend i, "Group "+CStr(i)
Next i

See Also GetLabel method

SetLegend method

134 SetLabel
ClearBasic Control Reference
 Graph control

method SetLegend

Syntax YourCustomList.SetLegend DataSetIndex, LegendText

Applies To Graph

Description The SetLegend method sets the legend text associated with the specified data set.
The legend text serves as an identifier for the data in a particular data set.

You can use this method to assign the text for legend entries even if the legend is not
currently visible. Entries in the legend are color-coded to match the elements
displayed in the graph. The position of the legend is controlled by the LegendPos
property.

If the graph uses a contextual object to acquire its data, this method does nothing.

Parameters This method uses the following parameters:

Parameter Type Description

DataSetIndex Long Specify the index of the group whose legend you want to
modify. This index is zero-based, that is, the first group is at
index 0, the second at index 1, and so on.
LegendText String Specify the new legend text for the group. This text replaces
any previous text for the group.

Return Values None

Example The following code fragment generates a set of random data for a graph. The graph
contains four data sets. The legend entries for the graph consist of the strings "Group
0", "Group 1", "Group 2", and "Group 3".
Dim i as Integer
Dim j as Integer

For i = 0 to 3
For j = 0 to 16 Step 2
graphDataTrend.SetPoint i,j,Random(0,100)
graphDataTrend.SetLabel 0,j,CStr(j)
Next j
graphDataTrend.SetLegend i, "Group "+CStr(i)
Next i

See Also GetLegend method

SetLabel method
LegendPos property
ShowLegend property

SetLegend 135
ClearBasic Control Reference
 Graph control

method SetPoint

Syntax YourCustomList.SetPoint DataSetIndex, XValue, YValue

Applies To Graph

Description The SetPoint method adds a new data point to the graph. Use this method to add
points to a graph that does not acquire its data from a contextual object. If the graph
uses a contextual object to acquire its data, this method does nothing.

Using this method, you can specify the contents of the graph one point at a time. The
DataSetIndex and XValue parameters identify the place in which to insert the point.
The YValue parameter contains the value for the point.

Parameters This method uses the following parameters:

Parameter Type Description

DataSetIndex Long Specify the index of the data set you are retrieving. This
index is zero-based, that is, the first data set is at index 0,
the second at index 1, and so on.
XValue Long Specify the index of the desired point in the data set. Data
set items are labeled using contiguous zero-based
indexes, that is, the first point is at index 0, the second at
index 1, and so on.
YValue Integer Specify an empty variable of the desired type. On return,
Long this variable contains the value of the specified data point.
Float
Double

Return Values None

Example The following code fragment generates a set of random data for a graph. The graph
contains four data sets.
Dim i as Integer
Dim j as Integer

For i = 0 to 3
For j = 0 to 16 Step 2
graphDataTrend.SetPoint i,j,Random(0,100)
graphDataTrend.SetLabel 0,j,CStr(j)
Next j
graphDataTrend.SetLegend i, "Group "+CStr(i)
Next i

See Also GetPoint method

136 SetPoint
ClearBasic Control Reference
 Graph control

property BackColor

Syntax ColorLabel = YourControl.BackColor

YourControl.BackColor = ColorLabel

Applies To Graph

Description The BackColor property contains a string that identifies a color scheme entry. You
can get or set this value.

You can use this property only after using the CreateColorScheme/
SetColorScheme methods to specify the colors corresponding to the color labels.

The BackColor property allows you to set the background color of the graph control.
You can set this property directly for the control, or indirectly by setting the property
on the contextual object that is linked to the control.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The
label must be in the color scheme that is currently in effect for the form
in which you are performing color operations. (See
CreateColorScheme and SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the text box label and the textbox foreground text are assigned the
same color, red, and the background color for the text box is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Black", "Gray", _

"Blue", "Cyan", "Green"
LabelList1.AppendItem "Yellow", "Gold", _
"Wheat", "Orange", "Red"

ColorList1.AppendItem "Black", "Gray", _

"Blue", "Cyan", "Green"

BackColor 137
ClearBasic Control Reference
 Graph control

LabelList1.AppendItem "Yellow", "Gold", _

"Wheat", "Orange", "Red"

App.CreateColorScheme"Form2020", _
LabelList1, ColorList1
End Sub

Sub Form_Load
App.SetColorScheme "Form2020"
CBGraph.BackColor = "Yellow"
End Sub

See Also BackStyle property

CreateColorScheme method (App object in ClearBasic Object Reference)
SetColorScheme method (App object in ClearBasic Object Reference)

138 BackColor
ClearBasic Control Reference
 Graph control

property BackStyle

Syntax YourValue = YourControl.BackStyle

YourControl.BackStyle = newValue

Applies To Graph

Description The BackStyle property contains a long integer that indicates the background fill
style used to display graph elements, where each graph element corresponds to a data
point plotted on the graph. The value stored in this property corresponds to one of the
following constants:

Constant Description
cbGraphNoFill Graph elements are not filled.
cbGraphFill Graph elements are filled.

See Also BackColor property

BackStyle 139
ClearBasic Control Reference
 Graph control

property BorderStyle

Syntax YourValue = YourControl.BorderStyle

YourControl.BorderStyle = newValue

Applies To Graph

Description The BorderStyle property contains a long integer indicating the type of border
drawn around the control. The value stored in this property corresponds to one of the
following constants:

Constant Description
cbGraphNoBorder None
cbGraphThinRaisedBorder Thin Raised Border
cbGraphThinSunkenBorder Thin Sunken Border
cbGraphThin3DBorder Thin 3D Border
cbGraphThickRaisedBorder Thick Raised Border
cbGraphThickSunkenBorder Thick Sunken Border
cbGraphThick3DBorder Thick 3D Border
cbGraphLineBorder Simple Line Border

If the graph uses a contextual object to acquire its data, this property is read-only.

See Also BackStyle property

GraphType property

140 BorderStyle
ClearBasic Control Reference
 Graph control

property GraphType

Syntax YourValue = YourControl.GraphType

YourControl.GraphType = newValue

Applies To Graph

Description The GraphType property contains a long integer indicating the type of graph drawn
by the control. The value stored in this property corresponds to one of the following
constants:

Constant Description
cbGraphLine Line plot
cbGraphHBar Horizontal bar chart
cbGraphVBar Vertical bar chart
cbGraphPie Pie chart
cbGraphArea Area under curve
cbGraphStock High-Low-Quotes
cbGraphISOBar 3D Bar chart "Manhattan"
cbGraphISOArea 3D Bar chart "Rooftop"
cbGraphStackVBar 2D Stacked vertical bar
cbGraphStackHBar 2D Stacked horizontal bar
cbGraphISOPie 3D pie chart
cbGraphStrata Strata graph
cbGraphExVBar 3D Vertical bar
cbGraphExHBar 3D Horizontal bar
cbGraphBubbleRadius Bubble radius
cbGraphBubbleArea Bubble area
cbGraphVectorTail Vector - anchor at tail
cbGraphVectorCenter Vector - anchor at center
cbGraphVectorPointAndOffset Vector with point & offset
cbGraphXYScatterAlt Scatter graph(alternate)
cbGraphXYScatterIndex Scatter graph(indeces)
cbGraphXYScatterGroup Scatter graph(groups)
cbGraphAreaWeb Area Web chart
cbGraphAreaStock Area Stock (hi-lo-now)
cbGraphPolar Polar chart
cbGraphAreaPolar Polar chart (area fill)
cbGraphCandle Candle chart
cbGraphHiLoOpenClose Hi-Lo-Open-Close
cbGraphGantt Gantt
cbGraphLineOnly Line only (no widgets)

GraphType 141
ClearBasic Control Reference
 Graph control

Constant Description
cbGraphRibbon 3D Ribbon chart
cbGraphWeb Web chart
cbGraphXYScatterAltEx Scatter graph with log/lin axis (alternate)
cbGraphXYScatterIndexEx Scatter graph with log/lin axis (indices)
cbGraphXYScatterGroupEx Scatter graph with log/lin axis (group)
cbGraphStep Step chart
cbGraphStepLo Step chart (line only)
cbGraphStrataVBar Strata vertical bar (one index/per bar)
cbGraphStrataHBar Strata horizontal bar (one index/per bar)
cbGraphStrataVBarGroup Strata vertical bar (one group/per bar)
cbGraphStrataHBarGroup Strata horizontal bar (one group/per bar)

If the graph uses a contextual object to acquire its data, this property is read-only.

See Also BackStyle property

BorderStyle property

142 GraphType
ClearBasic Control Reference
 Graph control

property LegendPos

Syntax YourValue = YourControl.LegendPos

YourControl.LegendPos = newValue

Applies To Graph

Description The LegendPos property contains a long integer indicating the position of the
graph’s legend text. You can set this property to one of the following values:

Value Position of legend

cbGraphLegendLeft Left side of graph
cbGraphLegendRight Right side of graph
cbGraphLegendTop Top of graph
cbGraphLegendBottom Bottom of graph

If the graph uses a contextual object to acquire its data, this property is read-only.

See Also GetLegend method

SetLegend method
ShowLegend property

LegendPos 143
ClearBasic Control Reference
 Graph control

property NumSets

Syntax YourValue = YourControl.NumSets

Applies To Graph

Description The NumSets property contains a long integer indicating the number of data sets in
the graph. Each data set consists of one or more data points, which you add using the
SetPoint method.

This property is read-only and cannot be set.

See Also GetPoint method

SetPoint method

144 NumSets
ClearBasic Control Reference
 Graph control

property ShowLegend

Syntax YourValue = YourControl.ShowLegend

YourControl.ShowLegend = newValue

Applies To Graph

Description The ShowLegend property contains a Boolean value that indicates whether or not the
graph’s legend is displayed. You can get the value of this property to determine if the
legend is currently visible or set the value to hide or show the legend.

See Also GetLegend method

SetLegend method
LegendPos property

ShowLegend 145
ClearBasic Control Reference
 Graph control

146 ShowLegend
ClearBasic Control Reference
 Grid control

Description A grid control displays information in a series of columns and rows. You can use this
control to display records from a database table, database view, or dynamic view—
user-defined type (UDT). Each row of the grid corresponds to a single record of the
specified type. Each column corresponds to a field of the table or view. A cell
represents the intersection of a row and column and contains the data for a specific
field of a record.

You create grid controls using the User Interface Editor. When you create the control,
you associate it with a contextual object that designates the table or view you want to
display in the grid. You must create one or more columns to display the fields of the
table or view. You must also decide whether the user may edit the contents of the grid
by setting the control’s Is Editable property.

NOTE: Grid controls are sometimes referred to as Custom List controls. The name Custom
List is maintained in some situations for backwards compatibility. However, the term Grid is
preferred.

Static Grid Controls By default, new grid controls are static, that is, their contents cannot be edited by the
user. You can use static controls in situations where you only want to display the data
or when you want to force the user to open a child dialog to edit the contents of a row.
In both cases, the user cannot edit the contents of the grid directly.

Although the user may not edit the contents of the grid using the grid interface, you
can modify the contents programmatically using ClearBasic code. You can add new
rows using the AppendItem method and remove individual rows using the
RemoveByItem, RemoveItem, and RemoveSelected methods. To remove all rows
from a control, use the Clear method.

Selections in a static grid control affect entire rows, as opposed to individual cells of
the row. When the user clicks in a cell, the control highlights the entire row. Some
methods of the grid control operate only on the currently selected row. For example,
the Down and Up methods adjust the position of one or more rows. You can get the
current selection using the GetSelected, SelectedIndexes, and SelectedList
methods or using the Selected and ListIndex properties. You can also change the
selection using the SetSelected and UnSelect methods.

You can use the properties of the grid control to gather information about its current
settings. You can retrieve the name of the control, its location, and other information
that describes the control’s current state.

Static grid controls generate two types of events for handling user clicks in the control.
Your Click and DblClick event handlers can process these events and perform any
relevant tasks.

ClearBasic Control Reference

 Grid control

Editable Grid When you create a new grid control, you can make it editable by setting its Is Editable
Controls property to True in the User Interface Editor. An editable grid control supports all of
the same functionality for manipulating the grid as does the static version of the
control. In addition, the editable control allows the user to modify the displayed data
directly in the grid. To edit the contents of a particular cell, the user simply clicks in a
cell to activate the cell. Once activated, the user can enter data using the cell’s edit
control.

Most of the methods relating specifically to editable grids help you set cell values and
validate rows and cells. Use the GetChoiceList, GetChoiceListDefault, and
SetCellText methods to get and set cell values. Use the GetChangedCell and
GetChangedRow methods to retrieve user edits for validation. Use the
AbortCellChange and AbortRowChange method to prevent the user from saving
those changes to the database.

With an editable grid control, you can call methods to prevent the user from editing
specific cells. The SetCellReadOnly method marks individual cells as read-only.
The SetRowReadOnly and SetEditStates methods mark groups of cells as read-
only.

Editable grids generate several additional events for you to handle. The
CellChanged event notifies you when the user has modified the contents of a cell.
The RowChanged event notifies you when the user has finished making changes to a
row so that you can save those changes to the database. When the user adds another
row to the grid, the grid control calls your NewRow event handler to create the row
and set the initial cell values. Other events support Select CBX-related features such as
searching and sorting.

Multiple Contextual The grid control supports the ability to change the current source and destination
Object Support contextual objects at runtime. Changing these objects allows one grid control to
display records from different database tables. Support for multiple contextual objects
requires the use of extended contextual object information. A grid that supports the
switching of contextual objects is called a multigrid control.

At runtime, you can change the contextual object of the grid by changing the value in
the CObj property of the grid. This property contains the name of the grid’s current
source contextual object. When you change the value, the grid reconfigures itself
using information in the new contextual object. Only one source contextual object can
be associated with the grid at any given time.

See the User Interface Editor Guide for information on how to configure and use a grid
control with multiple contextual objects.

Select CBX and The Select CBX control uses a grid control to display records retrieved by a query.
Grids When you relate a Select CBX to a grid, the Select CBX takes over many aspects of the
grid operation. In particular, the Select CBX coordinates the storage of the records in
the grid and the updates needed to display those records.

IMPORTANT: The Select CBX control defines several methods for retrieving grid information.
If you need to retrieve or set some grid data, call the Select CBX method instead of the
corresponding grid or contextual object method whenever possible. Calling the Select CBX
method ensures that any Select CBX state information is updated appropriately.

148
ClearBasic Control Reference
 Grid control

Paging If you associate a grid with a Select CBX control, the Select CBX control may use
paging to improve performance when handling large result sets. If the size of the
result set exceeds a preset amount, the Select CBX loads only a portion of the result set
into memory at any given time. The Select CBX keeps two pages worth of records in
memory at any given time. As the user scrolls through the list, the Select CBX loads
new pages into memory and updates the grid display.

Because the grid has no knowledge of which pages are in memory, you cannot make
any assumptions about the position of a record in the overall result set. When using
the Select CBX or grid interfaces, do not attempt to manipulate more than one record
at a time. If a paging event has occurred, one of the records may no longer be in
memory.

Before loading a new page, the grid sends appropriate CellChanged and
RowChanged events to allow you to save the contents of the current row. If the
current row has not changed, only the paging event is sent.

IMPORTANT: For CeFO default grid controls, you can specify the page size in the application
.env file.

Context-Sensitive This control supports the display of a context-sensitive menu. The control
Menu Support automatically provides several control-related menu items to allow the user to modify
the grid. You may add additional menu items using the methods of this control.

If you add context-sensitive menu items to a control, you must provide an event
handler to respond to the selection of your menu items. The ContextMenu_Select
event handler lets you handle the selection of all your context-sensitive menu items.
You may also implement a ContextMenuDisplaying event handler to modify the
state of your menu items immediately before the menu is displayed.

Grid Event The grid control supports several events for handling user interactions with the grid
Execution Order and its contents. In a few cases, a single action may trigger several events. In these
cases, the events are sent in a specific order. Table lists the actions and the
corresponding grid events.

Action Events Notes

Click on a new row Cell_Click event Occurs for the new cell that was
selected.
Click event Occurs for the row that was selected.
Click on a different cell in the Cell_Click event Occurs for the new cell that was
same row selected.
Click on a new row after CellChanged event Occurs for the cell that was edited.
editing the previous row RowChanged event Occurs for the row that was edited.
Cell_Click event Occurs for the new cell that was
selected.
Click event Occurs for the row that was selected.

149
ClearBasic Control Reference
 Grid control

Referring to Grid You cannot create control objects directly using ClearBasic code. You must associate
Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the grid
control called YourGridControl:
Dim YourControl As Control
Set YourControl = YourGridControl

Source At control design time, you must link a separate source field from one contextual
object to each column in the grid. The type of the contextual object must be a database
type or a UDT. It holds a list of records/UDTs at runtime.

Destination At run time, when the user selects one or more rows from the grid, the index or
indexes (and not the contents of the selected rows!) of the selected item(s) is stored in
the destination contextual object, which is of type List.

Control Label This control does not contain a label. You must create a label control and place it next
to this control.

150
ClearBasic Control Reference
 Grid control

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object. Methods marked with an [E] apply only to
editable grid controls.
■ AbortCellChange method [E]
■ AbortRowChange method [E]
■ AppendContextMenu method
■ AppendItem method
■ Clear method
■ ClearContextMenu method
■ ColorCells method
■ Contains method
■ Down method
■ GetChangedCell method [E]
■ GetChangedRow method [E]
■ GetChoiceList method [E]
■ GetChoiceListDefault method [E]
■ GetChoiceListUserData method [E]
■ GetColumnControlType method [E]
■ GetColumnMaxLength method [E]
■ GetColumnNames method [E]
■ GetList method
■ GetSelected method
■ GetSelectedColumns method
■ HideColumn method
■ IsColumnEditable method [E]
■ IsColumnRequired method [E]
■ Refresh method [C]
■ RemoveByItem method
■ RemoveItem method
■ RemoveSelected method
■ ReplaceItem method
■ SaveAnyChanges method [E]
■ SelectedIndexes method
■ SelectedList method
■ SetCellColoring method
■ SetCellFocus method [E]
■ SetCellReadOnly method[E]

151
ClearBasic Control Reference
 Grid control

■ SetCellText method [E]

■ SetContextMenuEnabled method
■ SetContextMenuVisible method
■ SetEditStates method [E]
■ SetFocus method [C]
■ SetNewRowIndicator method [E]
■ SetRowReadOnly method [E]
■ SetSelected method
■ UndoRowChanges method [E]
■ UnSelect method
■ Up method

152
ClearBasic Control Reference
 Grid control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object. Properties marked with [E] apply only to
editable grid controls.
■ AppendRows property [E]
■ CObj property
■ ControlType property [C]
■ DataChanged property
■ Dirty property [E]
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ ListCount property
■ ListIndex property
■ MultiSelect property
■ Name property [C]
■ NewIndex property
■ PagingEvent property
■ Parent property
■ PromptOnSave property [E]
■ SelCount property
■ Selected property
■ Sorted property
■ Tag property
■ Top property [C]
■ TopIndex property
■ TotalRows property
■ Visible property [C]
■ Width property [C]

153
ClearBasic Control Reference
 Grid control

Events This object supports the following events. Events marked with a [C] are documented
with the Control object. Events marked with an [E] are sent only to editable grid
controls.
■ AdhocCellChanged event [E]
■ Cell_Btn_Click event [E]
■ CellChanged event [E]
■ Cell_Click event
■ Cell_List_Select event [E]
■ Click event
■ ContextMenuDisplaying event
■ ContextMenu_Select event
■ DblClick event
■ DoAdhocQuery event
■ GotFocus event [C]
■ LostFocus event [C]
■ NewRow event [E]
■ Refresh event
■ RowChanged event [E]
■ SortColumn event

Deprecated Events The names of the following events have changed. The old event names are still
supported for compatibility but their use is discouraged. Use the new event names
instead.

Old Event New Event

DropDown_Click event Cell_List_Select event
DropDown_Displaying event Cell_Btn_Click event
GoTo_Click event Cell_Btn_Click event
LookUp_Click event Cell_Btn_Click event
<MenuItem> event ContextMenu_Select event

154
ClearBasic Control Reference
 Grid control

method AbortCellChange

Syntax YourGrid.AbortCellChange DialogType, Message

Applies To Grid (editable only)

Description The AbortCellChange method lets you abort the changes to a cell before they are
committed to the grid’s source contextual object. When you call this method, you may
use the DialogType and Message parameters to notify the user about the aborted
attempt to modify the cell. You may also use these parameters to let the user override
the abort operation and save the cell contents regardless.

Call this method from a CellChanged event handler when the contents of a cell are
invalid. This method prevents the cell focus from changing to another cell. The user
may not select a different cell until the edited cell contains a valid value or until you
give the user the option of saving the invalid changes.

The value you specify for the DialogType parameter determines what kind of
notification (if any) the user receives. If you specify the value
cbAbortDisplayYesNo for this parameter, the user has the option of accepting the
cell changes even though they are invalid. If you specify any other value, the changes
are automatically aborted.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

DialogType Long Specify the type of notification to give to the user. You must
specify one of the following constants.

Constant Description
cbAbortUndo Do not notify the user
cbAbortDisplayOK Notify the user that the changes
are being aborted
cbAbortDisplayYesNo Ask the user whether or not to
abort the changes
Message String Specify the prompt message to display to the user. If the
DialogType is cbAbortUndo, specify an empty string.

Return Values None

AbortCellChange 155
ClearBasic Control Reference
 Grid control

Example The following example shows the CellChanged event handler for the grid whose
name is GridCtl. This event handler validates only the quantity field of the grid. If
the user specifies a negative quantity, the event handler calls AbortCellChange to
notify the user that a positive integer must be entered.
Sub GridCtl_CellChanged
dim rowNum as Integer
dim fieldName as String
dim fieldData as String
dim numItems as Integer

' Get the info for the cell that changed.

GridCtl.GetChangedCell rowNum, fieldName, fieldData

' Validate the cell’s contents.

If fieldName = "quantity" Then
If IsNumeric(fieldData) And fieldData < 0 Then
AbortCellChange cbAbortDisplayOK, _
"Enter a positive integer value."
End If
End If
End Sub

See Also AbortRowChange method

GetChangedCell method
AdhocCellChanged event
CellChanged event
RejectAdhocCellEntry method (Select CBX control)

156 AbortCellChange
ClearBasic Control Reference
 Grid control

method AbortRowChange

Syntax YourGrid.AbortRowChange DialogType, Message, FieldName

Applies To Grid (editable only)

Description The AbortRowChange method lets you abort any changes to a row before
committing those changes to the database. Call this method from a RowChanged
event handler when your code determines that the contents of a row are invalid. This
method prevents the focus from changing to another row. The edited row remains
selected until the user corrects the errors, discards the changes, or overrides the abort
operation.

When you call this method, you may use the DialogType and Message parameters to
notify the user about the aborted attempt to save the row changes. You may also use
these parameters to let the user override the abort operation and save the row changes
regardless.

The value you specify for the DialogType parameter determines what kind of
notification (if any) the user receives. If you specify the value
cbAbortDisplayYesNo for this parameter, the user has the option of overriding the
abort operation and accepting the row changes even though they are invalid. If you
specify any other value, the row changes are automatically aborted.

Although the entire row remains selected when you abort a set of changes, you may
assign the cell focus to a particular cell of that row using this method. If you specify a
value in the FieldName parameter, the grid highlights the cell corresponding to that
field and assigns it the cell focus.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

DialogType Long Specify the type of notification to give to the user. You must specify
one of the following constants:
Constant Description
cbAbortUndo Do not notify the user
cbAbortDisplayOK Notify the user that the changes
are being aborted.
cbAbortDisplayYesNo Ask the user whether or not to
abort the changes.
Message String Specify the prompt message to display to the user. If the
DialogType is cbAbortUndo, specify an empty string (““).
FieldName String Specify the name of the field you want to receive the focus if the
changes are aborted.

AbortRowChange 157
ClearBasic Control Reference
 Grid control

Return Values None

See Also AbortCellChange method

UndoRowChanges method
RowChanged event

158 AbortRowChange
ClearBasic Control Reference
 Grid control

method AppendContextMenu

Syntax YourGrid.AppendContextMenu ItemName, ItemLabel, AppMenuName,

Separator

Applies To Grid

Description The AppendContextMenu method adds a new menu item to the end of the grid
control’s context-sensitive menu. You can use this method to supplement the menu
items specified using the User Interface Editor.

In addition to adding menu items, you can use this method to add a separator after an
existing menu item. To add a separator, specify True for the Separator parameter.

The menu items you add using this method are enabled and visible initially. To
change the appearance of an item, call the SetContextMenuEnabled or
SetContextMenuVisible method. You can also add code to a
ContextMenuDisplaying event handler to update the appearance of menu items
dynamically.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify an identification string for the menu item. Your
application uses this string to identify the menu item when
calling menu-related methods. This name does not have to be
the same as the menu item’s label.
ItemLabel String Specify the menu-item label. This is the string the user sees in
the menu.
AppMenuName String Specify the menu name associated with the context-sensitive
menu, if any.
Specify a value for this parameter only if the menu item is
already associated with one of the application menus.
Specifying the application menu name avoids the creation of
duplicate menu items.
If the menu item is unique, specify an empty string ("") for
this parameter.
Separator Boolean Specify True if the item should be a separator, otherwise False.
If you specify True for this parameter, the ItemLabel and
AppMenuName parameters are ignored.

Return Values None

AppendContextMenu 159
ClearBasic Control Reference
 Grid control

Example The following example adds two new items to the context-sensitive menu associated
with a grid control. The new items allow the user to select all of the rows in the grid
and to deselect whatever is currently selected.
Sub Form_Load
' Add two new menu items for selecting
' everything and nothing.
GridCtl.AppendContextMenu "cntxSelectAll", _
"Select All", "", FALSE
GridCtl.AppendContextMenu _
"cntxSelectNone", "Select None", "", _
FALSE

End Sub

See Also SetContextMenuEnabled method

SetContextMenuVisible method
ContextMenuDisplaying event

160 AppendContextMenu
ClearBasic Control Reference
 Grid control

method AppendItem

Syntax YourGrid.AppendItem ItemToAppend

Applies To Grid

Description The AppendItem method appends one row or a list of rows to the grid. The data type
of each row must match the data type currently associated with the grid. For
multigrids, you can check the current contextual object assigned to the grid to
determine the row type. This method automatically updates the source contextual
object linked to the grid.

When you add a new row to a grid, the grid sets the row’s Dirty property to False.
When the user modifies the value in a cell (or you modify the contents of a cell
programmatically), the grid updates the Dirty property.

Before calling this method, you must make sure there is a contextual object linked to
the grid and that the contextual object has already been initialized with the Fill
method. The subtype of the source contextual object must be set to Record List.

NOTE: If the grid is associated with a Select CBX control, use the AppendItem method of
the Select CBX control instead.

Parameters This method accepts the following parameters:

Parameters Type Values

ItemToAppend Variable Specify the item or list of items you want to add. The data
type of added items must match the data type of the grid’s
source contextual object.

Return Values None

See Also CObj property

Dirty property
AppendItem method (Select CBX control)
InsertItem method (Select CBX control)
Fill method (ContextualObject object in the ClearBasic Object Reference)

AppendItem 161
ClearBasic Control Reference
 Grid control

method Clear

Syntax YourGrid.Clear

Applies To Grid

Description The Clear method removes all items from the grid. This method sets the value of the
NewIndex property to -1.

Parameters None

Return Values None

See Also RemoveByItem method

RemoveItem method
ReplaceItem method

162 Clear
ClearBasic Control Reference
 Grid control

method ClearContextMenu

Syntax YourGrid.ClearContextMenu

Applies To Grid

Description The ClearContextMenu method removes custom menu items from the control’s
context-sensitive menu. This method removes only menu items that were added
using the AppendContextMenu method of the control. This method does not remove
menu items put on the menu by ClarifyCRM eFrontOffice or added in the User
Interface Editor.

Parameters None

Return Values None

See Also AppendContextMenu method

ClearContextMenu 163
ClearBasic Control Reference
 Grid control

method ColorCells

Syntax YourGrid.ColorCells Foregrounds, Backgrounds, Rows, Columns

Applies To Grid

Description The ColorCells method sets the foreground and background color for the grid cells.
The colors you specify must belong to the current color scheme.

You can use this method in conjunction with the SetCellColoring method to
specify a color procedure for the grid. A color procedure is a subroutine you define in
your form’s module for coloring the cells of the grid. Whenever rows are added to the
grid, either programmatically or by the user, the grid calls your color procedure to
adjust the cell colors. You use this method to apply the colors to the cells.

Before calling this method from a color procedure, you must set up the parameters to
specify which colors you want to apply to each cell. For any given index, the
parameters specify the colors to apply and the cell position at which to apply them.
For example, the following table shows a sample set of lists. In the example, the colors
red and white are applied to the first column of each row and the colors green and
white are applied to the fourth column of the first row.

List Index Foregrounds Backgrounds Rows Columns

0 “red” “white” 0 0
1 “green” “white” 0 3
2 “red” “white” 1 0
3 “red” “white” 2 0

The number of items in the Foregrounds and Backgrounds lists must be equal to the
number of cells specified by the Rows and Columns parameters. If you do not want to
apply a color to a particular cell, specify an empty string in place of a color name in
either the Foregrounds or Backgrounds parameter.

NOTE: The index for each column in a grid is determined at control design time in the User
Interface Editor. Therefore, if the end user reorders columns in the grid, the indexes are not
affected.

Parameters This method accepts the following parameters:

164 ColorCells
ClearBasic Control Reference
 Grid control

Parameter Type Description

Foregrounds List Specify the list of color values to apply to the foreground of the
cells. If you do not want to apply a foreground color to a cell, you
must specify an empty string (““) instead.
The colors you specify for this parameter must correspond to
colors in the current color scheme.
Backgrounds List Specify the list of color values to apply to the background of the
cells. If you do not want to apply a background color to a cell,
you must specify an empty string (““) instead.
The colors you specify for this parameter must correspond to
colors in the current color scheme.
Rows List Specify a list of integer values. Each value represents the row
index of a cell to be colored. The value in the same position of the
Columns parameter specifies the column of the cell. (The first
row in the grid has an index of 0.)
This parameter is optional. If you do not specify this parameter,
the ColorCells method iterates over the rows, applying the
specified colors to the entire row. This behavior overrides the
setting supplied to the WholeRow parameter of the
SetCellColoring method.
Columns List Specify a list of integer values. Each value represents the column
index of a cell to be colored. The value in the same position of the
Rows parameter specifies the row of the cell. (The first column in
the grid has an index of 0.)
This parameter is optional. If you do not supply this parameter
but you do specify the Rows parameter, the colors are applied to
the first column of the specified row.

CAUTION: You must specify a color or "" in both the Foregrounds and Backgrounds
parameters for each cell you specify using the Rows and Columns parameters. Failure to do so
will result in unexpected behavior.

Return Values None.

Example The following example shows a sample color procedure that applies a color to the
column containing the “priority” field.

The first part of the example sets up the initial color scheme. In a global module, the
Initialize_App routine defines the color scheme and associates different colors
with the values that can exist in the “priority” field. In the global module, define the
following code:
Sub Initialize_App
Dim ColorVals As New List
Dim ColorNames As New List

ColorVals.appendItem "red", "purple","green",

"black","cyan"

ColorNames.AppendItem "Immediate", _

ColorCells 165
ClearBasic Control Reference
 Grid control

"Urgent", "Casual", "Other","Medium"

App.CreateColorScheme "MyColorScheme", _
ColorNames, ColorVals
End Sub

In the form module, the Form_Load routine sets the current color scheme and
associates a color procedure with the grid. The color procedure iterates through the
rows of the grid and assigns an appropriate color to the “priority” field of each row, as
shown in the following code:
'In the form module
Sub Form_Load
App.SetColorScheme "MyColorScheme"
MyGrid.SetCellColoring "MyColorProc"
Me.DoDefault
End Sub

' Define the color procedure

Sub MyColorProc
Dim SourceList As List
Dim CaseRec As Record
Dim Foregrounds As New List
Dim Backgrounds As New List
Dim Row As integer

Dim RowList As New List

Dim ColList As New List

Foregrounds.ItemType="String"
Backgrounds.ItemType="String"
RowList.ItemType="Integer"
ColList.ItemType="Integer"

Set SourceList = MyGrid.GetList

For Row = 0 to SourceList.Count -1

Set CaseRec = SourceList.ItemByIndex(Row)
Foregrounds.AppendItem CaseRec.GetField("priority")

Backgrounds.AppendItem "" ' Use the default color

RowList.AppendItem Row
ColList.AppendItem 2 ' Third column is “priority”
Next Row

MyGrid.ColorCells Foregrounds, Backgrounds,

RowList, ColList
End Sub

See Also SetCellColoring method

CreateColorScheme method (App object in the ClearBasic Object Reference)
SetColorScheme method (App object in the ClearBasic Object Reference)

166 ColorCells
ClearBasic Control Reference
 Grid control

method Contains

Syntax YourBoolean = YourGrid.Contains (ItemToFind)

Applies To Grid

Description The Contains method returns a boolean value indicating whether the specified
record exists in the grid. The type of the record you specify in the ItemToFind
parameter must match the type of items displayed in the grid. This method compares
every field of the specified record with the fields of the records in the grid.

IMPORTANT: This method performs a comparison of all of the fields in the specified records,
including those not displayed in the grid. If you want to perform field-level comparisons, use
the FindFirstIndex method.

This method supports user defined types.

Parameters This method takes the following parameter:

Parameter Type Description

ItemToFind Record Specify a record whose type matches the type of records
displayed by the grid. For multigrids, check the type of the
current contextual object before specifying this parameter.

Return Values Returns True if the item is in the grid, otherwise False.

See Also FindFirstIndex method (List object in the ClearBasic Object Reference

Contains 167
ClearBasic Control Reference
 Grid control

method Down

Syntax YourGrid.Down

Applies To Grid

Description The Down method moves the currently selected item or items down one position in
the grid.

This method moves the selected items in the grid down one place. Each selected item
moves down to appear one line lower than previously displayed. The displaced items
move up accordingly. If multiple items are selected, some displaced items may move
up to make room for the items that move down.

If a selected item is at the end of the list, it remains there. If multiple items are selected
so that all the items between an item and the end of the list are selected, then that item
will remain in its previous position.

Parameters None

Return Value None

See Also Up method

168 Down
ClearBasic Control Reference
 Grid control

method GetChangedCell

Syntax YourBoolean = YourGrid.GetChangedCell (Row, FieldName, Data)

Applies To Grid (editable only)

Description The GetChangedCell method returns information about the most recently changed
cell. Call this method only from a CellChanged event handler.

This method returns the row index and field name of the cell that changed and returns
the new value of the cell. You can use this information to validate the contents of the
cell.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

Row Long You must provide a long integer variable for this parameter.
On return, this variable contains the index of the row
containing the changed cell. The row index is zero-based, that
is, the first row is at index 0, the second at index 1, and so on.
FieldName String You must provide a string variable for this parameter. On
return, the variable contains the field name of the changed cell.
Data String You must provide a string variable for this parameter. On
return, this variable contains the new cell value.

Return Values Returns True if the data was acquired successfully, otherwise False.

Example The following example shows a sample CellChanged event handler. Before
validating any data, this method calls the GetChangedCell method to determine
which cell changed and to determine the new value in the cell.
Sub GridCtl_CellChanged
dim rowNum as Integer
dim fieldName as String
dim fieldData as String
dim numItems as Integer

' Get the info for the cell that changed.

GetChangedCell rowNum, fieldName, fieldData

' Validate the cell’s contents.

If fieldName = "quantity" Then
If IsNumeric(fieldData) And fieldData < 0 Then
AbortCellChange cbAbortDisplayOK, _

GetChangedCell 169
ClearBasic Control Reference
 Grid control

"Enter a positive integer value."

End If
End If
End Sub

See Also AbortCellChange method

GetChangedRow method
CellChanged event

170 GetChangedCell
ClearBasic Control Reference
 Grid control

method GetChangedRow

Syntax YourBoolean = YourGrid.GetChangedRow (Row, FieldNameList,

DataList)

Applies To Grid (editable only)

Description The GetChangedRow method returns information about the most recently changed
row. Call this method only from a RowChanged event handler.

This method returns the row and field names of the cells that changed. (All of the cells
belong to the same row.) This method also returns the data for each of the changed
cells.

The items in the FieldNameList and DataList parameters are ordered in parallel. That
is, for each field name in the FieldNameList parameter, the corresponding cell data is
at the same index in the DataList parameter. For example, the data at index 0 in the
DataList parameter belongs to the cell whose field name is at index 0 in the
FieldNameList parameter.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

Row Long You must provide a long integer variable for this parameter. On
return, this variable contains the index of the row containing the
changed cells. The row index is zero-based, that is, the first row
is at index 0, the second at index 1, and so on.
FieldNameList List You must provide a list variable for storing items of type "string".
On return, the variable contains one or more String objects, each
of which contains the name of a field. Each field name identifies
a cell in the specified row that changed.
DataList List You must provide a list variable for storing items of type "string".
On return, the variable contains one or more String objects, each
of which contains the new data for one changed cell.

Return Values Returns True if the data was acquired successfully, otherwise False.

Example The following example gets the changed record and saves it to the database using a
BulkSave object.
Sub GridCtl_RowChanged
dim blkSave as New BulkSave
dim recordList as List
dim changedRec as Record
dim rowIndex as Integer
dim fields as List

GetChangedRow 171
ClearBasic Control Reference
 Grid control

dim values as List

GridCtl.GetChangedRow rowIndex, fields, values

set recordList = Cobj_GridCtl.Contents

set changedRec = Cobj_GridCtl.GetRecordByIndex rowIndex

blkSave.UpdateRecord changedRec
blkSave.Save
End Sub

See Also GetChangedCell method

RowChanged event

172 GetChangedRow
ClearBasic Control Reference
 Grid control

method GetChoiceList

Syntax ChoiceList = YourGrid.GetChoiceList (FieldName)

Applies To Grid (editable only)

Description The GetChoiceList method returns a list of strings corresponding to the items in
the specified column’s choice list. You may call this method for columns that use a
drop-down list box or drop-down combo box. If a column uses a drop-down combo
box, the returned list includes any items that the user added to the list.

This method returns only the name of the choice list item; it does not return the user
data associated with the item. To get the user data for a selected item, call the
GetChoiceListUserData method.

You assign a choice list to a column using the User Interface Editor. The choice list
may be of any type: static, popup, or Clarify. You cannot change the type of list
associated with the grid control at runtime using ClearBasic code.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

FieldName String Specify the name of the field corresponding to the desired
column.

Return Values Returns a list of String objects. If the field does not have a choice list, this method
returns the null list Nothing.

Each string in the list contains the name of one entry in the choice list. The order of the
returned entries matches the order of the items as they are displayed in the control.

See Also GetChoiceListDefault method

GetChoiceListUserData method

GetChoiceList 173
ClearBasic Control Reference
 Grid control

method GetChoiceListDefault

Syntax ItemData = YourGrid.GetChoiceListDefault (FieldName)

Applies To Grid (editable only)

Description The GetChoiceListDefault method returns the default item associated with the
specified column’s choice list. This method is primarily for informational purposes.
However, you can use the value returned by this method to initialize new records in a
NewRow event handler.

You assign a choice list to a column using the User Interface Editor. The cell’s column
must display the choice list using either a drop-down list box or a drop-down combo
box control. Only static choice lists may have a default value. You cannot assign the
default item using ClearBasic code.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

FieldName String Specify the name of the field associated with the desired
column. The column must display a static choice list using
either a drop-down list box or drop-down combo box.

Return Values Returns a String object containing the text of the default choice. If the column does not
have a default item, this method returns an empty string ("").

See Also GetChoiceList method

GetChoiceListDefault method
NewRow event

174 GetChoiceListDefault
ClearBasic Control Reference
 Grid control

method GetChoiceListUserData

Syntax ItemData = YourGrid.GetChoiceListUserData (Row, FieldName)

Applies To Grid (editable only)

Description The GetChoiceListUserData method returns the user data associated with the
selected choice-list item. The returned data belongs to the currently selected item in
the cell specified by the Row and FieldName parameters. The data consists of a string,
which you can use to store information about the item. This string is never displayed
to end users and is for your application’s internal use only.

You assign a choice list to a column using the User Interface Editor. The cell’s column
must display a choice list using either a drop-down list box or a drop-down combo
box control. Only static choice list items may have user data. You cannot assign the
user data using ClearBasic code.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

Row Long Specify the index of the row containing the desired cell.
This index is zero-based, that is, the first row is at index 0,
the second at index 1, and so on.
FieldName String Specify the name of the field corresponding to the column
of the desired cell.

Return Values Returns a String object containing the user data. If the selected list item does not have
any user data, this method returns an empty string ("").

See Also GetChoiceList method

GetChoiceListDefault method

GetChoiceListUserData 175
ClearBasic Control Reference
 Grid control

method GetColumnControlType

Syntax ColType = YourGrid.GetColumnControlType (FieldName)

Applies To Grid (editable only)

Description The GetColumnControlType method returns the name of the control used to edit
the specified column’s cells. This method is primarily for informational purposes.

Some methods of the grid control may only be called on columns that use specific
types of controls. You can use this method to verify the control type before calling
those methods.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameter:

Parameter Type Description

FieldName String Specify the name of the field corresponding to the
column whose control type you want to know.

Return Values Returns a String object containing the name of the control type. This method returns
one of the following values:

Control type Returned string

Checkbox "CheckBox"
Currency "Currency"
Date/time "Datetime"
Drop-Down Combo Box "Dropdown ComboBox"
Drop-Down List Box "Dropdown ListBox"
Editbox "TextBox"
Lookup "Lookup"
Masked Editbox "Mask Edit"

See Also GetChoiceList method

GetChoiceListDefault method
GetChoiceListUserData method

176 GetColumnControlType
ClearBasic Control Reference
 Grid control

method GetColumnMaxLength

Syntax ColumnWidth = YourGrid.GetColumnMaxLength (FieldName)

Applies To Grid (editable only)

Description The GetColumnMaxLength method returns the maximum number of bytes available
for storing data in the cells of the specified column. This value does not correspond to
the visual width of the column in pixels.

This value cannot be set using ClearBasic; you must set it at design time using the
User Interface Editor. You can assign a maximum length value only to lookup
controls, edit controls, and drop-down combo boxes.

The value returned by this method applies to data entered using the grid control
interface. The grid generates an error if the user types too many characters or you call
a method with a value that exceeds this limit. Data entered using the grid’s contextual
objects are not bound by this limit.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameter:

Parameter Type Description

FieldName String Specify the name of the field corresponding to the column
whose length you want to know.

Return Values Returns an integer value containing the number of bytes allowed for data in the cells
of the specified column.

See Also SetCellText method

GetColumnMaxLength 177
ClearBasic Control Reference
 Grid control

method GetColumnNames

Syntax FieldNamesList = YourGrid.GetColumnNames

Applies To Grid

Description The GetColumnNames method returns a list containing the names of each column in
the grid. The names returned by this method are the visible names displayed at the
top of the column. The name of a column does not necessarily correspond to the name
of the field associated with that column.

The order of the returned column names corresponds to the current order of the
columns in the grid. If user may rearranged the grid columns at runtime, the names
are returned in the rearranged order.

Parameters None.

Return Values Returns a list of String objects, each of which contains the name of one column.

See Also GetColumnControlType method

GetColumnMaxLength method

178 GetColumnNames
ClearBasic Control Reference
 Grid control

method GetList

Syntax Set YourList = YourGrid.GetList

YourRetVar = YourGrid.GetList (Index)

Applies To Grid

Description The GetList method returns the list of items currently in the grid.

Because of paging limitations, this method returns only the records currently in
memory. For large result sets, this list may contain only a portion of the total records.

Parameters This method accepts the following parameter:

Parameter Type Description

Index Long This parameter is optional. You can specify the index of the item
you want returned.
If you don’t specify an index, the entire list is returned.

Return Values If an index is specified, this method returns the item at the specified index. If no index
is specified, this method returns a list of the items currently in the control. The data
type is the same as the items in the grid.

See Also GetSelected method

GetNext method (Select CBX control)
GetPrevious method (Select CBX control)

GetList 179
ClearBasic Control Reference
 Grid control

method GetSelected

Syntax YourVarBool = YourGrid.GetSelected(SelectedItem)

If YourGrid.GetSelected(SelectedItem) Then
...

Applies To Grid

Description The GetSelected method returns the current selection. If an item is selected, this
method returns True and places the selected item into the SelectedItem output
parameter. If no item is selected, this method returns False and does not put a value in
the SelectedItem parameter. This method returns an error if more than one item is
selected, so it should not be used on controls that support the selection of multiple
items (use SelectedList instead).

NOTE: This method performs the same function as the Selected property, except that this
method can be used with user-defined types, unlike Selected.

This method supports the use of User-Defined Types.

Parameters This method accepts the following parameter:

Parameter Type Description

SelectedItem UDT or Specify an empty variable of type Record or of a User-Defined
Record Type. The selected item is placed into that variable. The type of
the record or UDT must match the type of items displayed in
the grid.
Always check the method’s return value before accessing this
parameter. If no item is selected, the contents of this parameter
are undefined.

Return Values Returns True if an item is selected and False if no item is selected.

Example In the following button click procedure, the code first checks whether the user
selected anything in the grid. If a selection was made, GetSelected returns the
record to MyRecord, changes the field value, then updates the database with the
changes.
Sub SelectMe_Click
Dim MyRecord As Record
Dim Bulks As New BulkSave

If MyCustList.GetSelected(MyRecord) Then
MyRecord.SetField "myfield", "Notified"

180 GetSelected
ClearBasic Control Reference
 Grid control

Bulks.UpdateRecord MyRecord
Bulks.Save
End If
End Sub

See Also SelectedIndexes method

SelectedList method
SetSelected method
ReplaceSelected method (Select CBX control)
SetSelectedById method (Select CBX control)

GetSelected 181
ClearBasic Control Reference
 Grid control

method GetSelectedColumns

Syntax FieldNameList = YourGrid.GetSelectedColumns

Applies To Grid

Description The GetSelectedColumns method returns a list of field names corresponding to

the currently selected columns. The order of the returned fields corresponds to the
order of the columns in the grid. The columns are returned in left-to-right order, that
is, the left-most column is listed first, followed by each successive column.

You use this method in a SortColumn event handler to determine which columns to
use when sorting the rows of the grid.

Parameters None.

Return Values Returns a List containing zero or more strings. Each string contains the name of a field
corresponding to a selected column.

See Also SortColumn event

182 GetSelectedColumns
ClearBasic Control Reference
 Grid control

method HideColumn

Syntax YourGrid.HideColumn FieldName, Hide

Applies To Grid

Description The HideColumn method hides the specified column. You can use this method to
prevent users from accessing information in a particular column. Your application can
also use this method to show a column that is already hidden.

When you hide a column, the column is no longer visible in the grid control. While
hidden, you can still manipulate the column and its contents using ClearBasic code.
However, the user cannot see any of the changes until you show the column again.

NOTE: The grid control does not let the user show a column that is hidden. Hidden columns
can only be modified by your ClearBasic code.

Parameters This method uses the following parameter:

Parameter Type Description

FieldName String Specify the name of the field corresponding to the column
you want to hide.
Hide Boolean Specify True to hide the column, otherwise False to show
the column again.

Return Values None

See Also Visible property (Control object)

HideColumn 183
ClearBasic Control Reference
 Grid control

method IsColumnEditable

Syntax YourBoolean = YourGrid.IsColumnEditable (FieldName)

Applies To Grid (editable only)

Description The IsColumnEditable method returns a boolean indicating whether the Editable
property of the specified column is set. If the property is set, the user can modify the
cells in this column; otherwise, the user can only view the cell contents.

You must decide at design time whether you want users to be able to modify the cells
in a particular column. Use the User Interface Editor to set the value of the column’s
Editable property as it cannot be changed using ClearBasic.

NOTE: This method only detects the Editable property set for the column in the User Interface
Editor. This method does not detect the read-only status of a cell that was set using the
SetCellReadOnly or SetRowReadOnly methods.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameter:

Parameter Type Description

FieldName String Specify the name of the field corresponding to the column
whose Editable property is to be checked.

Return Values Returns True if the specified column is editable, otherwise False.

See Also IsColumnRequired method

SetCellReadOnly method
SetRowReadOnly method
CellChanged event

184 IsColumnEditable
ClearBasic Control Reference
 Grid control

method IsColumnRequired

Syntax YourBoolean = Yourgrid.IsColumnRequired (FieldName)

Applies To Grid (editable only)

Description The IsColumnRequired method returns a boolean indicating whether the Required
property of column was set using the User Interface Editor. If this property is set, the
cell in this column must contain a value before the corresponding record can be saved.
If the property is not set, the cell can be left empty.

You must decide at design time whether or not a cell requires data. Use the User
Interface Editor to set the value of the column’s Required property as it cannot be
changed using ClearBasic.

It is your responsibility to make sure each required field contains a suitable value.
Therefore, you must always call this method in your RowChanged event handler
before attempting to save the row.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameter:

Parameter Type Description

FieldName String Specify the name of the field corresponding to the column
whose Required property is to be verified.

Return Values Returns True if the Required property is set, otherwise False.

See Also IsColumnEditable method

RowChanged event

IsColumnRequired 185
ClearBasic Control Reference
 Grid control

method RemoveByItem

Syntax RemovedItem = YourGrid.RemoveByItem (ItemToRemove)

Applies To Grid

Description The RemoveByItem method removes one item or a list of items from the grid. If any
of the specified items are not in the grid, this method removes the items it can find
and returns a list of the missing items.

Parameters This method accepts the following parameters:

Parameter Type Description

ItemToRemove variable You must specify one item or a list of items that you want
to remove from the control.
The data type of the item or list of items you specify must
match the data type of the source contextual object linked
to the grid.

Return Values Returns a List object containing zero or more records. Each record in the list
corresponds to an item that was not found in the grid.

See Also RemoveItem method

ReplaceItem method

186 RemoveByItem
ClearBasic Control Reference
 Grid control

method RemoveItem

Syntax YourGrid.RemoveItem Index

Applies To Grid

Description The RemoveItem method removes the specified item from the grid, using the index
provided. This method does not delete any information from the database. It simply
removes the specified item from the grid’s contextual object.

This method does not trigger any events.

NOTE: Because of paging limitations, the index you specify must correspond to the index of a
record relative to the currently loaded page.

Parameters This method accepts the following parameters:

Parameter Type Description

Index Long Specify the index of the item to remove. This value must be a
long integer between 0 and the number of items in the list
minus 1. If you specify an index out of this range, an error is
generated.

Return Values None

See Also AppendItem method

RemoveSelected method
Regenerate method (Select CBX control)

RemoveItem 187
ClearBasic Control Reference
 Grid control

method RemoveSelected

Syntax RetInteger = YourGrid.RemoveSelected

Applies To Grid

Description The RemoveSelected method removes the items that are currently selected in the
grid control.

Calling this method does not delete the records from the database; it simply removes
them from the result set of the most recent query. If you rerun the original query you
used to fill the grid, the query still returns the removed records.

This method does not trigger any events.

Parameters None.

Return Values This method returns the number of items that are left in the grid after the removal of
the selected item(s).

Example The following code snippet shows one application of this method. Selected items are
removed from MyControl and the number of items remaining in the control are
returned to Count. If no more items are left in the control, the REMOVE button is
disabled.
Count = MyControl.RemoveSelected
If Count = 0 Then
Remove.Enabled = False
End If

See Also RemoveByItem method

RemoveItem method
ReplaceItem method

188 RemoveSelected
ClearBasic Control Reference
 Grid control

method ReplaceItem

Syntax YourGrid.ReplaceItem ItemToPutIn, Index

Applies To Grid

Description The ReplaceItem method replaces an item in the control with another item. This
method will replace an existing item in a control list with the supplied object. The
index parameter specifies which item to replace in the list. This index must contain a
number between 0 and the number of items in the list minus 1. If the index is not in
this range, an error will result. Also, an error will result if the type of object being
replaced into the control's list is not the same as the type of objects currently in the
control's list.

The ReplaceItem method does not support UDTs. For UDTs, you must use the
ReplaceByIndex method.

Parameters This method takes the following parameters:

Parameter Type Description

ItemToPutIn variable This parameter specifies the item you want to place into the
control. The data type of the item must match the record
type displayed by the grid.
Index Long This parameter is the index of the item to be replaced. You
must use an integer value in the range from 0 to the number
of items minus one.

Return Values None

See Also GetList method

RemoveItem method
ListCount property

ReplaceItem 189
ClearBasic Control Reference
 Grid control

method SaveAnyChanges

Syntax Result = YourGrid.SaveAnyChanges

Applies To Grid (editable only)

Description The SaveAnyChanges method generates a RowChanged event if a row is being

edited and has not yet been saved. If no row is being edited, this method does
nothing.

Normally, RowChanged events are triggered when the user has edited a row and then
selects a cell in another row. However, the user can dismiss the form without selecting
another row, thus preventing the dispatch of the final RowChanged event. This
method allows you to generate the RowChanged event manually so that you can
prevent the loss of any data.

Call this method before performing any task that might cause row changes to be lost.
For example, call this method from the Click event handler of your form’s Done
button to save any changes before dismissing the form.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters None

Return Values Returns True if the grid changes were saved, or if the grid was not dirty. Returns False
if the changes could not be saved (usually due to invalid data).

Example The following example shows the Click event handler for a form’s Done button.
When this button is clicked, the event handler tries to save any changes to the grid. If
changes were made, the event handler closes the form, otherwise it leaves the form
open so that the user can correct any problems.
Sub CLOSE_Click
If GridCtl.SaveAnyChanges Then
Me.Close
End If
End Sub

See Also SaveAnyChanges method

190 SaveAnyChanges
ClearBasic Control Reference
 Grid control

method SelectedIndexes

Syntax Set YourList = YourGrid.SelectedIndexes

Applies To Grid

Description The SelectedIndexes method returns a list of the indexes of the currently selected
items in a control.

If a control allows only one item to be selected at a time, the returned list will always
contain 0 or 1 items (indexes). If a control allows for more than one item to be selected
at a time, the returned list contains 0 or more items. (If no items are currently selected,
the returned list contains 0 items.)

NOTE: Because of paging limitations, the returned indexes correspond to the selected records
on the currently loaded pages only.

Parameters None.

Return Values Returns a list of long integers which are the indexes of the items currently selected in
the control.

See Also GetSelected method

SelectedList method
Selected property

SelectedIndexes 191
ClearBasic Control Reference
 Grid control

method SelectedList

Syntax Set YourRetList = YourGrid.SelectedList

Applies To Grid

Description The SelectedList method returns a list of the currently selected items in a control.

NOTE: Because of paging limitations, the selection returned by this method never extends
beyond page boundaries.

Use this method where more than one item at a time can be selected in a control. If
only one item can be selected at a time in the control, using the Selected property
may be more convenient.

Parameters None

Return Values Returns a List object containing zero or more items. Each item corresponds to a
selected record in the grid.

See Also GetSelected method

Regenerate method (Select CBX control)
SelectedIndexes method
Selected property

192 SelectedList
ClearBasic Control Reference
 Grid control

method SetCellColoring

Syntax YourGrid.SetCellColoring "YourColorProc", WholeRow?

Applies To Grid

Description The SetCellColoring method associates a custom color procedure with the grid.
You must write the color procedure that you pass to this method. When you call this
method, the grid immediately runs your color procedure to establish the colors for the
grid’s current contents. After this method returns, the grid runs the color procedure
any time you add or remove rows.

The color procedure you define must take no parameters and return no values. The
following example shows a sample color procedure:
Sub MyColorProc
' Apply color using the ColorCells method
End Sub

In your color procedure, call the ColorCells method to apply colors to the cells of
the grid. The colors you specify must belong to the current color scheme. To ensure
that the colors exist, call the SetColorScheme method prior to calling
SetCellColoring.

IMPORTANT: If you specify a ColorProc that is invalid or that cannot be found, all subsequent
operations affecting the grid will fail.

Parameters This method accepts the following parameters:

Parameter Type Description

YourColorProc String Specify the name of your color procedure. The color
procedure you define must be located in the form module
belonging to the grid control’s form.
WholeRow? Boolean This parameter is optional and is set to True by default.
Specify True if you want the color procedure’s Foreground
and Background coloring to apply to the entire row in the
grid. (If you specify True, do not specify any column
information when calling ColorCells in your color
procedure.)
Specify False if you want the color procedure’s Foreground
and Background coloring to apply only to certain cells in the
row, and not the whole row. (If you specify False, you must
specify Columns in the color procedure’s invocation of
ColorCells: for more information, see ColorCells.)

Return Values None

SetCellColoring 193
ClearBasic Control Reference
 Grid control

Examples The following example shows a sample color procedure that applies a color to the
column containing the “priority” field.

The first part of the example sets up the initial color scheme. In a global module, the
Initialize_App routine defines the color scheme and associates different colors
with the values that can exist in the “priority” field. In the global module, define the
following code:
Sub Initialize_App
Dim ColorVals As New List
Dim ColorNames As New List

ColorVals.appendItem "red", "purple","green",

"black","cyan"

ColorNames.AppendItem "Immediate", _
"Urgent", "Casual", "Other","Medium"

App.CreateColorScheme "MyColorScheme", _
ColorNames, ColorVals
End Sub

In the form module, the Form_Load routine sets the current color scheme and
associates a color procedure with the grid. The color procedure iterates through the
rows of the grid and assigns an appropriate color to the “priority” field of each row, as
shown in the following code:
'In the form module
Sub Form_Load
App.SetColorScheme "MyColorScheme"
MyGrid.SetCellColoring "MyColorProc"
Me.DoDefault
End Sub

' Define the color procedure

Sub MyColorProc
Dim SourceList As List
Dim CaseRec As Record
Dim Foregrounds As New List
Dim Backgrounds As New List
Dim Row As integer

Dim RowList As New List

Dim ColList As New List

Foregrounds.ItemType="String"
Backgrounds.ItemType="String"
RowList.ItemType="Integer"
ColList.ItemType="Integer"

Set SourceList = MyGrid.GetList

For Row = 0 to SourceList.Count -1

Set CaseRec = SourceList.ItemByIndex(Row)
Foregrounds.AppendItem CaseRec.GetField("priority")

194 SetCellColoring
ClearBasic Control Reference
 Grid control

Backgrounds.AppendItem "" ' Use the default color

RowList.AppendItem Row
ColList.AppendItem 2 ' Third column is “priority”
Next Row

MyGrid.ColorCells Foregrounds, Backgrounds,

RowList, ColList
End Sub

See Also ColorCells method

SetCellColoring 195
ClearBasic Control Reference
 Grid control

method SetCellFocus

Syntax YourBoolean = YourGrid.SetCellFocus (Row, FieldName)

Applies To Grid (editable only)

Description The SetCellFocus method sets the cell focus to the specified cell. The cell focus
indicates which cell in the grid receives system-level events such as keyboard events.
Only one cell in the grid may own the cell focus at any given time.

The grid control highlights the cell with the cell focus and displays the control
associated with that cell’s column. If the cell is hidden behind another control, this
method fronts the entire grid control.

If a cell is being edited, changing the cell focus generates a CellChanged event and
may also generate a RowChanged event. This method generates a RowChanged event
if the new cell is in a different row from the cell that previously owned the cell focus.
The CellChanged event occurs before the RowChanged event.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

NOTE: Because of paging restrictions, you can set the cell focus to a cell only if the cell is on a
page currently loaded into memory.

Parameters This method uses the following parameters:

Parameter Type Description

Row Long Specify the index of the row containing the desired cell. This
index is zero-based, that is, the first row is at index 0, the
second at index 1, and so on.
FieldName String Specify the name of the field corresponding to the cell’s
column.

Return Values Returns True if successful, otherwise False.

See Also SetFocus method (Control object)

196 SetCellFocus
ClearBasic Control Reference
 Grid control

method SetCellReadOnly

Syntax YourBoolean = YourGrid.SetCellReadOnly (Row, FieldName,

ReadOnly)

Applies To Grid (editable only)

Description The SetCellReadOnly method sets the read-only status of a single cell in the grid
control. You can use this method to prevent the user from editing specific cells in the
grid.

Refreshing the contents of the grid neutralizes the effects of this method. After you
refresh the grid, you must call SetRowReadOnly again to mark any desired rows as
read-only. As a result, this method is most appropriate for use on the current row in
situations where you want to change the read-only state of cells based on input to
another cell.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

NOTE: Because of paging restrictions, you can set the read-only status of a cell only if the cell
is on a page currently loaded into memory.

Parameters This method uses the following parameters:

Parameter Type Description

Row Long Specify the index of the row containing the desired cell. This
index is zero-based, that is, the first row is at index 0, the
second at index 1, and so on.
FieldName String Specify the name of the field corresponding to the column
containing the desired cell.
ReadOnly Boolean Specify True if the cell is read-only, otherwise False to allow
editing.

Return Values Returns True if the operation is successful, otherwise False.

See Also SetEditStates method

SetRowReadOnly method
Refresh method (Control object)

SetCellReadOnly 197
ClearBasic Control Reference
 Grid control

method SetCellText

Syntax YourBoolean = YourGrid.SetCellText (Row, FieldName,

"DataString")

Applies To Grid (editable only)

Description The SetCellText method sets the value for the specified cell, even if the cell’s
column is not editable. The length of the new data string must not exceed the
maximum length allowed by the field. After setting the new value, this method
generates a CellChanged event.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

Row Long Specify the index of the row containing the desired cell. This
index is zero-based, that is, the first row is at index 0, the
second at index 1, and so on.
FieldName String Specify the name of the field corresponding to the cell.
Data String Specify the new data to assign to the cell.

Return Values Returns True if the operation is successful, otherwise False.

See Also GetColumnMaxLength method

CellChanged event

198 SetCellText
ClearBasic Control Reference
 Grid control

method SetContextMenuEnabled

Syntax YourGrid.SetContextMenuEnabled ItemName, Enabled

Applies To Grid

Description The SetContextMenuEnabled method enables or disables a menu item in a

context-sensitive menu. Disabled menu items are displayed in the menu but cannot be
selected by the user. Enabled menu items can be selected and generate an appropriate
menu item event.

You can call this method from a ContextMenuDisplaying event handler to adjust
the appearance of the items in the menu. The enabled state of the item does not
change until you call this method again.

You may use this method to modify both permanent menu items and those added
using the AppendContextMenu method. To set the default enabled state of a
permanent menu item, modify the item’s entry in the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify the identification string of the desired menu item. This
is the string you assigned to the item in the User Interface
Editor or using the AppendContextMenu method.
Enabled Boolean Specify True to enable the menu item; specify False to disable
it.

Return Values None

See Also AppendContextMenu method

SetContextMenuVisible method
ContextMenuDisplaying event
ContextMenu_Select event

SetContextMenuEnabled 199
ClearBasic Control Reference
 Grid control

method SetContextMenuVisible

Syntax YourGrid.SetContextMenuVisible ItemName, Visible

Applies To Grid

Description The SetContextMenuVisible method shows or hides a menu item in a context-

sensitive menu. The visibility of a menu item determines whether or not the item
appears in the menu. Calling this method with the Visible parameter set to False
removes the item from the menu. Specifying True for the Visible parameter displays
the item to its original place in the menu.

You can call this method from a ContextMenuDisplaying event handler to adjust
the appearance of the items in the menu. The visible state of the item does not change
until you call this method again.

You may use this method to modify both permanent menu items and those added
using the AppendContextMenu method. To set the default visible state of a
permanent menu item, modify the item’s entry in the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify the identification string of the desired menu item. This
is the string you assigned to the item in the User Interface
Editor or using the AppendContextMenu method.
Visible Boolean Specify True to make the menu item visible; specify False to
hide it.

Return Values None

See Also AppendContextMenu method

SetContextMenuEnabled method
ContextMenuDisplaying event

200 SetContextMenuVisible
ClearBasic Control Reference
 Grid control

method SetEditStates

Syntax YourGrid.SetEditStates StateList, UseExisting, RowList,

FieldNameList

Applies To Grid (editable only)

Description The SetEditStates method sets the read-only state for a group of rows or cells.
Call this method from a Refresh event handler to set the read-only state of the rows
or cells when the grid is updated. If you omit the FieldNameList parameter, this
method applies the changes to entire rows. If you specify a value for the
FieldNameList parameter, the changes are applied to individual cells.

To mark a set of rows as read-only, specify the same number of elements in both the
StateList and RowList parameters. This method assigns each element in the StateList
parameter to the row at the same index in the RowList parameter.

To mark a set of specific cells as read-only, you must specify a FieldNameList

parameter with the same number of elements as the RowList parameter. For any
given index, the read-only status in the StateList parameter is applied to the cell at the
row and column specified in the RowList and FieldNameList parameters. The
following table shows an example of how the elements in each list are applied:

Row Column Applied value

RowList[0] FieldNameList[0] StateList[0]
RowList[1] FieldNameList[1] StateList[1]
RowList[2] FieldNameList[2] StateList[2]
RowList[3] FieldNameList[3] StateList[3]

IMPORTANT: If you are modifying a baseline form, the UseExisting parameter must
contain the value True.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

SetEditStates 201
ClearBasic Control Reference
 Grid control

Parameter Type Description

StateList List Specify a list of long integers. For each index, specify the
value 1 to make the element at that index read-only. Specify
the value 0 to make the element editable.
The number of elements in this list must be equal to the
number of elements in RowList.
UseExisting Boolean Specify True to retain the entries from previous calls to this
method; otherwise, specify False to clear any previous entries
and specify new read-only states.
RowList List Specify a list of long integers. This list specifies the indexes of
the rows whose cells you want to modify. Row indexes are
zero-based, that is, the first row is at index 0, the second at
index 1, and so on.
FieldNameList List Specify a list of strings. This list specifies the names of the
fields whose cells you want to modify. If you omit this
parameter, the settings apply to the entire row.

Return Values None

Example The following code shows the Refresh event handler used to modify the read-only
status of a set of cells. This event handler iterates through the new list of rows and
checks the current status and owner of each record. If the record’s current status is
"closed", this method makes the "title" field read-only. If the supervisor owns the
record, this method makes the "priority" field editable.
Sub MyGrid_Refresh()
dim source as List
dim Value as New List
dim Rows as New List
dim Cols as New List
dim RecBuf as Record

dim i as Integer
dim CurStatus as String
dim Owner As String

Value.ItemType = "Integer"
Rows.ItemType = "Integer"
Cols.ItemType = "String"

set source = MyGrid.GetList

if source.Count > 0 Then
For i = 0 to source.Count - 1
set RecBuf = source.ItemByIndex(i)

if RecBuf.RecordType = "qry_bug_view" Then

CurStatus = RecBuf.GetField("status")

' If the status is closed, mark the

' title field of the row as read only.
if CurStatus = "Closed" Then
Rows.AppendItem i

202 SetEditStates
ClearBasic Control Reference
 Grid control

Cols.AppendItem "title"
Value.AppendItem 1
End If
End If

' If the supervisor owns the record,

' mark the priority field as editable.
Owner = RecBuf.GetField(“owner”)
If Owner = "Supervisor" Then
Rows.AppendItem i
Cols.AppendItem "priority"
Value.AppendItem 0
End If
Next i

GridCtl.SetEditStates Value, False, _

Rows, Cols

Me.ForceRedraw
End If
End Sub

See Also SetCellReadOnly method

SetRowReadOnly method
Refresh event
Refresh method (Control object)

SetEditStates 203
ClearBasic Control Reference
 Grid control

method SetNewRowIndicator

Syntax YourGrid.SetNewRowIndicator Row

Applies To Grid (editable only)

Description The SetNewRowIndicator places a new row indicator next to the row and marks
the row as dirty. Call this method immediately after creating a new row in the
NewRow event handler. When the user begins editing a cell in the row, the control
removes the indicator automatically.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

Row Long Specify the index of the desired row. This index is zero-based,
that is, the first row is at index 0, the second at index 1, and so
on.

Return Values None

See Also NewRow event

204 SetNewRowIndicator
ClearBasic Control Reference
 Grid control

method SetRowReadOnly

Syntax YourBoolean = YourGrid.SetRowReadOnly (Row, ReadOnly)

Applies To Grid (editable only)

Description The SetRowReadOnly method sets the read-only status of a row of cells in the grid
control. You can use this method to prevent the user from editing the contents of an
entire row.

Refreshing the contents of the grid neutralizes the effects of this method. After you
refresh the grid, you must call SetRowReadOnly again to mark any desired rows as
read-only. As a result, this method is most appropriate for use on the current row in
situations where you want to change the read-only state of cells based on input to
another cell.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

Row Long Specify the index of the desired row. This index is zero-
based, that is, the first row is at index 0, the second at index 1,
and so on.
ReadOnly Boolean Specify True if the row is read-only, otherwise False to allow
editing.

Return Values Returns True if the operation is successful, otherwise False.

See Also SetCellReadOnly method

SetEditStates method
Refresh method (Control object)

SetRowReadOnly 205
ClearBasic Control Reference
 Grid control

method SetSelected

Syntax YourGrid.SetSelected ItemToSelect

Applies To Grid

Description The SetSelected method deselects any previously selected items in a grid and
selects the specified item or items. Because of paging limitations, selections are limited
to those rows on the currently loaded pages. The grid’s source contextual object
always contains the contents of the currently loaded pages.

NOTE: Because this method sets the selection programmatically, it does not generate a Click
event for the grid.

Parameters This method takes one of the following parameters:

Parameter Type Description

ItemToSelect List Specify a list of integer values. Each value in this list
corresponds to the index of a row you want to select.

Return Values None

See Also UnSelect method

SetSelected method (Select CBX control)
SetSelectedById method (Select CBX control)

206 SetSelected
ClearBasic Control Reference
 Grid control

method UndoRowChanges

Syntax YourGrid.UndoRowChanges

Applies To Grid (editable only)

Description The UndoRowChanges method aborts the changes made to a row and restores the
original values of the changed cells. Call this method only from your RowChanged
event handler.

Normally, you use this method after prompting the user to discard any row changes.
Use this method to discard the row changes.

This method is available only for grids whose Editable property has been set to Yes in
the User Interface Editor.

Parameters None

Return Values None

Example The following example prompts the user to save, discard, or cancel any row changes.
If the user chooses to discard the row changes, the RowChanged event handler calls
UndoRowChanges.
Sub MyGrid_RowChanged()
Select Case App.MsgBox(“Save changes?”, _
cbSaveDiscardCancel, “Confirmation Message”)
Case cbIdSave
Call SaveData
Case cbIdCancel
MyGrid.AbortRowChange cbAbortUndo, ““, “login_name”
Case cbIdDiscard
MyGrid.UndoRowChanges
End Select
End Sub

See Also AbortCellChange method

AbortRowChange method
RowChanged event

UndoRowChanges 207
ClearBasic Control Reference
 Grid control

method UnSelect

Syntax YourGrid.Unselect

Applies To Grid

Description The UnSelect method deselects all items in the control.

Parameters None

Return Values None

Example The following example implements a Click event handler for a button. When the
button is pressed, the current selection is cleared.
Sub cmdClearSelection_Click
MyGrid.Unselect
End Sub

See Also SetSelected method

SetSelected method (Select CBX control)
SetSelectedById method (Select CBX control)

208 UnSelect
ClearBasic Control Reference
 Grid control

method Up

Syntax YourGrid.Up

Applies To Grid

Description The Up method moves the selected item(s) up one place in the control.

When used on controls, this method moves the selected item or items in the control up
one place. This means that each selected item is moved up so that it appears one line
higher than previously displayed. Items that are displaced are moved down
accordingly. Note that this method will work if multiple items are selected; in that
case, some displaced items may be moved down several places to make room for the
items that move up.

If a selected item is already at the top of the list, it will remain at the top of the list.
Additionally, if more than one item is selected, but all the items between it and the top
of the list are also selected, then that item will remain in its previous position.

Parameters None

Return Values None

See Also Down method

Up 209
ClearBasic Control Reference
 Grid control

property AppendRows

Syntax YourValue = YourGrid.AppendRows

Applies To Grid (editable only)

Description The AppendRows property contains a boolean value indicating whether or not new
rows can be added to the grid. If this property is set to True, the user may add new
rows by selecting the last row in the grid and pressing the down-arrow key.

This property is read-only from ClearBasic code. You must use the User Interface
Editor to set the value of this property.

This property is available only for grids whose Editable property has been set to Yes
in the User Interface Editor.

See Also NewRow event

210 AppendRows
ClearBasic Control Reference
 Grid control

property CObj

Syntax Set RetCObj = YourGrid.CObj

YourGrid.CObj = SelectedCObj

Applies To Grid

Description The CObj property contains the ContextualObject instance currently associated with
the grid control. You can assign a new contextual object to the grid by changing the
value in this property. If you change the contextual object, make sure you refresh the
contents of the grid.

This property applies only to grids that support multiple contextual objects. For
information on creating grids that support multiple contextual objects, see the User
Interface Editor Guide.

CAUTION: If the grid is associated with a Select CBX control, do not modify this property.
Use the SetCObj method of the Select CBX control instead. The Select CBX maintains state
information about the current contextual object. Changing the grid’s contextual object in this
situation can cause errors in the behavior of the grid.

See Also Refresh method (Control object)

SetCObj method (Select CBX control)

CObj 211
ClearBasic Control Reference
 Grid control

property DataChanged

Syntax RetBoolean = YourGrid.DataChanged

YourGrid.DataChanged = NewValue

Applies To Grid

Description The DataChanged property indicates whether the user made modifications to the
grid’s contents. This property does not indicate changes made programmatically. If
you modify the contents of a control programmatically, you can change the value in
this property directly to reflect your changes.

This property contains the value True if changes were made to the control, otherwise
it contains the value False.

IMPORTANT: The DataChanged property is not affected by selecting a row of the grid.

212 DataChanged
ClearBasic Control Reference
 Grid control

property Dirty

Syntax YourValue = YourGrid.Dirty

Applies To Grid (editable only)

Description The Dirty property contains a boolean value indicating whether the grid contains
any dirty rows. A dirty row is one that has been changed by the user but which has
not been saved to the database. The grid control displays a pencil icon ( )
immediately to the left of any dirty row.

Using the AppendItem method to add a new row to the grid has no effect on this
property. However, modifying the contents of a cell in that row sets this property to
True.

This property is read-only from ClearBasic code.

This property is available only for grids whose Editable property has been set to Yes
in the User Interface Editor.

See Also SaveAnyChanges method

SetCellText method

Dirty 213
ClearBasic Control Reference
 Grid control

property ListCount

Syntax NumOfRows = YourGrid.ListCount

Applies To Grid

Description The ListCount property contains the number of rows currently loaded into memory
for the grid. If the grid supports paging, this value can be less than the total number of
rows in the grid. Compare this property with the TotalRows property, which returns
the total number of rows in the grid.

This property is read-only.

214 ListCount
ClearBasic Control Reference
 Grid control

property ListIndex

Syntax ItemIndex = YourGrid.ListIndex

Applies To Grid

Description The ListIndex property contains an integer value indicating the index of the
selected item. If no item is selected, the value is -1. If multiple items are selected, this
property contains the index of the first item in the selection.

This property is read-only.

ListIndex 215
ClearBasic Control Reference
 Grid control

property MultiSelect

Syntax Setting = YourGrid.MultiSelect

YourGrid.MultiSelect = Setting

Applies To Grid

Description The MultiSelect property contains a boolean value that indicates whether the grid
supports the selection of more than one item. Set this property to True to support the
selection of multiple items in the grid. Set it to False to disallow multiple selected
items.

Changing this property at runtime does not permanently set the property for the grid.
The new value remains in effect only until the form containing the grid is dismissed.

216 MultiSelect
ClearBasic Control Reference
 Grid control

property NewIndex

Syntax YourRetInt = YourGrid.NewIndex

Applies To Grid

Description The NewIndex property contains a long integer with the index of the most recently
added item. You can pass this index to other methods so that they can modify (or
subsequently remove) the item.

When you add a new item, the AppendItem method updates this property to reflect
the position of any new items. Methods that remove items reset the value in this
property to -1.

This property is read-only.

See Also AppendItem method

Clear method
RemoveByItem method
RemoveItem method
RemoveSelected method
ReplaceItem method

NewIndex 217
ClearBasic Control Reference
 Grid control

property PagingEvent

Syntax YourValue = YourGrid.PagingEvent

Applies To Grid

Description The PagingEvent property contains a boolean value indicating whether or not the
grid is currently loading a new page of data. This event occurs when the user attempts
to scroll beyond the number of records currently in memory. See Paging on page 149
for more information on how grids handle paging.

You should check this property from your CellChanged and RowChanged event
handlers. If this property contains the value True, your event handlers cannot cancel
any changes that were made to the cells. The event handler must either save or
discard the changes.

See Also CellChanged event

RowChanged event

218 PagingEvent
ClearBasic Control Reference
 Grid control

property Parent

Syntax Set YourForm = YourGrid.Parent

Applies To Grid

Description The Parent property contains a reference to the Form object that owns the grid. You
can use this property to access information on the parent form.

This property is read-only.

See Also SetParent method (Form object in the ClearBasic Object Reference)

Parent 219
ClearBasic Control Reference
 Grid control

property PromptOnSave

Syntax YourValue = YourGrid.PromptOnSave

Applies To Grid (editable only)

Description The PromptOnSave property contains a boolean value indicating whether or not the
user should be prompted before saving any data to the database. Check the value of
this property in your RowChanged event handler before saving a row to the database.

If this property contains the value True, display a dialog to confirm the changes with
the user. Your dialog should display buttons that allow the user to save or discard the
changes. You should also provide a Cancel button to stop the action.

NOTE: In cases where the user may want to modify multiple rows, you can add an option to
your dialog that allows the user to skip future confirmation dialogs. If the user sets this option,
your RowChanged code can simply use the user’s last choice

This property is read-only from ClearBasic code. You must use the User Interface
Editor to set the value of this property.

This property is available only for grids whose Editable property has been set to Yes
in the User Interface Editor.

See Also RowChanged event

220 PromptOnSave
ClearBasic Control Reference
 Grid control

property SelCount

Syntax NumItems = YourGrid.SelCount

Applies To Grid

Description The SelCount property contains an integer that indicates the number of currently
selected items in the grid. If no items are selected, this property contains the value 0.
This property is read-only.

SelCount 221
ClearBasic Control Reference
 Grid control

property Selected

Syntax Set YourReturn = YourGrid.Selected

Applies To Grid

Description The Selected property contains the selected item in the grid. It is not intended to be
used for controls where multiple items can be selected. (If more than one item is
selected, an error is generated.)

IMPORTANT: This property cannot be used on controls that contain user-defined type values.
If the control contains user-defined type values, then use the GetSelected method.

This property returns the actual item selected. The type of the item is the same as the
record type for the grid’s source contextual object. If no item is selected, it returns a
variant NULL value.

See Also GetSelected method

SelectedIndexes method
SelectedList method

222 Selected
ClearBasic Control Reference
 Grid control

property Sorted

Syntax IsSorted = YourList.Sorted

Applies To Grid

Description The Sorted property contains a boolean value indicating whether the items in the
control’s list are sorted. Sorting is determined by the current settings of the grid’s
source contextual object. This property contains the value True if the items in the
control’s source contextual object are sorted, otherwise False.

This property is read-only.

See Also Sort method (ContextualObject object in the ClearBasic Object Reference)

Sorted 223
ClearBasic Control Reference
 Grid control

property Tag

Syntax YourGrid.Tag = "YourString"

YourString = YourGrid.Tag

Applies To Grid

Description The Tag property allows you to assign a tag string to the grid, with no effect other
than identifying the object in some way or providing extra data about it.

224 Tag
ClearBasic Control Reference
 Grid control

property TopIndex

Syntax YourGrid.TopIndex = Index

Index = YourGrid.TopIndex

Applies To Grid

Description The TopIndex property scrolls the item of the specified index to the top of the
control. It does not permanently move the item in relation to the other items, but only
moves it up temporarily. The next time the user scrolls the grid, the position of the
items in the list will change.

You can get the TopIndex anytime, and you can also set the TopIndex, but you must
be aware that there are certain operations that will destroy your setting of this
property. Essentially, if you do anything to the control or the control’s contextual
object in the same event, your setting of the TopIndex will be lost. This includes:
AppendItem, SetSelected, Refresh, Fill, and so on. So, the TopIndex setting
will only take effect if you are careful not to do any other things that change the
control.

When calling this method, you may specify any integer greater than zero and less
than the total number of items in the control.

When read, this property returns the index of the item currently at the top of the
control.

TopIndex 225
ClearBasic Control Reference
 Grid control

property TotalRows

Syntax YourValue = YourGrid.TotalRows

Applies To Grid (editable only)

Description The TotalRows property indicates the total number of rows in the grid. This value
includes all rows, whether or not they are loaded into memory. Compare this property
with the ListCount property, which returns the number of rows currently loaded
into the grid.

This property is read-only.

This property is available only for grids whose Editable property has been set to Yes
in the User Interface Editor.

See Also ListCount property

226 TotalRows
ClearBasic Control Reference
 Grid control

event AdhocCellChanged

Syntax Sub YourGrid_AdhocCellChanged

Applies To Grid

Description The AdhocCellChanged event notifies your application when the value of an adhoc
query cell changes to a non-empty value. The grid control sends this event instead of a
CellChanged event when the cell focus leaves a cell in the adhoc query row. This
event only occurs if the grid is associated with a Select CBX control displaying the
adhoc query row. This event does not occur if the contents of the adhoc query cell are
cleared.

In your AdhocCellChanged event handler, validate the cell’s new value. For
example, you might perform checks to make sure an integer value is within a specific
range. You can get the cell value and location by calling the GetChangedCell
method.

When your event handler exits, the grid control stores the cell value internally. If the
cell contains an invalid value, you can prevent the new value from being saved by
calling the RejectAdhocCellEntry method of the Select CBX.

NOTE: To validate cells outside of the adhoc query row, use the CellChanged event instead.

This property is available only for grids whose Editable property has been set to Yes
in the User Interface Editor.

See Also GetChangedCell method

SetCellText method
CellChanged event
RejectAdhocCellEntry method (Select CBX control)

AdhocCellChanged 227
ClearBasic Control Reference
 Grid control

event Cell_Btn_Click

Syntax Sub YourGrid_Cell_Btn_Click (ButtonName, FieldName, Text)

Applies To Grid (editable only)

Description The Cell_Btn_Click event reports the click of a button in a Lookup, dropdown list
box, or dropdown combo box control of the grid. This event occurs after the user has
clicked the button but before any other actions are taken.

For cells that contain a dropdown list box or dropdown combo box, the grid control
calls your event handler to give it a chance to update the contents of the dropdown
list. After calling your event handler, the grid displays the list and sends additional
events in response to the user’s selection.

For cells that contain a lookup control, you must use this event to handle clicks in the
Lookup ( ) and GoTo ( ) buttons of the control. When the user clicks the
Lookup button, use your event handler to display an appropriate selection form.
After the user makes a selection, change the cell text to display the value of the
selected item in the cell.

When the user clicks the GoTo button, use your event handler to display the details of
the currently selected item. The grid sends this event only if the cell contains a non-
empty string. The Text parameter contains the contents of the cell; use this parameter
to locate the item selected by the user.

NOTE: This event replaces the Lookup_Click, GoTo_Click, and

Dropdown_Displaying events and should be used instead of those events. The old events
are still supported for backward compatibility. If this event is not present, the old event is
called.

Parameters This event receives the following parameters:

228 Cell_Btn_Click
ClearBasic Control Reference
 Grid control

Parameter Type Description

ButtonName String Contains the name of the type of button that was clicked by the
user. This parameter must contain one of the following values:
String Type
"Lookup" Lookup button of a Lookup control
"GoTo" GoTo button of a Lookup control
"Dropdown" Dropdown list box or dropdown combo
box control
FieldName String Contains the name of a field displayed in a column of the grid.
The corresponding column contains the button that was
clicked.
Text String Contains the text that is currently in the cell containing the
button. This text indicates the currently selected item for the
dropdown list or Lookup control.
When the user clicks a GoTo button, display the details for the
item specified by this parameter.

See Also Cell_List_Select event

Cell_Btn_Click 229
ClearBasic Control Reference
 Grid control

event CellChanged

Syntax Sub YourGrid_CellChanged

Applies To Grid (editable only)

Description The CellChanged event notifies your application when the value of a grid cell
changes. The grid sends this event automatically when the focus leaves a cell whose
contents have changed. The user may change the cell focus by selecting another cell or
you may change the focus programmatically by calling the SetCellFocus method.

In your CellChanged event handler, validate the cell’s new value. For example, you
might perform checks to make sure an integer value is within a specific range. You can
get the cell value and location by calling the GetChangedCell method.

IMPORTANT: Use this event only for validating the contents of the cell. Do not attempt to
display any new forms or modify the contents of any grid cells from your event handler.

When your event handler exits, the grid control saves the cell value to the control’s
contextual object. If the cell contains an invalid value, you can prevent the new value
from being saved by calling the AbortCellChange method.

NOTE: To validate the value in a cell belonging to the adhoc query row, use the
AdhocCellChanged event instead.

This property is available only for grids whose Editable property has been set to Yes
in the User Interface Editor.

Example The following example shows the CellChanged event handler for the grid whose
name is GridCtl. This event handler validates only the quantity field of the grid. If
the user specifies a negative quantity, the event handler calls the AbortCellChange
method to notify the user that a positive value must be entered.
Sub GridCtl_CellChanged
dim rowNum as Integer
dim fieldName as String
dim fieldData as String
dim numItems as Integer

' Get the info for the cell that changed.

GridCtl.GetChangedCell rowNum, fieldName, fieldData

' Validate the cell’s contents.

If fieldName = "quantity" Then
If IsNumeric(fieldData) And fieldData < 0 Then
AbortCellChange cbAbortDisplayOK, _
"Enter a positive integer value."
End If
End If
End Sub

230 CellChanged
ClearBasic Control Reference
 Grid control

See Also AbortCellChange method

GetChangedCell method
SetCellText method
AdhocCellChanged event
Cell_List_Select event
SetFocus method (Control object)

CellChanged 231
ClearBasic Control Reference
 Grid control

event Cell_Click

Syntax Sub YourGrid_Cell_Click (RowNumber, FieldName)

Applies To Grid (editable only)

Description The Cell_Click event reports a click in a different cell than the currently selected
cell. Subsequent clicks in the same cell do not trigger this event. However, clicking in a
different cell generates a new Cell_Click event for that cell.

The grid fires this event for every cell of the grid, including the row and column
headers. When the user clicks in a row header, the FieldName parameter contains an
empty string. When the user clicks in a column header, this event sets the RowNumber
parameter to a negative number. When you click in any other cell, the grid selects the
row containing that cell.

For editable grids, if the current cell is dirty, the grid sends a CellChanged event
before sending this event. If the CellChanged event prevents the change of focus,
this event is not sent.

Parameters This event receives the following parameters:

Parameter Type Description

RowNumber Long Contains the index of the cell’s row. Due to paging
restrictions, this index is always relative to the beginning
of the current page.
FieldName String Specifies the name of the field. If the event occurs in a row
header, this parameter contains an empty string.

See Also GetSelected method

Cell_Btn_Click event
CellChanged event

232 Cell_Click
ClearBasic Control Reference
 Grid control

event Cell_List_Select

Syntax Sub YourGrid_Cell_List_Select (ButtonName, FieldName, Text)

Applies To Grid (editable only)

Description The Cell_List_Select event reports the selection of an item in a dropdown list
box or dropdown combo box control. The grid control sends this event immediately
prior to a CellChanged event; however, this event occurs while the cell still has the
focus.

In your Cell_List_Select event handler, perform any tasks related to choosing a

new item from the list. For example, you might want to update other cells in the row
whose values are dependent upon the selected list item. To determine the row in
which the event occurred, call the GetSelected method.

Parameters This event receives the following parameters:

Parameter Type Description

ButtonName String Contains the name of the type of button that was clicked
by the user. Currently, only dropdown list box and
dropdown combo box controls support this event so the
parameter contains the string "Dropdown".
FieldName String Contains the name of a field displayed in a column of the
grid. The corresponding column contains the cell that
was clicked.
Text String Contains the text for the newly selected item in the list.

See Also Cell_Btn_Click event

CellChanged event

Cell_List_Select 233
ClearBasic Control Reference
 Grid control

event Click

Syntax Sub YourGrid_Click

Applies To Grid

Description The Click event occurs when the user clicks in a different row. Subsequent clicks in
the same row do not generate additional Click events. However, clicking in a
different row generates a new Click event for that row.

The Click event handler reports clicks in both the rows of the list and in the column
headers of the list. If a click occurs in a column header, the GetSelected method
returns False and the SelectedList method returns an empty list.

For editable grids, if the current row is dirty and the user clicks in another row, the
Click event for the new row fires after the RowChanged event for the old row.

See Also Cell_Click event

234 Click
ClearBasic Control Reference
 Grid control

event ContextMenuDisplaying

Syntax Sub YourGrid_ContextMenuDisplaying

Applies To Grid

Description The ContextMenuDisplaying event notifies your control that its context-sensitive
menu is about to be displayed. This event is sent before the menu is displayed. Use
this event to update the appearance of the menu and its items. You can enable or
disable items, set the visibility of items, or add items to the menu as appropriate.

In your ContextMenuDisplaying event handler, modify the menu and its

appearance to reflect the current state of the control. For example, if your menu
contains a Select All command, you might want to disable the command if the entire
contents of the control are already selected.

Example The following example enables and disables items in a grid control’s context-sensitive
menu. The new items allow the user to select all of the rows in the grid and to deselect
whatever is currently selected. Because the items do not apply in all situations, they
are disabled when the appropriate conditions are met.
Sub GridCtl_ContextMenuDisplaying
Dim numSelItems As Integer
Dim numTotalItems As Integer

' Enable items as appropriate.

numSelItems = GridCtl.SelCount
numTotalItems = GridCtl.TotalRows

' If everything is already selected, disable

' the Select All item.
If numSelItems = numTotalItems Then
GridCtl.SetContextMenuEnabled _
"cntxSelectAll", FALSE
End If

' If there is no selection, disable the

' Select None item.
If numSelItems = 0 Then
GridCtl.SetContextMenuEnabled _
"cntxSelectNone", FALSE
End If
End Sub

See Also AppendContextMenu method

SetContextMenuEnabled method
SetContextMenuVisible method
ContextMenu_Select event

ContextMenuDisplaying 235
ClearBasic Control Reference
 Grid control

event ContextMenu_Select

Syntax Sub YourGrid_ContextMenu_Select (EventName)

Applies To Grid

Description The ContextMenu_Select event notifies your application that the user chose an
item from the grid’s context-sensitive menu. In your event handler, perform the task
associated with the menu item. Use the EventName parameter to determine which
menu item was selected by the user.

You can define menu items at design time using the User Interface Editor or at
runtime using the AppendContextMenu method.

Parameters This event receives the following parameter:

Parameter Type Description

EventName String Contains the internal name you assigned to the event handler
using the User Interface Editor. If you used the
AppendContextMenu method to create the item, this
parameter contains the value you specified in the ItemName
parameter of that method.

See Also AppendContextMenu method

ContextMenuDisplaying event

236 ContextMenu_Select
ClearBasic Control Reference
 Grid control

event DblClick

Syntax Sub YourGrid_DblClick

Applies To Grid

Description The DblClick event occurs when the user double clicks on the grid control. When
the user double-clicks a grid, the following events occur in order:
■ A Click event for the grid
■ A DblClick event for the grid
■ A Click event for the default button on the form.

DblClick 237
ClearBasic Control Reference
 Grid control

event DoAdhocQuery

Syntax Sub YourGrid_DoAdhocQuery

Applies To Grid

Description The DoAdhocQuery event notifies your grid control when the user wants to perform
a query using the information in the adhoc query row of the grid control. This event
only occurs if the grid is associated with a Select CBX control displaying the adhoc
query row. The user triggers the generation of this event by pressing the Enter key
when the cell focus is on a cell in the adhoc query row.

NOTE: The Find button associated with a Select CBX control does not trigger this event.

In your DoAdhocQuery event handler, you must use the information in the adhoc
query row of the list to perform the query. Call the GetAdhocRowValues method of
the corresponding Select CBX control to retrieve the values in the cells of the adhoc
query row.

See Also AdhocCellChanged event

GetAdhocRow method (Select CBX control)
BulkRetrieve object in the ClearBasic Object Reference

238 DoAdhocQuery
ClearBasic Control Reference
 Grid control

event NewRow

Syntax Sub YourGrid_NewRow

Applies To Grid (editable only)

Description The NewRow event notifies your application when the user wants to add a new row to
the grid. The user creates new rows by pressing the Insert key.

In your NewRow event handler, create a new record object and fill it with default
information appropriate for the record or view displayed by the grid. To add the
record object to the grid, use the AppendItem method.

NOTE: If the grid’s AppendRows property is set to False, the grid does not send NewRow
events. To set the value for the AppendRows property, use the User Interface Editor.

Adding a new row does not affect the contents of the grid’s Dirty property unless
you call the SetNewRowIndicator method. If you modify one or more cells, you can
mark the grid as dirty and thus force the grid to save the new row, even if the user has
not entered any data.

This property is available only for grids whose Editable property has been set to Yes
in the User Interface Editor.

See Also GetChoiceListDefault method

SetCellText method
SetNewRowIndicator method

NewRow 239
ClearBasic Control Reference
 Grid control

event Refresh

Syntax Sub YourGrid_Refresh

Applies To Grid

Description The Refresh event notifies your application that the contents of the grid have
changed. The grid sends this event every time the grid is filled with a new set of
records or when you call the Refresh, AppendItem, or ReplaceItem of the grid.

In your Refresh event handler, you can update the read-only status of the newly
loaded records and perform any other necessary cleanup. Use the SetEditStates
method to set the read-only status of a group of cells and rows in one operation.

The Select CBX control uses paging to fill its associated grid control with the next set
of records returned by a query. The grid sends this event each time a new page is
loaded.

See Also AppendItem method

ReplaceItem method
SetCellReadOnly method
SetEditStates method
SetRowReadOnly method
Refresh method (Control object)

240 Refresh
ClearBasic Control Reference
 Grid control

event RowChanged

Syntax Sub YourGrid_RowChanged

Applies To Grid (editable only)

Description The RowChanged event notifies your application that one or more cells in a row have
changed. The grid sends this event when the user selects a different row or when you
call the SaveAnyChanges method from your ClearBasic code. Use this event to save
any pending changes before the user begins working on a different row. The grid does
not send this event if the cells in the row have not changed.

In your RowChanged event handler, save the contents of the modified row to the
database. The grid control maintains changes to the row in the attached contextual
object. When the user selects a cell in a different row, save the changes to the database
before allowing the user to modify the new row.

If the PromptOnSave property of the grid control is set to True, your RowChanged
event handler should prompt the user with a confirmation dialog.

In addition to saving the changes to the database, you can use the RowChanged event
to perform additional validation on the row. Use this technique to supplement the
validation you perform in your CellChanged event handler. This technique is useful
when the value in one cell depends on the value in another cell and you want to wait
until the user has finished editing all of the dependent cells.

Call the GetChangedRow method to determine which of the row’s cells changed and
what their new values are. To abort all of the changes made to the row and restore the
original cell values, call the AbortRowChange method.

This property is available only for grids whose Editable property has been set to Yes
in the User Interface Editor.

Example The following example gets the changed record and saves it to the database using a
BulkSave object.
Sub GridCtl_RowChanged
dim blkSave as New BulkSave
dim recordList as List
dim changedRec as Record
dim rowIndex as Integer
dim cols as List
dim values as List
dim promptRet as Long

GridCtl.GetChangedRow rowIndex, cols, values

' Verify that the row is valid.

' Check to see if the user should be prompted

If GridCtl.PromptOnSave = True Then
promptRet = App.MsgBox “Save changes to the row?”, _

RowChanged 241
ClearBasic Control Reference
 Grid control

cbSaveDiscardCancel
Select Case (whichBtn)
Case cbIDSave
' Save changes to the database
Case cbIdDiscard
' Discard changes
GridCtl.UndoRowChanges
Exit Sub
Case cbIdCancel
' Abort the procedure
GridCtl.AbortRowChange cbAbortUndo, ““, ““
Exit Sub
Case Else
' Error. No other buttons should be
' available.
End Select
End If
set recordList = Cobj_GridCtl.Contents
set changedRec = _
Cobj_GridCtl.GetRecordByIndex rowIndex

blkSave.UpdateRecord changedRec
blkSave.Save
End Sub

See Also AbortRowChange method

GetChangedRow method
SaveAnyChanges method
UndoRowChanges method
PromptOnSave property
CellChanged event

242 RowChanged
ClearBasic Control Reference
 Grid control

event SortColumn

Syntax Sub YourGrid_SortColumn (SortOrder)

Applies To Grid

Description The SortColumn event notifies your grid control that the user wants to sort its rows.
You must use the currently selected columns to determine the sort order for the rows.
The SortOrder parameter specifies whether you should sort the rows in ascending or
descending order. This event occurs only if the grid is associated with a Select CBX
control.

In your SortColumn event handler, use the information in the currently selected
columns to sort the rows. Typically, you do this by repeating the previous query but
applying the new sort criteria to the query. When executed, the query returns the
records in the new sort order.

NOTE: Due to paging restrictions, the records in the contextual object may be only a portion
of the records in the entire grid.

You can get the list of selected columns by calling the GetSelectedColumns
method. If more than one column is selected, sort the rows based on the left-to-right
order of the columns. That is, use the data in the left-most column to perform the
primary sort and use data in subsequent columns to perform secondary or tertiary
sorts as needed.

Parameters This event receives the following parameter:

Parameter Type Description

SortOrder Long This parameter contains one of the following values:

Constant Description
cbAscending Sort the items in ascending order.
cbDescending Sort the items in descending order.

See Also GetSelectedColumns method

Sort method (ContextualObject object in the ClearBasic Object Reference)

SortColumn 243
ClearBasic Control Reference
 Grid control

244 SortColumn
ClearBasic Control Reference
 Label control

Description The label control displays a static string of text on a form. You can use control to
identify other controls that do not have their own built-in labels.

In the User Interface Editor, you can specify a fixed string of text for the label control
or link the control to a source contextual object. Linking the control to a contextual
object causes the control to receive automatic updates whenever the data in the
contextual object changes.

In addition to specifying fixed text strings, you can use the label control to implement
Hypertext links. When clicked, the label control opens the file that you specified in the
control’s property sheet at design time. You cannot modify the destination of a
Hypertext link at runtime using this control.

Referring to Label You cannot create control objects using ClearBasic code. You must associate controls
Controls with a form, frame, or tab using the User Interface Editor. When the form, frame, or
tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the label
control called YourLabelControl:
Dim YourControl As Control
Set YourControl = YourLabelControl

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ Refresh method [C]

ClearBasic Control Reference

 Label control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ BackColor property
■ Caption property
■ ControlType property [C]
■ Enabled property [C]
■ ForeColor property
■ Height property [C]
■ Id property [C]
■ Left property [C]
■ Name property [C]
■ Parent property
■ Tag property
■ Top property [C]
■ Visible property [C]
■ Width property [C]

Events This object supports the following event:

■ Click event

246
ClearBasic Control Reference
 Label control

property BackColor

Syntax YourControl.BackColor = "ColorLabel"

ControlColor = YourControl.BackColor

Applies To Label

Description The BackColor property allows you to set the background color of a control. You can
set this property directly for the control, or indirectly by setting the property on the
contextual object that is linked to the control.

Before using this property, you must establish a color scheme using either the
CreateColorScheme or SetColorScheme method.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the label control may be colored on
UNIX, but not on the Macintosh.

This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The
label must be in the color scheme that is currently in effect for the form
in which you are performing color operations. (See CreateColorScheme
and SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the text box label and the textbox foreground text are assigned the
same color, red, and the background color for the text box label is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", _
"Important", "Weak"

ColorList1.AppendItem "red", _

BackColor 247
ClearBasic Control Reference
 Label control

"cyan", "blue"

App.CreateColorScheme "Form2020", _
LabelList1,ColorList1
End Sub

Sub Form_Load
App.SetColorScheme "Form2020"

TextBox1.ForeColor = "Urgent"
TextBox1_Label.ForeColor = "Urgent"
TextBox1_Label.BackColor = "Important"
End Sub

See Also ForeColor property

CreateColorScheme method (App object in the ClearBasic Object Reference)
SetColorScheme method (App object in the ClearBasic Object Reference)

248 BackColor
ClearBasic Control Reference
 Label control

property Caption

Syntax YourControl.Caption = "CaptionTextString"

ControlCaption = YourControl.Caption

Applies To Label

Description Use the Caption property to get or set the text label for the control. If you want to
assign a new value to this property at runtime, make sure you set the Autosizable
property of the control to Yes in the User Interface Editor.

The Caption property works on a control whether you assigned it a fixed text label
or whether you linked the control to a source contextual object. If the control is linked
to a source contextual object, modifying this property also modifies the value in the
specified field of that contextual object.

IMPORTANT: On some platforms, your caption changes may persist when you display or
redisplay the form. If this happens, set the caption in the Form_Load event procedure for that
form. Also, if the control supports labeling through use of a source contextual object, and you
make this source link at design time, you can use the Fill method on the contextual object to
get the caption to display properly.

One way to use the caption property is to change the caption on a control during the
execution of some procedure to indicate that the procedure is executing.

Settings This property accepts the following settings:

Setting Description
CaptionTextString Specify the text string.
The default caption is the string defined for the form or control at
design time using the User Interface Editor.

Return Values In read mode, this property returns the title of the control or form. If the control is
source linked to a contextual object field, the value of the field is returned.

Caption 249
ClearBasic Control Reference
 Label control

property ForeColor

Syntax YourControl.ForeColor = "ColorLabel"

ControlColor = YourControl.ForeColor

Applies To Label

Description The ForeColor property allows you to set the color of the control label text. You can
set this property directly for the control, or indirectly by setting the property on the
contextual object that is linked to the control.

Before using this property, you must establish a color scheme using either the
CreateColorScheme or SetColorScheme method.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored on UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The
label must be in the color scheme that is currently in effect for the
form in which you are performing color operations. (See
CreateColorScheme and SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the text box label and the textbox foreground text are assigned the
same color, red, and the background color for the text box label is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", "Important",

"Weak"

250 ForeColor
ClearBasic Control Reference
 Label control

ColorList1.AppendItem "red", "cyan", "blue"

App.CreateColorScheme"Form2020",
LabelList1,ColorList1

End Sub

Sub Form_Load
App.SetColorScheme "Form2020"

TextBox1.ForeColor = "Urgent"
TextBox1_Label.ForeColor = "Urgent"
TextBox1_Label.BackColor = "Important"
End Sub

See Also BackColor property

CreateColorScheme method (App object in the ClearBasic Object Reference)
SetColorScheme method (App object in the ClearBasic Object Reference)

ForeColor 251
ClearBasic Control Reference
 Label control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To Label

Description The Parent property contains the form object that owns the label control. You can
use this property to retrieve a reference to the form object containing the button.

This property is read-only.

252 Parent
ClearBasic Control Reference
 Label control

property Tag

Syntax YourControl.Tag = "YourStringHere"

ControlTag = YourControl.Tag

Applies To Label

Description The Tag property contains a custom string that you assign at runtime. You can use
this string to identify the command button control internally to your application. You
can also use this property to store extra information about the control.

Tag 253
ClearBasic Control Reference
 Label control

event Click

Syntax Sub YourControl_Click

Applies To Label

Description The Click event reports a click on a Hypertext-enabled label control. You can use this
event to perform any appropriate action for the label, including displaying a web
page.

254 Click
ClearBasic Control Reference
 List Box control

Description The list box control displays a read-only list from which the user may make a
selection. The functionality of this control is similar to the dropdown list box control,
but requires more display space since it displays several list items at once. (The
dropdown list box displays only one item.) You should use this control if you don’t
expect the user to know what the possible selections are without seeing the list.

You can use the methods of the list box control to modify the contents of the list at
runtime. You can add new items to the list or remove existing items. You can move
existing items up or down in the list. You can also get and set the current selection for
the list.

This control does not include a label automatically. To add a label, create a label
control and place it next to this control.

Referring to List Box You cannot create control objects using ClearBasic code. You must associate controls
Controls with a form, frame, or tab using the User Interface Editor. When the form, frame, or
tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the list box
control called YourLIstBoxControl:
Dim YourControl As Control
Set YourControl = YourListBoxControl

Source The source contextual object of a list box control stores the list of items to be displayed
in the control. Each item in the list is a string containing the text to display for a single
item. You can specify the items for this list at design time using the User Interface
Editor or at runtime using the methods of the list box control.

Destination The destination contextual object of a list box control stores the list item that is
currently selected. This contextual object must specify a string data type.

ClearBasic Control Reference

 List Box control

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ AppendItem method
■ Clear method
■ Contains method
■ Down method
■ GetList method
■ GetSelected method
■ Refresh method [C]
■ RemoveByItem method
■ RemoveItem method
■ RemoveSelected method
■ ReplaceItem method
■ SelectedIndexes method
■ SelectedList method
■ SetFocus method [C]
■ SetSelected method
■ UnSelect method
■ Up method

256
ClearBasic Control Reference
 List Box control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ DataChanged property
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ ListCount property
■ ListIndex property
■ MultiSelect property
■ Name property [C]
■ NewIndex property
■ Parent property
■ SelCount property
■ Selected property
■ Sorted property
■ Tag property
■ Top property [C]
■ TopIndex property
■ UserData property
■ Value property
■ Visible property [C]
■ Width property [C]

Events This object supports the following events. Events marked with a [C] are documented
with the Control object.
■ Click event
■ DblClick event
■ GotFocus event [C]
■ LostFocus event [C]

257
ClearBasic Control Reference
 List Box control

method AppendItem

Syntax YourControl.AppendItem ItemToAppend

YourControl.AppendItem ListOfItems

Applies To List Box

Description The AppendItem method appends a single item or list of items to the control. The
control must have a source contextual object to store the items added by this method.
This method automatically updates the items in the source contextual object.

You can use this method in a Form_Load procedure to initialize the control. If you
had not previously initialized the control’s source contextual object, you must do so
by calling its Fill method before calling this method.

This method updates the value in the NewIndex property to reflect the index of the
newly added item. When you add a list of items, the NewIndex property reflects the
index of the first item in the list.

Parameters This method accepts the following parameters:

Parameters Type Values

ItemToAppend String Specify a string with the item text to add to the list.
ListOfItems List Specify a List object containing one or more strings. Each
string contains the text for a single item.

Return Values None

Example In the following example, NewCourse is added to the list box ListBox1, then the list box
is refreshed to display the added item.
Sub AppendToControl
ListBox1.AppendItem "NewCourse"
ListBox1.Refresh
End Sub

See Also Contains method

RemoveItem method
NewIndex property

258 AppendItem
ClearBasic Control Reference
 List Box control

method Clear

Syntax YourControl.Clear

Applies To List Box

Description The Clear method removes all of the items from the list box control and from the
control’s source contextual object. This method also resets the value of the NewIndex
property to -1.

After calling this method, call the form’s Refresh method to update the control’s
display.

Parameters None

Return Values None

See Also NewIndex property

Refresh method (Control object)
Empty method (ContextualObject object in the ClearBasic Object Reference)

Clear 259
ClearBasic Control Reference
 List Box control

method Contains

Syntax YourBoolean = YourControl.Contains (ItemToFind)

Applies To List Box

Description The Contains method returns a boolean value indicating whether the specified item
is in the list.

Parameters This method accepts the following parameter:

Parameter Type Description

ItemToFind String Specify the string you want to search for in the control’s list of
items.

Return Values Returns True if the item is already in the control, or False if the item is not in the
control.

Example The following test routine shows one use of the Contains method. In the example,
Contains is used to verify that an item has been properly added to a control.

Notice that the count of items in the control is taken before the new item is added.
This means that the index of Clover should be equal to the count.
Sub TestSub_Click
Dim I As integer
Dim J As integer

I= ListBox1.ListCount
ListBox1.AppendItem "Clover"
ListBox1.Refresh
J= ListBox1.NewIndex

If (J = I) Then
If ListBox1.Contains("Clover") Then
App.MsgBox "Clover is here!"
Else
App.MsgBox "Clover is not here!"
End If
Else
App.MsgBox "Item not added properly"
End If
End Sub

260 Contains
ClearBasic Control Reference
 List Box control

method Down

Syntax YourControl.Down

Applies To List Box

Description The Down method moves the currently selected item down one position in the
control’s list. Any displaced items are moved up to make room for the item. If the
selected item is already at the bottom of the list, it remains there.

If no item is selected, this method does nothing.

Parameters None

Return Values None

Example In the following example, a loop loads five strings into an empty list box. The strings
are sequenced Item 1 to Item 5, and Item 2 is moved down. At this point, the index of
Item 2 should become 2 and the index of Item 3 should become 1. GetList is used to
check this, returning the item at index 1 in the control. If Item 3 is at that index, the
appropriate notification is stored in Logstr.
Sub DownTest
Dim Hold1 As string
Dim Logstr As string

ListBox1.Clear

For i = 1 to 5
ListBox1.AppendItem "item"+Str$(i)
ListBox1.Refresh
Next i

ListBox1.SetSelected "item 2"

ListBox1.Down 1
ListBox1.Refresh

Hold1 = ListBox1.GetList(1)

If Hold1 = "item 3" Then

Logstr = "Second item moved one position _
down"
Else
Logstr = "Second item did not move down"
End If
End Sub

See Also Up method

Down 261
ClearBasic Control Reference
 List Box control

method GetList

Syntax Set YourList = YourControl.GetList

YourRetVar = YourControl.GetList (Index)

Applies To List Box

Description The GetList method returns the items currently in the list box. If you specify an
index of an item in the list, this method returns that item. If you do not specify any
parameters, this method returns the entire list of items.

The source contextual object associated with the control must be initialized before
calling this method.

Parameters This method accepts the following parameter:

Parameter Type Description

Index Long This parameter is optional. You can specify the index of the item
you want returned.
If you don’t specify an index, the entire list is returned.

Return Values Returns a List object containing zero or more strings. Each string in the list
corresponds to an item in the list box control.

If the Index parameter was specified, this method returns a String containing the text
of the desired item.

Example In the following example, a loop loads five strings into an empty list box. The strings
are sequenced Item 1 to Item 5, and Item 2 is moved down. At this point, the index of
Item 2 should become 2 and the index of Item 3 should become 1. GetList is used to
check this, returning the item at index 1 in the control. If Item 3 is at that index, the
appropriate notification is stored in Logstr.
Sub DownTest
Dim Hold1 As string
Dim Logstr As string
ListBox1.Clear

For i = 1 to 5
ListBox1.AppendItem "item"+Str$(i)
ListBox1.Refresh
Next i

ListBox1.SetSelected "item 2"

ListBox1.Down 1
ListBox1.Refresh

Hold1 = ListBox1.GetList(1)

262 GetList
ClearBasic Control Reference
 List Box control

If Hold1 = "item 3" Then

Logstr = "Second item moved one position _
down"
Else
Logstr = "Second item did not move down"
End If
End Sub

See Also GetSelected method

GetList 263
ClearBasic Control Reference
 List Box control

method GetSelected

Syntax YourBool = YourControl.GetSelected(SelectedItem)

If YourControl.GetSelected(SelectedItem) Then
...

Applies To List Box

Description The GetSelected method returns the currently selected item in the list box. The text
for the item is returned in the SelectedItem parameter, which you must provide
when you call the method. The method returns a boolean value indicating whether or
not an item is selected.

Parameters This method accepts the following parameter:

Parameter Type Description

SelectedItem String Specify the name of a String variable. The selected item is
placed into that variable.

Return Values Returns True if an item was selected, otherwise False.

See Also SelectedIndexes method

SelectedList method
SetSelected method

264 GetSelected
ClearBasic Control Reference
 List Box control

method RemoveByItem

Syntax Set BadItems = YourControl.RemoveByItem ItemToRemove

Set BadItems = YourControl.RemoveByItem ListOfItems

Applies To List Box

Description The RemoveByItem method removes one or more items from the list box. After
removing the items, this method sets the value in the NewIndex property to -1. You
can use this method to selectively remove items from the list box control.

As the method processes the list of items, it keeps track of those items that were not in
the control’s list. Upon completion, the method returns the list of missing items to
you. Duplicate entries are considered missing items and are therefore returned in this
list.

Parameters This method accepts the following parameters:

Parameter Type Description

ItemToRemove String Specify a name of the item you want to remove.
ListOfItems List Specify a list of String objects. Each string in the list
contains the name of an item you want to remove.

Return Values Returns a List object containing zero or more strings. Each string contains the name
of an item that was not in the control’s list.

See Also RemoveItem method

ReplaceItem method
NewIndex property

RemoveByItem 265
ClearBasic Control Reference
 List Box control

method RemoveItem

Syntax YourControl.RemoveItem Index

Applies To List Box

Description The RemoveItem method removes the specified item from the list box. If the
specified item is currently selected, this method clears the selection before removing
the item. After removing the item, this method sets the value in the NewIndex
property to -1

Parameters This method accepts the following parameters:

Parameter Type Description

Index Long Specify the index of the item to remove. This index is 0 based, that
is, the first item is at index 0, the second at index 1, and so on.
If the index you specify is less than 0 or greater than the number of
items in the control, this method generates an error.

Return Values None

See Also AppendItem method

RemoveByItem method
NewIndex property

266 RemoveItem
ClearBasic Control Reference
 List Box control

method RemoveSelected

Syntax RetInteger = YourControl.RemoveSelected

Applies To List Box

Description The RemoveSelected method removes the currently selected items from the list box
control. This method clears the current selection and sets the value in the NewIndex
property to -1.

Parameters None

Return Values Returns a Long integer with the number of items remaining in the control after the
removal of the selected items.

Example The following code snippet shows one application of this method. Selected items are
removed from MyControl and the number of items remaining in the control are
returned to Count. If no more items are left in the control, the REMOVE button is
disabled.
Count = MyControl.RemoveSelected
If Count = 0 Then
REMOVE.Enabled = False
End If

See Also RemoveByItem method

RemoveItem method
ReplaceItem method
NewIndex property

RemoveSelected 267
ClearBasic Control Reference
 List Box control

method ReplaceItem

Syntax YourControl.ReplaceItem ItemToPutIn, Index

Applies To List Box

Description The ReplaceItem method replaces the item at the specified index with the desired
string. This method does not affect the current selection or the value in the NewIndex
property.

Parameters This method accepts the following parameters:

Parameter Type Description

NewItemText String Specify a string containing the replacement text.
Index Long Specify the index of the item to replace. This index is 0 based,
that is, the first item is at index 0, the second at index 1, and
so on.
If the index you specify is less than 0 or greater than the
number of items in the control, this method generates an
error.

Return Values None

See Also AppendItem method

RemoveItem method

268 ReplaceItem
ClearBasic Control Reference
 List Box control

method SelectedIndexes

Syntax Set yourList=YourControl.SelectedIndexes

Applies To List Box

Description The SelectedIndexes method returns a list of indexes corresponding to the

currently selected items. For list box controls, this list can contain at most one item.

This method is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected items from each.

Parameters None

Return Values Returns a List object containing zero or one long integer. The integer is a 0-based
index into the control’s list of items.

See Also GetSelected method

SelectedList method
Selected property

SelectedIndexes 269
ClearBasic Control Reference
 List Box control

method SelectedList

Syntax Set YourRetList = YourControl.SelectedList

Applies To List Box

Description The SelectedList method returns a list containing the currently selected items in
the control. Because list boxes only allow the selection of one item at a time, this list
can contain at most one item.

This method is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected items from each.

Parameters None

Return Values Returns a List object containing zero or more strings. Each string in the list
corresponds to a selected item in the control. If no items are selected, the returned list
is empty.

See Also GetSelected method

RemoveSelected method
SelectedIndexes method

270 SelectedList
ClearBasic Control Reference
 List Box control

method SetSelected

Syntax YourControl.SetSelected ItemToSelect

Applies To List Box

Description The SetSelected method selects the specified item. If there was an existing
selection, this method clears it before selecting the new item.

Only one item at a time may be selected for a list box control. If you specify an item
that does not exist in the control’s list, this method exits without clearing the previous
selection.

Parameters This method accepts the following parameters:

Parameter Type Description

ItemToSelect String Specify the item text corresponding to the item you want to
select. This string is case-sensitive and must match the item
text in the control exactly.

Return Values None

See Also Contains method

GetSelected method
Selected property

SetSelected 271
ClearBasic Control Reference
 List Box control

method UnSelect

Syntax YourControl.Unselect

Applies To List Box

Description The UnSelect method clears the control’s current selection.

Parameters None

Return Values None

See Also SetSelected method

Selected property

272 UnSelect
ClearBasic Control Reference
 List Box control

method Up

Syntax YourControl.Up

Applies To List Box

Description The Up method moves the currently selected item up one position in the control’s list.
Any displaced items are moved down to make room for the item. If the selected item
is already at the beginning of the list, it remains there.

If no item is selected, this method does nothing.

Parameters None

Return Values None

See Also Down method

Up 273
ClearBasic Control Reference
 List Box control

property DataChanged

Syntax RetBoolean = YourControl.DataChanged

YourControl.DataChanged = NewSetting

Applies To List Box

Description The DataChanged property contains a boolean value indicating whether the user
modified the contents of this control. This value only indicates whether modifications
were made by the user; it does not reflect changes made to the control by your
ClearBasic code.

If you modify the control programmatically, you can set this property to reflect your
changes. Set this property to True to indicate you made modifications; otherwise, set it
to False to indicate the control is unchanged.

274 DataChanged
ClearBasic Control Reference
 List Box control

property ListCount

Syntax ItemCount = YourControl.ListCount

Applies To List Box

Description The ListCount property contains a Long integer indicating the total number of
items in the list box control.

This property is read-only.

See Also ListIndex property

ListCount 275
ClearBasic Control Reference
 List Box control

property ListIndex

Syntax SelectedItem = YourControl.ListIndex

Applies To List Box

Description The ListIndex property returns the index of the control’s currently selected item. A
list box control may have at most one item selected. The list box may also not have a
selection.

List indexes are 0-based, that is, the first item is at index 0, the second at index 1, and
so on. As a result, the maximum index is always one less than the total number of
items as stored in the ListCount property.

Example The following procedure illustrates the use of this property.

Sub MyClick_Click
Dim MyRetInt As Integer

MyRetInt = MyListBox.ListIndex

If MyRetInt = -1 Then
App.MsgBox "No Selection"
Else
‘Do this
...
End If
End Sub

See Also ListCount property

276 ListIndex
ClearBasic Control Reference
 List Box control

property MultiSelect

Syntax IsMultiSelect = YourControl.MultiSelect

Applies To List Box

Description The MultiSelect property contains a boolean value indicating whether the list box
supports the selection of multiple items. For list box controls, this property always
contains the value False.

This property is read-only.

MultiSelect 277
ClearBasic Control Reference
 List Box control

property NewIndex

Syntax YourRetInt = YourControl.NewIndex

Applies To List Box

Description The NewIndex property contains a long integer with the index of the most recently
added item. You can pass this index to other methods to modify (or subsequently
remove) the item.

When you add a new item, the AppendItem method updates this property to reflect
the position of any new items. Methods that remove items reset the value in this
property to -1.

This property is read-only.

See Also AppendItem method

Clear method
RemoveByItem method
RemoveItem method
RemoveSelected method
ReplaceItem method

278 NewIndex
ClearBasic Control Reference
 List Box control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To List Box

Description The Parent property contains the form object that owns the control. You can use this
property in to retrieve a reference to the form object containing the list box.

This property is read-only.

Parent 279
ClearBasic Control Reference
 List Box control

property SelCount

Syntax ItemCount = YourControl.SelCount

Applies To List Box

Description The SelCount property contains an integer value indicating the number of currently
selected list items. If no items are selected, this property contains the value 0.

This property is read-only.

280 SelCount
ClearBasic Control Reference
 List Box control

property Selected

Syntax SelectedItem = YourControl.Selected

YourControl.Selected = ItemToSelect

Applies To List Box

Description The Selected property contains the string representing the currently selected item.
List boxes can have at most one item selected. If no item is selected, this property
contains an empty string ("").

This property is read-only.

This property is provided as a convenience for situations where you may want to
iterate through a group of controls and get the selected item from each.

See Also GetSelected method

SelectedIndexes method
SelectedList method

Selected 281
ClearBasic Control Reference
 List Box control

property Sorted

Syntax IsSorted = YourList.Sorted

Applies To List Box

Description The Sorted property contains a boolean value indicating whether the items in the
control’s list are sorted. This property contains the value True if the items in the
control’s source contextual object are sorted, otherwise False.

This property is read-only.

See Also Sort method (ContextualObject object in the ClearBasic Object Reference)

282 Sorted
ClearBasic Control Reference
 List Box control

property Tag

Syntax YourControl.Tag = "YourStringHere"

ControlTag = YourControl.Tag

Applies To List Box

Description The Tag property contains a custom string that you assign at runtime. You can use
this string to identify the control internally to your application. You can also use this
property to store extra information about the control.

Tag 283
ClearBasic Control Reference
 List Box control

property TopIndex

Syntax YourControl.TopIndex = Index

Index = YourControl.TopIndex

Applies To List Box

Description The TopIndex property contains the index of the first visible item in the list box. This
index is one-based, that is, the first item is at index 1, the second at index 2, and so on.
This property is readable and writable.

The item represented by the index is not necessarily the first item in the list, but it is
the first item scrolled into view in the list box control. If the list box contains a selected
item, the value in this property is 0.

If you assign a new value to this property, the control scrolls the item into view. The
position of other items in the list does not change; only their visibility in the list box
control changes. If you specify an index that is less than 1 or greater than the number
of items in the control, this method generates an error.

The value in this property changes when you add or remove list items, set or clear the
selection, or update the control’s appearance. This property is also modified by
changes to the contents of the control’s destination contextual object. For example,
this property is affected by the AppendItem, SetSelected, and Refresh methods
of the list box control and by the Fill method of a ContextualObject.

284 TopIndex
ClearBasic Control Reference
 List Box control

property UserData

Syntax ControlData = YourControl.UserData

YourControl.UserData = ControlData

Applies To List Box

Description The UserData property contains the string associated with the currently selected
item. At design time, you can associate a string with each item of a dropdown list. You
can assign individual strings for each item in the list or omit the string as appropriate.
This string may contain a database path or any other type of value that you designate.

This property is read-only. For information on associating user data with dropdown
list box items, see the User Interface Editor Guide.

UserData 285
ClearBasic Control Reference
 List Box control

property Value

Syntax ControlValue = YourControl.Value

YourControl.Value = ControlValue

Applies To List Box

Description The Value property contains a string with the item text for the currently selected
item. You can get this property to retrieve the item text for the selected item.

If you assign a value to this property, you must specify a string the name of the item
you want to select. This string is case-sensitive and must match the name of an item in
the list exactly. The string you specify is stored in the control’s destination contextual
object.

NOTE: It is possible to update the contents of the control’s destination contextual object
without changing the value in this property. Before getting this property, you can call the
Refresh method to ensure the control’s caches are up-to-date.

286 Value
ClearBasic Control Reference
 List Box control

event Click

Syntax Sub YourControl_Click

Applies To List Box

Description The Click event handler for your list box is called when the user presses and releases
the mouse button over the control. A Click event usually indicates the selection of an
item from the control’s list. However, this event does not distinguish between the
selection of a new item or of the same item.

You can use the Click event handler to perform other actions based on the selection
of an item.

Click 287
ClearBasic Control Reference
 List Box control

event DblClick

Syntax Sub YourControl_DblClick

Applies To List Box

Description The DblClick event handler for your list box is called when the user double-clicks
the mouse button over the same item in the list box. This event is preceded by a
Click event.

See Also Click event

288 DblClick
ClearBasic Control Reference
 Multiline Text Box control

Description The multiline text box control provides the user with an area for entering multiple
lines of text. This control is similar to the text box control, except for the way it
processes KeyPress events. When the user presses the Enter key in a multiline text
box, the control automatically adds a line termination character to the end of the
current line and moves the cursor to the next line. Other controls interpret the Enter
key as a button click in the form’s default button.

This control does not include a label automatically. To add a label, create a label
control and place it next to this control.

Context-Sensitive This control supports the display of a context-sensitive menu. The control
Menu Support automatically provides several control-related menu items to allow the user to cut,
copy, and paste text. You may add additional menu items using the methods of this
control.

If you add context-sensitive menu items to a control, you must provide an event
handler to respond to the selection of your menu items. The ContextMenu_Select
event handler lets you handle the selection of all your context-sensitive menu items.
You may also implement a ContextMenuDisplaying event handler to modify the
state of your menu items immediately before the menu is displayed.

Referring to You cannot create control objects using ClearBasic code. You must associate controls
Multiline Text Box with a form, frame, or tab using the User Interface Editor. When the form, frame, or
Controls tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the multiline
text box control called YourMTextBoxControl:
Dim YourControl As Control
Set YourControl = YourMTextBoxControl

Source This control does not support the use of a source contextual object.

Destination The destination contextual object of a multiline text box control stores the text entered
either by the user or by your ClearBasic code. This contextual object must specify a
string data type.

ClearBasic Control Reference

 Multiline Text Box control

Methods This object supports the following methods. Methods marked with [C} are
documented with the Control object.
■ AppendContextMenu method
■ ClearContextMenu method
■ SetContextMenuEnabled method
■ SetContextMenuVisible method
■ Refresh method [C]
■ SetFocus method [C]

Properties This object supports the following properties. Properties marked with [C} are
documented with the Control object.
■ BackColor property
■ ControlType property [C]
■ Enabled property [C]
■ ForeColor property
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ MaxLength property
■ MultiLine property
■ Name property [C]
■ Parent property
■ Required property
■ RequiredColor property
■ SelLength property
■ SelStart property
■ SelText property
■ Tag property
■ Text property
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

290
ClearBasic Control Reference
 Multiline Text Box control

Events This object supports the following events. Events marked with [C} are documented
with the Control object.
■ Click event
■ ContextMenuDisplaying event
■ ContextMenu_Select event
■ GotFocus event [C]
■ KeyPress event
■ LostFocus event [C]

Deprecated Events The following event has changed. The old event is still supported for compatibility
but its use is discouraged. Use the new event instead.

Old Event Name New Event Name

<MenuItem> event ContextMenu_Select event

291
ClearBasic Control Reference
 Multiline Text Box control

method AppendContextMenu

Syntax YourControl.AppendContextMenu ItemName, ItemLabel, AppMenuName,

Separator

Applies To Multiline Text Box

Description The AppendContextMenu method adds a new menu item to the end of the control’s
context-sensitive menu. You can use this method to supplement the menu items
specified using the User Interface Editor.

In addition to adding menu items, you can use this method to add a separator after an
existing menu item. To add a separator, specify True for the Separator parameter.

The menu items you add using this method are enabled and visible initially. To
change the appearance of an item, call the SetContextMenuEnabled or
SetContextMenuVisible method. You can also add code to a
ContextMenuDisplaying event handler to update the appearance of menu items
dynamically.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify an identification string for the menu item. Your
application uses this string to identify the menu item when
calling menu-related methods. This name does not have to
be the same as the menu item’s label.
ItemLabel String Specify the menu-item label. This is the string the user sees
in the menu.
AppMenuName String Specify the menu name associated with the context-sensitive
menu, if any.
Specify a value for this parameter only if the menu item is
already associated with one of the application menus.
Specifying the application menu name prevents the creation
of duplicate menu items.
If the menu item is unique, specify an empty string ("") for
this parameter.
Separator Boolean Specify True if the item should be a separator, otherwise
False. If you specify True for this parameter, the ItemLabel
and AppMenuName parameters are ignored.

Return Values None

292 AppendContextMenu
ClearBasic Control Reference
 Multiline Text Box control

Example The following example adds two new items to the context-sensitive menu associated
with a multiline text box control. The new items allow the user to select all of the text
in the control and to deselect whatever is currently selected.
Sub Form_Load
Dim numSelItems As Integer
Dim numTotalItems As Integer

' Add two new menu items for selecting

' everything and nothing.
TextBoxCtl.AppendContextMenu "cntxSelectAll", _
"Select All", "", FALSE
TextBoxCtl.AppendContextMenu _
"cntxSelectNone", "Select None", "", _
FALSE

End Sub

See Also SetContextMenuEnabled method

SetContextMenuVisible method
ContextMenuDisplaying event

AppendContextMenu 293
ClearBasic Control Reference
 Multiline Text Box control

method ClearContextMenu

Syntax YourControl.ClearContextMenu

Applies To Multiline Text Box

Description The ClearContextMenu method removes custom menu items from the control’s
context-sensitive menu. This method removes only menu items that were added
using the AppendContextMenu method of the control. This method does not remove
application-specific menu items or menu items added in the User Interface Editor.

Parameters None

Return Values None

See Also AppendContextMenu method

294 ClearContextMenu
ClearBasic Control Reference
 Multiline Text Box control

method SetContextMenuEnabled

Syntax YourControl.SetContextMenuEnabled ItemName, Enabled

Applies To Multiline Text Box

Description The SetContextMenuEnabled method enables or disables a menu item in a

context-sensitive menu. Disabled menu items are displayed in the menu but cannot be
selected by the user. Enabled menu items can be selected and generate an appropriate
menu item event.

You can call this method from a ContextMenuDisplaying event handler to adjust
the appearance of the items in the menu. The enabled state of the item does not
change until you call this method again.

You may use this method to modify both permanent menu items and those added
using the AppendContextMenu method. To set the default enabled state of a
permanent menu item, you must modify the item’s entry in the Clarify User Interface
Editor.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify the identification string of the desired menu item.
This is the string you assigned to the item in the Clarify User
Interface Editor or using the AppendContextMenu method.
Enabled Boolean Specify True to enable the menu item; specify False to disable
it.

Return Values None

See Also AppendContextMenu method

SetContextMenuVisible method
ContextMenuDisplaying event
ContextMenu_Select event

SetContextMenuEnabled 295
ClearBasic Control Reference
 Multiline Text Box control

method SetContextMenuVisible

Syntax YourControl.SetContextMenuVisible ItemName, Visible

Applies To Multiline Text Box

Description The SetContextMenuVisible method sets the visibility of a menu item in a

context-sensitive menu. The visibility of a menu item determines whether or not the
item appears in the menu. Calling this method with the Visible parameter set to False
removes the item from the menu. Specifying True for the Visible parameter displays
the item to its original place in the menu.

You can call this method from a ContextMenuDisplaying event handler to adjust
the appearance of the items in the menu. The visible state of the item does not change
until you call this method again.

You may use this method to modify both permanent menu items and those added
using the AppendContextMenu method. To set the default visible state of a
permanent menu item, you must modify the item’s entry in the Clarify User Interface
Editor.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify the identification string of the desired menu item. This
is the string you assigned to the item in the Clarify User
Interface Editor or using the AppendContextMenu method.
Visible Boolean Specify True to make the menu item visible; specify False to
hide it.

Return Values None

See Also AppendContextMenu method

SetContextMenuEnabled method
ContextMenuDisplaying event

296 SetContextMenuVisible
ClearBasic Control Reference
 Multiline Text Box control

property BackColor

Syntax YourControl.BackColor = "ColorLabel"

ControlColor = YourControl.BackColor

Applies To Multiline Text Box

Description The BackColor property allows you to set the background color of a control. You can
set this property directly for the control, or indirectly by setting the property on the
contextual object that is linked to the control.

Before using this property, you must establish a color scheme using either the
CreateColorScheme or SetColorScheme method.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored in UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The label
must be in the color scheme that is currently in effect for the form in
which you are performing color operations. (See CreateColorScheme
and SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the foreground of the label and the multiline text box are assigned the
same color: red; the background color for the multiline text box is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", _
"Important", "Weak"
ColorList1.AppendItem "red", _

BackColor 297
ClearBasic Control Reference
 Multiline Text Box control

"cyan", "blue"

App.CreateColorScheme "Form2020", _
LabelList1,ColorList1
End Sub

Sub Form_Load
App.SetColorScheme "Form2020"

TextBox1_Label.ForeColor = "Urgent"
TextBox1.ForeColor = "Urgent"
TextBox1.BackColor = "Important"
End Sub

See Also CreateColorScheme method (App object in the ClearBasic Object Reference)
SetColorScheme method (App object in the ClearBasic Object Reference)

298 BackColor
ClearBasic Control Reference
 Multiline Text Box control

property ForeColor

Syntax YourControl.ForeColor = "ColorLabel"

ControlColor = YourControl.ForeColor

Applies To Multiline Text Box

Description The ForeColor property allows you to set the color of the control label text. You can
set this property directly for the control, or indirectly by setting the property on the
contextual object that is linked to the control.

Before using this property, you must establish a color scheme using either the
CreateColorScheme or SetColorScheme method.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored in UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The label
must be in the color scheme that is currently in effect for the form in
which you are performing color operations. (See CreateColorScheme
and SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the foreground of the label and the multiline text box are assigned the
same color: red; the background color for the multiline text box is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", "Important",

"Weak"

ForeColor 299
ClearBasic Control Reference
 Multiline Text Box control

ColorList1.AppendItem "red", "cyan", "blue"

App.CreateColorScheme"Form2020",
LabelList1,ColorList1

End Sub

Sub Form_Load
App.SetColorScheme "Form2020"

TextBox1_Label.ForeColor = "Urgent"
TextBox1.ForeColor = "Urgent"
TextBox1.BackColor = "Important"
End Sub

See Also CreateColorScheme method (App object in the ClearBasic Object Reference)
SetColorScheme method (App object in the ClearBasic Object Reference)

300 ForeColor
ClearBasic Control Reference
 Multiline Text Box control

property MaxLength

Syntax YourControl.MaxLength = Length

Length = YourControl.MaxLength

Applies To Multiline Text Box

Description The MaxLength property contains a long integer indicating the maximum number of
bytes that may be displayed by the control. The value of this integer must be between
0 and 32000. (For UNIX-only implementations, this value may be between 0 and
64000.) This property is readable and writable.

You can use this property to obtain the initial design-time value specified in the User
Interface Editor. You may also change this value by assigning a new value to the
property. Any value you specify remains in effect until you change the property again
or until the current session ends.

MaxLength 301
ClearBasic Control Reference
 Multiline Text Box control

property MultiLine

Syntax IsMultiLine = YourControl.MultiLine

Applies To Multiline Text Box

Description The MultiLine property contains a boolean indicating whether the control is a
multiline control. For multiline text boxes, this property always contains the value
True.

This property is read-only.

See Also MaxLength property

302 MultiLine
ClearBasic Control Reference
 Multiline Text Box control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To Multiline Text Box

Description The Parent property contains the form object that owns the control. You can use this
property in to retrieve a reference to the form object containing the control.

This property is read-only.

Parent 303
ClearBasic Control Reference
 Multiline Text Box control

property Required

Syntax RetBoolean = YourControl.Required

Applies To Multiline Text Box

Description The Required property contains a boolean value indicating whether or not the user
must enter a value in the text box before dismissing the form. This property contains
the value True if the control is required, otherwise False.

This property is read-only. You must set this property at design time using the User
Interface Editor.

See Also RequiredColor property

304 Required
ClearBasic Control Reference
 Multiline Text Box control

property RequiredColor

Syntax YourControl.RequiredColor = "ColorLabel"

ColorLabel = YourControl.RequiredColor

Applies To Multiline Text Box

Description The RequiredColor property contains a color label indicating the background color
of a required textbox. Before setting this property, you must use
CreateColorScheme and SetColorScheme to create and set a color scheme for
the form in which the textbox is located.

This property is readable and writable. This property only applies to multiline text
box controls whose Required property is set to True. If the Required property is not
set to True, this property is ignored.

See Also BackColor property

ForeColor property
Required property
CreateColorScheme method (App object in the ClearBasic Object Reference)
SetColorScheme method (App object in the ClearBasic Object Reference)

RequiredColor 305
ClearBasic Control Reference
 Multiline Text Box control

property SelLength

Syntax YourControl.SelLength = YourLong

YourLong = YourControl.SelLength

Applies To Multiline Text Box

Description The SelLength property contains a long integer value indicating the number of
characters in the current selection. This property is readable and writable.

Changing the value in this property changes the length of the current selection. You
can use this property in combination with the SelStart property to select text in the
control. When selecting text that spans multiple lines, newline characters count as 1
character.

See Also SelStart property

SelText property

306 SelLength
ClearBasic Control Reference
 Multiline Text Box control

property SelStart

Syntax YourControl.SelStart = Index

Index = YourControl.SelStart

Applies To Multiline Text Box

Description The SelStart property contains a long integer value indicating the location of the
current insertion point. Text typed by the user or entered programmatically is entered
before the character at the specified index. Indexes are 1 based, that is, the first
character is at index 1, the second at index 2, and so on.

If the SelLength property contains a value greater than 0, this property indicates the
beginning of a text selection. You can use this property in combination with
SelLength to select text in the control.

See Also SelLength property

SelText property

SelStart 307
ClearBasic Control Reference
 Multiline Text Box control

property SelText

Syntax YourControl.SelText = "String"

SelectedText = YourControl.SelText

Applies To Multiline Text Box

Description The SelText property contains a string with the text of the current selection. Getting
this property returns the selected text, setting it replaces the selected text with the
string you specify.

If no text is selected, this property contains an empty string (""). To determine if any
text is selected, check the SelLength property for a non-zero value.

See Also SelLength property

SelStart property

308 SelText
ClearBasic Control Reference
 Multiline Text Box control

property Tag

Syntax YourControl.Tag = "YourStringHere"

ControlTag = YourControl.Tag

Applies To Multiline Text Box

Description The Tag property contains a custom string that you assign at runtime. You can use
this string to identify the control internally to your application. You can also use this
property to store extra information about the control.

Tag 309
ClearBasic Control Reference
 Multiline Text Box control

property Text

Syntax YourControl.Text = "YourStringHere"

ControlText = YourControl.Text

Applies To Multiline Text Box

Description The Text property contains the complete text displayed by the multiline text box
control. The text in this property is stored in the destination contextual object linked to
the control.

This property is readable and writable. Setting this property replaces the text
currently in the control with the new string you specify. It also updates the contents of
the destination contextual object.

NOTE: This property behaves the same way as the Value property of the multiline text box
control.

310 Text
ClearBasic Control Reference
 Multiline Text Box control

property Value

Syntax ControlValue = YourControl.Value

YourControl.Value = NewValue

Applies To Multiline Text Box

Description The Value property contains the complete text displayed by the multiline text box
control. The text in this property is stored in the destination contextual object linked to
the control.

This property is readable and writable. Setting this property replaces the text
currently in the control with the new string you specify. It also updates the contents of
the destination contextual object.

Value 311
ClearBasic Control Reference
 Multiline Text Box control

event Click

Syntax Sub YourControl_Click

Applies To Multiline Text Box

Description The Click event handler for your multiline text box is called when the user presses
and releases the mouse button over the control. A Click event usually indicates the
positioning of the insertion point or the selection of text. You can use this event in
combination with the SelStart and SelLength properties to determine the new
selection.

See Also SelLength property

SelStart property

312 Click
ClearBasic Control Reference
 Multiline Text Box control

event ContextMenuDisplaying

Syntax Sub YourControl_ContextMenuDisplaying

Applies To Multiline Text Box

Description The ContextMenuDisplaying event notifies your control that its context-sensitive
menu is about to be displayed. Use this event to update the appearance of the menu
and its items. You can enable or disable items, set the visibility of items, or add items
to the menu as appropriate.

The control sends this event in response to a user request to display the context-
sensitive menu. The event is sent before the menu is displayed.

In your ContextMenuDisplaying event handler, modify the menu and its

appearance to reflect the current state of the control. For example, if your menu
contains a Select All command, you might want to disable the command if the entire
contents of the control are already selected.

See Also AppendContextMenu method

SetContextMenuEnabled method
SetContextMenuVisible method
ContextMenu_Select event

ContextMenuDisplaying 313
ClearBasic Control Reference
 Multiline Text Box control

event ContextMenu_Select

Syntax Sub YourControl_ContextMenu_Select (EventName)

Applies To Multiline Text Box

Description The ContextMenu_Select event notifies your application that the user chose an
item from the control’s context-sensitive menu. In your event handler, perform the
task associated with the menu item.

You must provide an event handler for each menu item you define in the context-
sensitive menu. You can define menu items at design time using the Clarify User
Interface Editor or at runtime using the AppendContextMenu method.

Parameters This event receives the following parameter:

Parameter Type Description

EventName String Contains the internal name you assigned to the event handler
using the User Interface Editor. If you used the
AppendContextMenu method to create the item, this
parameter contains the value you specified in the ItemName
parameter of that method.

See Also AppendContextMenu method

ContextMenuDisplaying event

314 ContextMenu_Select
ClearBasic Control Reference
 Multiline Text Box control

event KeyPress

Syntax Sub YourControl_KeyPress (YourKey As Integer)

Applies To Multiline Text Box

Description The KeyPress event occurs when the user presses an ASCII key or an extended
ASCII key in the control (when the control has the focus). Event handlers for this
event can perform tasks such as checking for valid characters.

The parameter YourKey returns the ASCII keycode for the key that was pressed. To
convert the parameter YourKey from ASCII into a character, use the function Chr:
Char = Chr (YourKey)

To convert the character back to ASCII use the Asc function:

YourKey = Asc(char)

Example The following code is part of an event procedure for a textbox that handles the
keypress for a plus "+" key event.
Sub SUB_BILLEXP_MOD_KeyPress(KeyAscii As Integer)
Dim increment As Boolean
increment = False

Debug.print "User entered ", KeyAscii, _

" Chr(", Chr(KeyAscii), ")"

If KeyAscii = Asc("+") Then

Debug.Print "Got a plus!!"
increment = True
End If
End Sub

KeyPress 315
ClearBasic Control Reference
 Multiline Text Box control

316 KeyPress
ClearBasic Control Reference
 Option Button control

Description The option button control implements a two-state button that you use in groups to
represent a set of mutually exclusive choices. Within a group of option buttons, only
one button at a time may be selected. The other buttons are automatically deselected.

You can use the option button control to obtain information about the state of an
option button on a form. The Value property contains an integer indicating the
current state of the control. You can read the value in this property to get the current
state or assign a new value to change the state of the control. Changing the state of an
option button affects the other option buttons in the group.

You can also use this control to change some of the option button settings. For
example, you can enable the control or change its visibility on the form. You can also
change the caption text associated with the control.

Referring to Option You cannot create control objects directly using ClearBasic code. You must associate
Button Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the option
button control called YourOptionBtnControl:
Dim YourControl As Control
Set YourControl = YourOptionBtnControl

Source At design time, you have the option of linking a source contextual object to this
control. This contextual object must contain a string data type. When a form
containing the option button is displayed, the control obtains the option button label
from this contextual object. If you do not assign a source contextual object, the control
uses the label assigned to it at design time.

Using a source contextual object is advantageous in situations where you may want
the label of the option button control to change dynamically. For example, you could
assign a contextual object whose contents contained the value in a particular database
field. As the value in that field change, so does the control label.

NOTE: Whether you use a source contextual object or a fixed text label, you can always change
the control label programmatically by modifying the control’s Caption property.

Destination At design time, you must link a destination contextual object to the control to store the
value for that control. The destination contextual object must contain a String value.
When the option button is selected, it stores the name of the selected option in this
contextual object.

ClearBasic Control Reference

 Option Button control

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ Refresh method[C]
■ SetFocus method [C]

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ Caption property
■ ControlType property [C]
■ DataChanged property
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ Name property [C]
■ Parent property
■ Tag property
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

Events The following event is supported for this events. Events marked with a [C] are
documented with the Control object.
■ Click event
■ GotFocus event [C]
■ LostFocus event [C]

318
ClearBasic Control Reference
 Option Button control

property Caption

Syntax YourControl.Caption = "CaptionTextString"

CaptionString = YourControl.Caption

Applies To Option Button

Description The Caption property contains a string with the label currently displayed by the
option button control. You assign the initial value for this property at design time by
modifying the values on the control’s property sheet. If the control uses a source
contextual object, the initial value for this property is obtained from that object.

You can change the control’s label at runtime by assigning a new string value to this
property. If you plan to change the control’s label at runtime, set the AutoSize
property of the control to Yes in the User Interface Editor. The AutoSize property
expands the control size to accommodate the new label.

If the control uses a source contextual object for the label, getting this property returns
the value in the contextual object. Assigning a value to this property changes the
value in the source contextual object. If the source contextual object is linked to a
database field, the value in that field is also updated to reflect the changes.

IMPORTANT: On some platforms, your caption changes may not persist when you display or
redisplay the form. If this happens, modify the corresponding Form_Load event procedure
and have it set the caption for the control explicitly.

Caption 319
ClearBasic Control Reference
 Option Button control

property DataChanged

Syntax ChangedBool = YourControl.DataChanged

YourControl.DataChanged = ChangedBool

Applies To Option Button

Description The DataChanged property contains a boolean value indicating whether the user
modified the contents of this control. This value only indicates whether modifications
were made by the user; it does not reflect changes made to the control by your
ClearBasic code.

If you modify the control programmatically, you can set this property to reflect your
changes. Set this property to True to indicate you made modifications; otherwise, set it
to False to indicate the control is unchanged.

320 DataChanged
ClearBasic Control Reference
 Option Button control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To Option Button

Description The Parent property returns the form that contains the control. This property is read-
only.

Parent 321
ClearBasic Control Reference
 Option Button control

property Tag

Syntax YourControl.Tag = "YourStringHere"

TagString = YourControl.Tag

Applies To Option Button

Description The Tag property contains a custom string that you can assign at runtime. You can
use this string to identify the object internally in your application. You can also use
this property to store extra information about the object.

322 Tag
ClearBasic Control Reference
 Option Button control

property Value

Syntax YourControl.Value = Setting

Setting = YourControl.Value

Applies To Option Button

Description The Value property contains a long integer indicating the current state of the option
button control. This value corresponds to the option button state seen by the user. The
value in this property is 1 if the control is selected, otherwise 0.

NOTE: The value in this property may not coincide with the value currently in the control’s
destination contextual object. You can call the control’s Refresh method to synchronize the
two values.

You can assign a new value to this property to change the current state of the control.
Setting this property to 1 selects this option button and deselects the other option
buttons in the group. Setting this property to 0 deselects this option button (if it was
selected) and selects the next option button in the group. Changing the value in this
property also changes the value in the associated destination contextual object.

Value 323
ClearBasic Control Reference
 Option Button control

event Click

Syntax Sub YourControl_Click

Applies To Option Button

Description The Click event occurs when the user presses and releases the mouse button with
the cursor on or in the control. You can use this event to respond to user interactions
with the control.

324 Click
ClearBasic Control Reference
 ProgressBar control

Description A progress bar control displays the progress of a lengthy operation. The control
consists of an empty rectangular area that is gradually filled during the course of the
operation. At any given time, the amount of the rectangle that is currently filled
represents the percentage of the operation that is complete.

Your application is responsible for defining the duration of the current operation and
for setting the progress of that operation. The Min and Max properties contain integer
values that define the start and end points of the operation. The current progress is
measured using the Value property of the control. At runtime, the control uses these
three properties to calculate the percentage of the operation that is complete.

At runtime, you must update the Value property to reflect the current progress of the
operation. If you associate the progress bar control with a contextual object, the
control automatically retrieves the value for this property from that object. However,
you can also modify the Value property programmatically as needed.

Referring to You cannot create control objects directly using ClearBasic code. You must associate
Progress Bar controls with a form, frame, or tab using the User Interface Editor. When the form,
Controls frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the progress
bar control called YourProgressControl:
Dim YourControl As Control
Set YourControl = YourProgressControl

Methods This object supports the following method:

■ Refresh method [C]

ClearBasic Control Reference

 ProgressBar control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ Height property [C]
■ Id property [C]
■ Left property [C]
■ Max property
■ Min property
■ Name property [C]
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

326
ClearBasic Control Reference
 ProgressBar control

property Max

Syntax YourValue = YourControl.Max

YourControl.Max = NewValue

Applies To ProgressBar control

Description The Max property contains an integer value representing the end of the operation.
This property is used in conjunction with the Min property to define the duration of
the operation.

This property is readable and writable. The value in this property must be greater
than the value in the Min property. By default, this property contains the value 100.
When the value in the Value property matches this value, the operation is complete.

See Also Min property

Value property

Max 327
ClearBasic Control Reference
 ProgressBar control

property Min

Syntax YourValue = YourControl.Min

YourControl.Min = NewValue

Applies To ProgressBar control

Description The Min property contains an integer value representing the beginning of the
operation. This property is used in conjunction with the Max property to define the
duration of the operation.

This property is readable and writable. The value in this property must be less than
the value in the Max property. By default, this property contains the value 0.

The progress bar control assigns the value in this property to the Value property at
the beginning of the operation.

See Also Max property

Value property

328 Min
ClearBasic Control Reference
 ProgressBar control

property Value

Syntax YourValue = YourControl.Value

YourControl.Value = NewValue

Applies To ProgressBar control

Description The Value property contains an integer value representing the current progress of the
operation. The value in this property must lie within the range specified by the Min
and Max properties.

The progress bar control uses the value in this property to determine how much of the
display rectangle to fill. When the control is initialized, this property is assigned the
value in the Min property.

This property is readable and writable. At runtime, if the control is associated with a
contextual object, the control retrieves updated values for this property from the
contextual object.

See Also Max property

Min property

Value 329
ClearBasic Control Reference
 ProgressBar control

330 Value
ClearBasic Control Reference
 Select CBX control

Description The Select CBX control extends the functionality of your ClearBasic forms by
providing integrated querying capabilities. A Select CBX control is a special type of
control that coordinates the interactions among the contextual objects, database
records, and other controls on the form. Using a Select CBX control, you do not have
to write any ClearBasic code to query the database.

The Select CBX control coordinates the behavior of its constituent controls and uses
them to gather query parameters from the user and to display the query results. The
Select CBX control provides basic functionality to search the database using the
information provided by the user. You can customize the Select CBX and its associated
controls to modify this behavior as needed for your application.

User Interface You add a Select CBX control to a parent or child form just as you would add any
other control. As with other controls, you can access the methods and properties of
the Select CBX control from the form’s ClearBasic routines.

At runtime, the Select CBX control does not display a visible interface in the form
window. Instead, it coordinates the interactions among its associated visible controls.
Figure 5: shows a form containing the controls needed by the Select CBX control.

Figure 5: Controls associated with the Select CBX control.

Filter Select list Find button

Edit Filter button

Select List grid

ClearBasic Control Reference

 Select CBX control

The Select CBX control binds together the following controls:

■ A “Filter Select” drop-down list that displays a list of available filters
■ An “Edit Filter” command button that opens the Filter Set window, which
allows the user to edit filters and sort criteria. This form is shown in Figure 6:
on page 332.
■ A “Find” command button that queries the database and returns a list of
records using the selected filter
■ A “Select List” grid that displays the list of returned records

You create these four controls using the User Interface Editor just as you would create
any other form controls. You may place the controls on the same form as the Select
CBX control, or you may place them on a child form or tab. However, you may not
place these controls on a parent form of the Select CBX control.

Figure 6: Filter set window

NOTE: For detailed information about how to create and set up Select CBX controls, refer to
the User Interface Editor Guide.

Driving Object When the Select CBX control performs a query, it limits the scope of its search to
Types records belonging to the driving object type of the control. You specify the driving
object type on the property sheet of the Select CBX control when you create it in the
User Interface Editor.

The Select CBX control also has a property for the display object type. This property
specifies the record or view type displayed by the Select List grid. If you specify a
view type for this property, the unique field of the view must be the objid field of the
driving object type. If you specify a record type, you must specify the driving object
type.

332
ClearBasic Control Reference
 Select CBX control

Filters The Select CBX control uses filters to define search criteria. A filter compares the value
in one field of a record to a fixed value. The user creates filters using the Filter Set
window and selects them using the Filter Select list. Selecting a filter copies the filter’s
search criteria to the adhoc row of the grid. If the adhoc row is displayed, the user can
modify the information before running the filter. Clicking the Find button runs the
query and returns the resulting records to the Select List grid.

Before users can create their own filters, you must configure the Select CBX control
with the fields you want to make available for filtering. Every filter is made up of
three elements:
■ a path
■ a value
■ a comparison operator

The path specifies the location of the desired field in the database. You must specify
the fields you want available for user filters and you must specify the location of those
fields using paths. By default, paths always start at the database table specified by the
driving object type of the Select CBX control. To create a path to a field in the driving
object type, specify only the field name. To build a path to fields in other tables, use
database relations.

To build a path using database relations, you must start with the relations of the
driving object type. You can then navigate from table to table until you reach the table
with the desired field. Each relation must be followed by a colon and a field must be
the last element on the end of the path. For example, you can build a path from the
case table to the city field of the address table using the path
“case2address:city”.

The comparison operator specifies how a field is compared to the specified value.
Filters support a variety of complex comparison operators, which are listed in Table 7.
Table 7 Supported filter operators

Operator Description
"greater than" The field contains a numeric value greater than the value.
"greater than or equal to" The field contains an numeric value greater than or equal to the
value.
"less than" The field contains an numeric value less than the value.
"less than or equal to" The field contains an numeric value less than or equal to the
value.
“is equal to” The field must match the value exactly.
"is not equal to" The field does not match the value.
“starts with” The field must begin with the specified value.
“ends with” The field must end with the specified value.
“contains” The field contains the specified value. The field may
additionally start with or end with the specified value.
“is in” The field is in the specified range of values.
"between" The field contains an integer or date that is between the
specified values.
“does not start with” The field does not start with the specified value.
“does not end with” The field does not end with the specified value.
“does not contain” The field does not contain the specified value.

333
ClearBasic Control Reference
 Select CBX control

Operator Description
"not between" The field contains an integer or date that is not between the
specified values.
“is not in” The field is not in the specified range of values.
"sounds like" The field text is included in the specified value.
"exists" The field contains a value.
"does not exist" The field does not contain a value.
"today" The field specifies today’s date.
"yesterday" The field specifies yesterday’s date.
"within last (days)" The field specifies a date within the number of days specified
by value.
"within last (hours)" The field specifies a time within the number of hours specified
by value.

If the field matches the specified value using the comparison operator, the Select CBX
control displays the record in the Select List grid.

Adhoc Filtering In addition to the Filter Set window, the user may also specify search criteria using a
technique called adhoc filtering. With adhoc filtering, the user enters search
information into a special row—called the adhoc row—of the Select List grid. The user
may specify search criteria for any of the fields displayed by the grid. When the user
clicks the Find button (or presses the Enter key), the Select CBX control uses the
specified information to perform the search.

If the user selects a filter from the Filter Select list, the adhoc row displays the search
values for the currently-selected filter. The user may use the specified values or type
in new values before clicking the Find button. Because users can type data values
directly into the adhoc row of the Select List grid, adhoc filtering is more convenient
than modifying filters using the Filter Set window. However, the values entered by
the user in the adhoc row are not saved permanently to the database.

Prefilters In addition to user-defined filters, you may define additional filters programmatically.
The filters you define are called prefilters and are applied before any user filters. As a
result, the user filters see only the records allowed through by your prefilters. You can
use prefilters to limit the scope of a query and prevent the user from accessing
particular records.

You create prefilters programmatically by calling the AppendPreFilter method

from ClearBasic code. You may add any number of prefilters using this method. The
Select CBX control applies prefilters in the order they are added. To remove a prefilter,
call the ClearPreFilter method.

Sorting The Filter Set window contains an additional tab that allows the user to specify the
sort criteria for records in the Select List grid. The user chooses one or more fields to
use when sorting the records and chooses whether records should be sorted in
ascending or descending order.

334
ClearBasic Control Reference
 Select CBX control

If the user does not specify a sort criteria, your application may supply a default sort
criteria. To specify a default sort criteria, you must call the AppendDefaultSort
method of the Select CBX control before the query is initiated. You may call
AppendDefaultSort multiple times to specify more than one sort criteria. The
Select CBX control applies sort criteria in the order they are added. To remove a sort
criteria, call the ResetDefaultSort method.

Paging When the Select CBX control performs a query, it does not always load the entire
results of the query into memory. If a query returns a large number of records, the
control uses paging to load a subset of the records into the Select List grid’s contextual
object. The remaining records are loaded into memory as needed.

The Select CBX control keeps two pages of records in memory at any given time. By
default, each page contains 50 records. To change this setting, modify the PAGE_SIZE
variable in the clarify.env file of your client applications.

Paging is normally transparent to the user. However, there are some situations where
methods may not behave as expected. The following is a list of these behaviors and
the situations in which you might encounter them.
■ Record indexes are always relative to the beginning of the currently loaded
pages.
■ A selection containing more than one record cannot extend over page
boundaries.
■ The contents of the select-list grid can only be sorted by performing a new
query.

Support for Multiple For most operations, the Select CBX control only needs to refer to records from one
Contextual Objects database table. However, the Select CBX provides support for changing the current
database table at runtime. A Select CBX control that supports the switching of
contextual objects at runtime is called a multiCBX control.

To enable multiple contextual object support for the Select CBX control, you must set
the appropriate options on the control’s property sheet in the User Interface Editor.
When you enable multi-contextual object support, the Select CBX control retrieves
database type information from its current extended contextual object. When a form
containing your multiCBX control is posted, your Form_Load routine must set the
control’s initial extended contextual object using the SetCObj method. The GetCObj
method returns the name of the extended contextual object currently in use.

When you set the extended contextual object for a multiCBX control, the control
automatically loads the new information into memory and updates the contents of the
Select List grid and Filter-Select list. During the context switch, data in the previous
extended contextual object is cached for future use. When you switch to an extended
contextual object with cached data, the multiCBX control automatically displays the
cached data.

Select CBX and When you associate a Select CBX with a grid, the Select CBX takes over many aspects
Grids of the grid operation. In particular, the Select CBX coordinates the storage of the
records in the grid and the updates needed to display those records.

335
ClearBasic Control Reference
 Select CBX control

The Select CBX control defines several methods for retrieving grid information. If you
need to retrieve or set some grid data, call the appropriate Select CBX method instead
of the corresponding grid method whenever possible. Calling the Select CBX method
ensures that any Select CBX state information is updated appropriately.

Referring to the When you want to refer to a Select CBX control in ClearBasic code, you must use the
Select CBX Control control’s instance name, prepended with the string “Cbx_”. Notice that this name is
in Your Code not the same as the control name you assign on the Select CBX property sheet. The
control name and instance name are separate entries. For example, to call the
Regenerate method of a Select CBX control whose control name is “MyCBX” and
whose instance name is “SelectTerritory”, you would use the following code:
Cbx_SelectTerritory.Regenerate

336
ClearBasic Control Reference
 Select CBX control

Methods This object supports the following methods:

■ AppendAdhocFilter method
■ AppendDefaultSort method
■ AppendItem method
■ AppendPreFilter method
■ ClearAdhocRow method
■ ClearAll method
■ ClearPreFilter method
■ EnableAdhoc method
■ GenerateSQL method
■ GetAdhocRow method
■ GetChangedCell method
■ GetCObj method
■ GetCount method
■ GetList method
■ GetNext method
■ GetObjIds method
■ GetPageSize method
■ GetPrevious method
■ GetSelCount method
■ GetSelected method
■ InsertItem method
■ OwnsGrid method
■ RefreshItem method
■ Regenerate method
■ RejectAdhocCellEntry method
■ RemoveItem method
■ RemoveSelected method
■ ReplaceSelected method
■ ResetDefaultSort method
■ ResetPreFilter method
■ SelectedList method
■ SetAdhocCellReadOnly method
■ SetAdhocCellText method
■ SetCObj method
■ SetCurrent method
■ SetSelected method

337
ClearBasic Control Reference
 Select CBX control

■ SetSelectedById method
■ UnSelect method
■ UpdateItem method

See Also Command Button control

Dropdown List Box control
Grid control
Text Box control

338
ClearBasic Control Reference
 Select CBX control

method AppendAdhocFilter

Syntax Cbx_InstanceName.AppendAdhocFilter Path, Operator, Value

Applies To Select CBX

Description The AppendAdhocFilter method assigns a filter value to the adhoc row. This
method adds the specified filter criteria to the adhoc row of the Select List grid. If the
specified field is not displayed in the grid, the filter condition is added but is not
visible to the user.

IMPORTANT: If the Select CBX control is a multiCBX, you must use this method in place of
the SetAdhocCellText method when adding filters to the control.

Parameters This method accepts the following parameters:

Parameter Type Description

Path String Specify a path to a field in the database. The prefilter
compares the specified field to the value in the Value
parameter.
Operator String Specify the filter operator to use when comparing the value at
the specified path to the value in the Value parameter.
Value String Specify the value to compare against the field identified by the
Path parameter.

See Filters on page 333 for information on specifying paths and operators.

Return Values None

See Also SetAdhocCellText method

AppendAdhocFilter 339
ClearBasic Control Reference
 Select CBX control

method AppendDefaultSort

Syntax Cbx_InstanceName.AppendDefaultSort SortName, Path, SortOrder

Applies To Select CBX

Description The AppendDefaultSort method adds the specified criteria to the default sort
criteria of the Select CBX control. If the user initiates a query using a filter that does
not contain any sort criteria, the Select CBX control applies the default sort criteria.

You may call this method multiple times to specify a sort order based on multiple
columns of the Select List grid. With each invocation, this method adds the specified
criteria to the end of the default sort criteria list. The criteria in this list are applied in
the order they were added to the list.

Parameters This method accepts the following parameters:

Parameter Type Description

SortName String Specify a name for this sort criteria. This name is not seen by
users. You can use it internally to identify the sort criteria.
Path String Specify the path to the field on which you want to sort. The path
assumes that you are beginning with the driving object type. See
Filters on page 333 for information on specifying paths.
SortOrder String Specify the sort order to apply one of the following strings:
String Description
“Ascending” Sort items in ascending order
“Descending” Sort items in descending order

Return Values None

Example The following code snippet adds two sort criteria to the default sort order. When this
default order is applied, the Select CBX control sorts entries by “Site Name” and then
by “Bin Name.”
Cbx_SelectInvCnt.AppendDefaultSort "Sort1", _
"Site Name", "Ascending"

Cbx_SelectInvCnt.AppendDefaultSort "Sort2", _
"Bin Name", "Descending"

See Also ResetDefaultSort method

340 AppendDefaultSort
ClearBasic Control Reference
 Select CBX control

method AppendItem

Syntax Cbx_InstanceName.AppendItem Record

Cbx_InstanceName.AppendItem 0, RecordObjId
Cbx_InstanceName.AppendItem ListOfRecords
Cbx_InstanceName.AppendItem 0, ListOfRecordObjIds

Applies To Select CBX

Description The AppendItem method adds one or more records to the end of the Select List grid.
This method does not save the specified records to the database; you must do that in
your ClearBasic code. The type of the records you specify must be the same as the
driving object type of the Select CBX control.

You can use this method to add existing database records or newly created records to
the list. Because the Select List grid displays records temporarily, you must save
newly created records to the database if you want to retain their data. If you use an
editable grid control for the Select List grid, you must similarly save changes to
existing records using the grid control interface.

This method adds the new items to the last page of the Select List grid’s result set. If
the page containing the new items is not currently displayed, the control scrolls that
page into view. If you are adding new items, call the SaveAnyChanges method of the
Select List grid to save the new items to the database.

Parameters This method accepts one of the following parameters:

Parameter Type Description

Record Record Specify the record to append to the list.
RecordObjId Long Specify the object ID (objid) of the record to append to
the list.
ListOfRecords List Specify a list containing one or more records that you
want to append to the list.
ListofRecordObjIds List Specify a list containing one or more object IDs (objid)
corresponding to the records you want to append to
the list.

Return Values None

Example The following example shows the Click routine associated with a command button.
This routine retrieves several records from the database and then uses the
AppendItem method to add them to the Select CBX control whose instance name is
“SelectTerritory.”

AppendItem 341
ClearBasic Control Reference
 Select CBX control

The first set of calls retrieve the records from the database. The second set of calls gets
the returned list of records and adds them to the Select List grid. Because the grid is
associated with a Select CBX control, the records must be added through the Select
CBX.
Sub btn_AppendItem_Click
’Set up required variables
Dim recList As List
Dim myBulk As New BulkRetrieve

' Set up and run a query to retrieve

' "territory" records whose "terr_id" field
' contains the value "123".
myBulk.SimpleQuery 0,"territory"
myBulk.AppendFilter 0,"terr_id",cbEqual,"123"
myBulk.RetrieveRecords

' Assign the retrieved records to recList

' and append the records to the grid.
Set recList = myBulk.GetRecordList(0)
Cbx_SelectTerritory.AppendItem recList
Grid_SelectList.SaveAnyChanges
End Sub

See Also InsertItem method

Regenerate method
SaveAnyChanges method (Grid control)

342 AppendItem
ClearBasic Control Reference
 Select CBX control

method AppendPreFilter

Syntax Cbx_InstanceName.AppendPreFilter FilterName, Path, Operator,

Value

Applies To Select CBX

Description The AppendPreFilter method adds a prefilter to the Select CBX control. Prefilters
limit the set of records passed to user-defined filters. You can use this method to
prevent the retrieval of any irrelevant or unwanted records. The prefilters you add
with this method take effect the next time you run the query using the Regenerate
method.

You can call this method multiple times to specify multiple prefilters. Each call adds
the specified prefilter to the end of the Select CBX control’s current list of prefilters.
During a query, the prefilters are applied in order, with subsequent filters operating
on the records retrieved by earlier filters.

To remove a specific prefilter from the Select CBX control, call the ClearPreFilter
method. To remove all of the control’s prefilters, call the ResetPreFilter method

Parameters This method accepts the following parameters:

Parameter Type Description

FilterName String Specify a name for the filter. Your application uses this name
internally to identify the filter.
Path String Specify a path relation to a field in the database. The prefilter
compares the specified field to the value in the Value parameter.
Operator String Specify the comparison operator to use when comparing the
value at the specified path to the value in the Value parameter.
Value String Specify the value against which to compare the field.

See Filters on page 333 for more information about paths and comparison operators.

Return Values None

AppendPreFilter 343
ClearBasic Control Reference
 Select CBX control

Example The following subroutine demonstrates the use of the AppendPreFilter method. In
this example, the SetFilter button’s Click event handler adds several prefilters to the
form’s Select CBX object, called SelectTerritory. In particular, this example sets up the
following prefilters:.
■ nameFilter filters records based on a specific name (Terri)
■ regionFilter filters records based on a specific geographic region (Florida)
■ branchFilter filters records based on a specific branch office (Miami)
Sub btn_SetFilter_Click
' Set up and append a prefilter, which is
' ANDed with the filter selected in the
' current select window and any other
' prefilters specified for the same Select
' CBX object elsewhere in the form module.

' This prefilter selects only those records

' whose "name" field contains "Terri".
CBX_SelectTerritory.AppendPreFilter _
"nameFilter", "name", "is equal to", _
"Terri"

' Set up and append another prefilter. This

' prefilter selects only those records whose
' "region" field contains "Florida".
CBX_SelectTerritory.AppendPreFilter _
"regionFilter", "region", _
"is equal to", "Florida"

' Set up and append another prefilter. This

' prefilter selects only those records whose
' "branch" field contains "Miami".
CBX_SelectTerritory.AppendPreFilter _
"branchFilter", "branch", _
"is equal to", "Miami"

'Regenerate (update) the list currently

'displayed in the Select List grid.
CBX_SelectTerritory.Regenerate
End Sub

See Also ClearPreFilter method

Regenerate method
ResetPreFilter method

344 AppendPreFilter
ClearBasic Control Reference
 Select CBX control

method ClearAdhocRow

Syntax Cbx_InstanceName.ClearAdhocRow

Applies To Select CBX

Description The ClearAdhocRow method clears the contents of each cell in the adhoc row. You
can use this method to reset the adhoc row when the form is posted or when the user
wants to clear the current search parameters.

Parameters None.

Return Values None.

See Also EnableAdhoc method

GetAdhocRow method
SetAdhocCellText method
SetCellText method (Grid control)

ClearAdhocRow 345
ClearBasic Control Reference
 Select CBX control

method ClearAll

Syntax Cbx_InstanceName.ClearAll

Applies To Select CBX

Description The ClearAll method clears the results of the last query and clears the items
displayed in the Select List grid. This method also resets the current record, as
assigned by the SetCurrent, GetNext, and GetPrevious methods.

After calling this method, you can call the Regenerate method to retrieve an
updated set of records. This method does not trigger any events.

Parameters None.

Return Values None.

See Also GetNext method

GetPrevious method
Regenerate method
SetCurrent method

346 ClearAll
ClearBasic Control Reference
 Select CBX control

method ClearPreFilter

Syntax Cbx_InstanceName.ClearPreFilter FilterName, Path

Applies To Select CBX

Description The ClearPreFilter method removes one or more prefilters from the Select CBX
control. You may use this method to remove only the prefilters you added with the
AppendPreFilter method; you cannot use this method to remove any user-defined
filters.

If you specify values for both the FilterName and Path parameters, the values must
refer to the same prefilter. If you specify an empty string for the Path parameter, this
method removes all prefilters whose name matches the value in the FilterName
parameter. If you specify an empty string for the FilterName parameter, this method
removes all prefilters whose path relation matches the value in the Path parameter. If
you specify empty strings for both parameters, this method does nothing.

NOTE: Removing a prefilter does not alter the currently displayed list of records. You must
call the Regenerate method to update the list of records.

This method does not trigger any events.

Parameters This method accepts the following parameters:

Parameter Type Description

FilterName String Specify the name of the filter. This string is the identification
string you assigned to the filter when you created it.
Path String Specify the path of the filter. You must specify the complete
path of the filter to remove, not just a portion of the path.

Return Values None

Example The following example illustrates the use of the btn_ClearPreFilter method. In
this example, when the user clicks the btn_ClearPreFilter button, the subroutine
removes all prefilters named “nameFilter” and removes all filters whose path relation
is “name”.
Sub btn_ClearPreFilter_Click
' Clear the prefilter named "nameFilter"
' associated with the Select CBX instance
' SelectTerritory
Cbx_SelectTerritory.ClearPreFilter _
"nameFilter",""

ClearPreFilter 347
ClearBasic Control Reference
 Select CBX control

' Clear the prefilter(s) whose path is "name"

Cbx_SelectTerritory.ClearPreFilter "","name"
End Sub

See Also AppendPreFilter method

ResetDefaultSort method

348 ClearPreFilter
ClearBasic Control Reference
 Select CBX control

method EnableAdhoc

Syntax Cbx_InstanceName.EnableAdhoc Enabled, Show

Applies To Select CBX

Description The EnableAdhoc method enables or disables the availability of the adhoc row in the
Select List grid. You also use this method to set the visibility of the adhoc row. The
adhoc row lets the user enter query values for each field in the grid using the grid
interface. When enabled and visible, the adhoc row is the first row in the grid.

When you enable the adhoc row, the grid makes the row available to the user. The
user may show the row or hide the row at runtime using the grid interface. You can
also use this method to show or hide the row by specifying a value for the Show
parameter.

If you disable the adhoc row, the grid makes the adhoc row inaccessible to the user.
The user cannot toggle the display of the row in any way. You must enable the row
using this method to make the row available again.

When the user selects a filter from the Filter Select list, the Select CBX control displays
the filter information in the adhoc row. If the adhoc row is disabled, the information is
applied to queries but is not visible to the user.

Parameters This method accepts the following parameters:

Parameter Type Description

Enabled Boolean Specify True to make the adhoc row available to users,
otherwise specify False to make it unavailable.
Show Boolean Specify True to display the adhoc row, otherwise specify False
to hide the row.
This parameter is optional and is set to the value True by
default. If the Enabled parameter is False, this parameter has
no effect.

Return Values None

See Also GetAdhocRow method

EnableAdhoc 349
ClearBasic Control Reference
 Select CBX control

method GenerateSQL

Syntax Set QueryRecord = Cbx_InstanceName.GenerateSQL (Options)

Applies To Select CBX

Description The GenerateSQL method generates an SQL string and returns it in a record of type
query. You can execute the returned SQL string by calling the Execute method of the
SQLDB object.

The returned SQL string incorporates the information indicated by the Options
parameter. You can use this parameter to specify which filters to include in the SQL
string. When gathering user-defined filter information, this method uses only those
filters created in the Filter Set window. This method does not use information entered
into the adhoc row by the user.

Parameters This method accepts the following parameters:

Parameter Type Description

Options String Specify one of the following values to determine which filters (if
any) to apply to the query.
Value Description
0 The query includes only the user-defined filters.
1 The query includes only the current prefilters.
2 The query includes the current prefilters and
user-defined filters.

Return Values Returns a Record object representing the query table. The sql_statement field of
this record contains the SQL string for the query.

See Also Regenerate method

Execute method (SQLDB object in ClearBasic Object Reference)

350 GenerateSQL
ClearBasic Control Reference
 Select CBX control

method GetAdhocRow

Syntax RetBool = Cbx_InstanceName.GetAdhocRow FieldNameList, DataList

Applies To Select CBX

Description The GetAdhocRow method returns the query information entered by the user into the
cells of the adhoc row. For each non-empty cell, this method returns the name of the
corresponding field and the value in the cell.

The items in the FieldNameList and DataList parameters are ordered in parallel. That
is, for each field name in the FieldNameList parameter, the corresponding cell data is
at the same index in the DataList parameter. For example, the data at index 0 in the
DataList parameter belongs to the cell whose field name is at index 0 in the
FieldNameList parameter.

Parameters This method accepts the following parameters:

Parameter Type Description

FieldNameList List Specify a List variable for storing items of type “string”. On
return, this list contains one or more Strings, each of which
contains the name of a field associated with a column in the
adhoc row. Only those fields that contain a non-empty
value are returned.
DataList List Specify a List variable for storing items of type “string”. On
return, this list contains one or more Strings, each of which
contains the data for a field. Each data item corresponds to
the cell associated with the column at the same index in
FieldNameList.

Return Values Returns True if the data was retrieved successfully, otherwise False.

See Also AppendAdhocFilter method

ClearAdhocRow method
EnableAdhoc method
SetAdhocCellText method

GetAdhocRow 351
ClearBasic Control Reference
 Select CBX control

method GetChangedCell

Syntax RetBool = Cbx_InstanceName.GetChangedCell FieldName, CellData

Applies To Select CBX

Description The GetChangedCell method returns information about the most recently changed
cell in the adhoc row. Call this method only from an AdhocCellChanged event
handler.

This method returns the field name of the cell that changed and returns the new value
of the cell. You can use this information to validate the contents of the cell. For
example, you could check to see if the specified value lies within a valid range of
values.

Parameters This method accepts the following parameters:

Parameter Type Description

FieldName String Specify a variable of type String. On return, the variable
contains the field name of the changed adhoc cell.
CellData String Specify a variable of type String. On return, the variable
contains the new adhoc cell value.

Return Values Returns True if the data was retrieved successfully, otherwise False.

See Also GetAdhocRow method

AdhocCellChanged method (Grid control)

352 GetChangedCell
ClearBasic Control Reference
 Select CBX control

method GetCObj

Syntax CObjName = Cbx_InstanceName.GetCObj

Applies To Select CBX

Description The GetCObj method returns the name of the contextual object currently associated
with the Select CBX control. You can pass this string to other methods to obtain
additional information about the properties and methods of the contextual object.

This method applies only to Select CBX controls that support multiple contextual
objects. For information on creating Select CBX controls that support multiple
contextual objects, see the User Interface Editor Guide.

Parameters None

Return Values Returns a String containing the name of the ContextualObject currently associated
with the Select CBX control. The returned string does not include the "Cobj_" prefix
normally added when referring to the contextual object in code.

See Also SetCObj method

CObj property (Grid control)
GetCBCObj method (Form object in ClearBasic Object Reference)
GetCObjFieldList (Form object in ClearBasic Object Reference)
GetCObjMethodList (Form object in ClearBasic Object Reference)

GetCObj 353
ClearBasic Control Reference
 Select CBX control

method GetCount

Syntax NumRows = Cbx_InstanceName.GetCount CObjName

Applies To Select CBX

Description The GetCount method returns the number of rows returned by the most recent
query. For Select CBX controls that support only one contextual object, this method
returns the number of rows in the Select List grid’s source contextual object. For
multiCBX controls, this method returns the number of rows in the specified
contextual object. If you do not specify a contextual object name, this method returns
the number of rows in the current contextual object.

Due to paging restrictions, the value returned by this method may be less than the
total number of rows that match the query search criteria.

Parameters This method accepts the following parameter:

Parameter Type Description

CObjName String You can specify an optional contextual object name. If you
specify this parameter, this method returns the number of
rows in the specified contextual object; otherwise, it uses
the current contextual object.

Return Values Returns a Long integer indicating the number of rows in the specified contextual
object.

See Also GetSelCount method

354 GetCount
ClearBasic Control Reference
 Select CBX control

method GetList

Syntax Set RecordList = Cbx_InstanceName.GetList CObjName

Applies To Select CBX

Description The GetList method returns the list of records currently in the source contextual
object of the associated Select List grid. For Select CBX controls, these records
correspond to the most recent set of records retrieved by the user using the query
mechanisms of the Select CBX control. For multiCBX controls, these records
correspond to the records in the specified contextual object.

This method supports Select CBX controls with multiple contextual objects. If you
specify a value for the CObjName parameter, this method returns the records in the
specified contextual object. If you omit the CObjName parameter, this method returns
the records for the current contextual object.

Because of paging restrictions, this method returns only the records currently in
memory. For large result sets, this list may contain only a portion of the total records.
For more information about paging, see Paging on page 335.

Parameters This method accepts the following parameter:

Parameter Type Description

CObjName String Specify the name of a contextual object.
This parameter is optional. If you specify this parameter,
GetList returns the list of records in the specified
contextual object; otherwise, it returns the records in the
current contextual object.

Return Values Returns a List object containing zero or more records.

See Also GetNext method

GetPrevious method
GetSelected method

GetList 355
ClearBasic Control Reference
 Select CBX control

method GetNext

Syntax Cbx_InstanceName.GetNext RecordObjId, RecordIndex,

RecordsInList, SelectRecord
Set Your_RecordVariable = Cbx_InstanceName.GetNext
(RecordObjId, RecordIndex, RecordsInList, SelectRecord)

Applies To Select CBX

Description The GetNext method increments the position of the current record by one. On return,
this method returns information about the new current record in the specified
parameters. If the current record is set to the last record in the Select List grid, this
method wraps around and makes the first record the current record.

Normally, you call the SetCurrent method to set the current record before calling
this method. If you do not call SetCurrent, the current record is set to the first
record in the Select List grid by default.

Because of paging restrictions, the information returned by this method is limited to

the set of records currently loaded into the source contextual object of the Select List
grid. These numbers may not reflect the total number of records that match the
current search criteria.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordObjId Long Specify a variable of type Long. On return, this parameter
contains the object ID of the new current record.
RecordIndex Long Specify a variable of type Long. On return, this parameter
contains the index of the new current record.
Indexes are zero-based and are relative to the beginning of
the current page.
RecordsInList Long Specify a variable of type Long. On return, this parameter
contains the number of records currently in the Select List
grid’s source contextual object.
SelectRecord Boolean Specify True if you want the specified record to be selected
in the user interface. If you specify True, make sure the
next record is on the current page.
This parameter is optional and is set to False by default.

Return Values Returns the Record object representing the new current record.

356 GetNext
ClearBasic Control Reference
 Select CBX control

Example The following example implements a Click event handler that displays information
about the record immediately after the selected record. This method uses the
SetCurrent and GetNext methods to get the record immediately after the selected
record.
Sub btn_SetCurRec_Click
'Set up required variables
Dim nextRecord As New Record
Dim selRecord as New Record
Dim recIndex As Long
Dim recObjId As Long
Dim recTotal As Long
Dim myResult As Boolean

' Mark the selected record as the current record.

myResult = Cbx_SelectTerritory.GetSelected(selRecord)

if myResult = TRUE Then

Cbx_SelectTerritory.SetCurrent _
selRecord.GetField(“objid”), recIndex, TRUE

' Get the record after the selection

Set nextRecord = Cbx_SelectTerritory.GetNext _
(recObjId, recIndex, recTotal)

'Display details about the next record in the

'Debug Print window
Debug.Print nextRecord
Debug.Print "ObjId of nextRecord: ", _
’recObjId
Debug.Print "Index of nextRecord: ", _
recIndex
Debug.Print "Total records in list: ", _
recTotal
End If
End Sub

See Also GetPrevious method

GetSelected method
SetCurrent method

GetNext 357
ClearBasic Control Reference
 Select CBX control

method GetObjIds

Syntax Set ListOfObjids = Cbx_InstanceName.GetObjIds (CObjName)

Applies To Select CBX

Description The GetObjIds method returns the list of object IDs from the specified result set.
Each result set contains a list of object IDs returned by the most recent query. For
Select CBX controls that support only one contextual object, this method always
returns the object IDs from the current result set.

If the Select CBX control supports multiple contextual objects, the control maintains
separate result sets for each associated contextual object. You can request object IDs
from a different result set by specifying the name of the corresponding contextual
object in the CObjName parameter. If you do not specify the name of a contextual
object, this method returns the object IDs from the current contextual object’s result
set.

This method is not affected by paging. The list returned by this method contains the
object IDs for every record in the retrieved result set, including those records on pages
not in memory.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Optionally, specify a string containing the name of a
contextual object associated with the multiCBX control.
The name of the contextual object is the name you
assigned in the User Interface Editor. This name must not
contain the “CObj_” string normally used when referring
to the contextual object in code.

Return Values Returns a List object containing zero or more long integers. Each long integer
contains the value in the objid field of a record in the specified contextual object.

See Also GetCObj method

SetCObj method
ContextualObject object (in the ClearBasic Object Reference)

358 GetObjIds
ClearBasic Control Reference
 Select CBX control

method GetPageSize

Syntax PageSize = Cbx_InstanceName.GetPageSize

Applies To Select CBX

Description The GetPageSize method returns the maximum number of records possible on a
single page. The Select CBX control uses paging to improve the performance of the
grid. See Paging on page 335 for more information.

The value returned by this method corresponds to the value assigned to the
PAGE_SIZE variable in the user’s clarify.env file. The default page size value is
50.

Parameters None

Return Values Returns a long integer indicating the maximum number of records possible on a
single page.

See Also ContextualObject object (in the ClearBasic Object Reference)

GetPageSize 359
ClearBasic Control Reference
 Select CBX control

method GetPrevious

Syntax Cbx_InstanceName.GetPrevious RecordObjId, RecordIndex,

RecordsInList, SelectRecord
Set Your_RecordVariable = Cbx_InstanceName.GetPrevious
(RecordObjId, RecordIndex, RecordsInList, SelectRecord)

Applies To Select CBX

Description The GetPrevious method decrements the position of the current record by one. On
return, this method returns information about the new current record in the specified
parameters. If the current record is set to the first record in the Select List grid, this
method wraps around and makes the last record the current record.

Normally, you call the SetCurrent method to set the current record before calling
this method. If you do not call SetCurrent, the current record is set to the first
record in the Select List grid by default.

Because of paging restrictions, the information returned by this method is limited to

the set of records currently loaded into the source contextual object of the Select List
grid. These numbers may not reflect the total number of records that match the
current search criteria.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordObjId Long Specify a variable of type Long. On return, this parameter
contains the object ID of the new current record.
RecordIndex Long Specify a variable of type Long. On return, this parameter
contains the index of the new current record.
Indexes are zero-based and are relative to the beginning of
the current page.
RecordsInList Long Specify a variable of type Long. On return, this parameter
contains the number of records currently in the Select List
grid’s source contextual object.
SelectRecord Boolean Specify True if you want the specified record to be selected
in the user interface. If you specify True, make sure the
previous record is on the current page.
This parameter is optional and is set to False by default.

Return Values Returns the Record object representing the new current record.

360 GetPrevious
ClearBasic Control Reference
 Select CBX control

Example The following example displays information about the record immediately before the
selected record. This method uses the SetCurrent and GetPrevious methods to
get the record immediately after the selected record.
Sub btn_SetCurRec_Click
'Set up required variables
Dim prevRecord As New Record
Dim selRecord as New Record
Dim recIndex As Long
Dim recObjId As Long
Dim recTotal As Long
Dim myResult As Boolean

' Mark the selected record as the current record.

myResult = Cbx_SelectTerritory.GetSelected(selRecord)

if myResult = TRUE Then

Cbx_SelectTerritory.SetCurrent _
selRecord.GetField(“objid”), recIndex, TRUE

' Get the record after the selection

Set prevRecord = Cbx_SelectTerritory.GetPrevious _
(recObjId, recIndex, recTotal)

'Display details about the previous record in the

'Debug Print window
Debug.Print prevRecord
Debug.Print "ObjId of prevRecord: ", _
’recObjId
Debug.Print "Index of prevRecord: ", _
recIndex
Debug.Print "Total records in list: ", _
recTotal
End If
End Sub

See Also GetNext method

GetSelected method
SetCurrent method

GetPrevious 361
ClearBasic Control Reference
 Select CBX control

method GetSelCount

Syntax NumRows = Cbx_InstanceName.GetSelCount CObjName

Applies To Select CBX

Description The GetSelCount method returns the number of selected rows in the specified
contextual object. For Select CBX controls that support only one contextual object, this
method returns the number of rows in the Select List grid’s source contextual object.
For multiCBX controls, this method returns the number of selected rows in the
specified contextual object. If no contextual object is specified, this method uses the
current contextual object.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Specify the name of a contextual object.
This parameter is optional. If you specify a non-empty string for
this parameter, this method looks for a contextual object with the
specified name; otherwise, it uses the current contextual object.

Return Values Returns a Long integer indicating the number of selected rows in the specified
contextual object.

362 GetSelCount
ClearBasic Control Reference
 Select CBX control

method GetSelected

Syntax Cbx_InstanceName.GetSelected SelectedRecord, CObjName

YourBoolean = Cbx_InstanceName.GetSelected SelectedRecord,
CObjName

Applies To Select CBX

Description The GetSelected method returns the currently selected record from the Select List
grid. If more than one record is selected, this method returns only the first record in
the selection.

This method supports Select CBX controls with multiple contextual objects. If you
specify a value for the CObjName parameter, this method returns the selected records
in the specified contextual object. If you omit the CObjName parameter, this method
returns the selected records for the current contextual object.

Call this method only if the Select List grid supports the selection of one record at a
time. If the grid supports the selection of multiple records, use the SelectedList
method to retrieve the current selection.

Parameters This method accepts the following parameters:

Parameter Type Description

SelectedRecord Record Specify a variable of type Record. On return, this variable
contains a copy of the selected record.
CObjName String You can specify an optional contextual object name. If you
specify a non-empty string for this parameter, this method
looks for a contextual object with the specified name;
otherwise, it uses the current contextual object.

Return Values Returns TRUE if a record was selected, otherwise FALSE.

Example The following code snippet illustrates the use of the GetSelected method:
Dim myRecord As New Record
Dim myResult As Boolean

'Check whether a record is already selected

'in the Select List grid.
myResult = Cbx_SelectTerritory.GetSelected (myRecord)

If myResult = TRUE Then

Debug.Print "Found selected record in grid."

'Any additional code

...
Else

GetSelected 363
ClearBasic Control Reference
 Select CBX control

Debug.Print "Found no selected record in _

grid."

'Any additional code

...
End If

See Also ReplaceSelected method

SelectedList method
SetSelected method
SetSelectedById method

364 GetSelected
ClearBasic Control Reference
 Select CBX control

method InsertItem

Syntax Cbx_InstanceName.InsertItem Record

Cbx_InstanceName.InsertItem RecordList
Cbx_InstanceName.InsertItem Record, ReferenceRecord, Position
Cbx_InstanceName.InsertItem RecordList, ReferenceRecord,
Position

Applies To Select CBX

Description The InsertItem method inserts one or more records into the Select List grid. This
method adds the specified records to the grid’s current list of items but does not add
the records to the database. The type of the records you specify must be the same as
the driving object type of the Select CBX control.

The ReferenceRecord and Position parameters let you specify the location at which to
insert the records. If you omit these parameters, this method inserts the records at the
top of the Select List grid.

You can use this method to insert existing database records or newly created records
into the Select List grid. Because the Select List grid displays records temporarily, you
must save newly created records to the database if you want to retain their data.

After it inserts the records, this method refreshes the list displayed by the Select List
grid. This method does not generate any events.

Parameters This method accepts the following parameters:

Parameter Type Description

Record Record Specify the record you want to insert into the Select List grid.
If you specify this parameter, do not specify the RecordList
parameter.
RecordList List Specify the list of records you want to insert into the Select
List grid.
If you specify this parameter, do not specify the Record
parameter.
ReferenceRecord Long Optionally, specify the object ID (objid) of a record in the
Select List grid. This record becomes the reference record.
The value in the Position parameter determines whether
records are inserted before or after this record.
This parameter is optional and is set to the value 0 by default.
Position Boolean Optionally, specify True to insert the records before the
reference record, otherwise False to insert the records after
the reference record.
This parameter is optional and is set to True by default.

Return Values None

InsertItem 365
ClearBasic Control Reference
 Select CBX control

Example The following example demonstrates the Click event handler for a button. When the
user clicks the button, this method retrieves some “territory” records and attempts to
insert them into the Select List grid. If a record is currently selected in the Select List
grid, this routine inserts the retrieved records before the selected record. If no record is
selected, this method inserts the retrieved records at the top of the list.
Sub btn_InsertRec_Click
'Set up required variables
Dim selRecord As New Record
Dim recList As New List
Dim myBulk As New BulkRetrieve
Dim selObjID As Long

' Retrieve the "territory" records that have

' a "terr_id" of 123.
myBulk.SimpleQuery 0,"territory"
myBulk.AppendFilter 0,"terr_id",cbEqual,"123"
myBulk.RetrieveRecords

'Put the retrieved records into recList

Set recList = myBulk.GetRecordList(0)

' Check to see if a record is currently

' selected. If one is, insert the new records
' before the selected record. Otherwise,
’ insert the records at the top of the list.
if Cbx_SelectTerritory.GetSelected _
(selRecord) Then
selObjID = selRecord.GetField("objid")

' Insert the records before the selected

' record.
Cbx_SelectTerritory.InsertItem recList, _
selObjID, TRUE
Else
Cbx_SelectTerritory.InsertItem recList
End If
End Sub

See Also AppendItem method

RemoveItem method

366 InsertItem
ClearBasic Control Reference
 Select CBX control

method OwnsGrid

Syntax DoesOwn = Cbx_InstanceName.OwnsGrid

Applies To Select CBX

Description The OwnsGrid method returns a boolean indicating whether the Select CBX owns the
associated grid. Use this method for Select CBX controls that support multiple
contextual objects. The Select CBX owns the grid when it has a valid contextual object
and is displaying that object’s data in the grid.

Call this method before manipulating the contents of the grid. If this method returns
True, you must manipulate the grid contents through the Select CBX control. If this
method returns False, you may call the methods of the grid control directly.

Parameters None

Return Values Returns True if the Select CBX control owns the associated grid, otherwise returns
False.

See Also Grid control

OwnsGrid 367
ClearBasic Control Reference
 Select CBX control

method RefreshItem

Syntax Cbx_InstanceName.RefreshItem RecordID

Cbx_InstanceName.RefreshItem ListOfIDs

Applies To Select CBX

Description The RefreshItem method refreshes one or more records in the select-list grid with
information from the database. If you make temporary changes to one or more
records in a grid without saving the changes, you can use this method to restore the
original contents of those records.

When you call this method, you may specify a object ID or a list of object IDs. If a
given object ID does not correspond to a known record in the grid, this method does
nothing for that object ID.

Parameters This method accepts one of the following parameters:

Parameter Type Description

RecordID Long Specify the object ID of the record whose contents you want to
refresh.
ListOfIDs List Specify a list of Long integers, each of which contains the object
ID of a record you want to refresh.

Return Values None

See Also UpdateItem method

368 RefreshItem
ClearBasic Control Reference
 Select CBX control

method Regenerate

Syntax Cbx_InstanceName.Regenerate

Applies To Select CBX

Description The Regenerate method uses the current filters and sort criteria to perform a new
query and refresh the contents of the Select List grid. Calling this method is equivalent
to the user clicking the Select CBX control’s Find button.

If the adhoc row is currently enabled, this method uses the information in that row to
perform the query. If the adhoc row is disabled, this method performs the query using
the currently selected filter.

CAUTION: This method does not save changes to the database before running the new query. If
the records in the Select List grid contain changes you want to retain, you must save those
records to the database before calling this method.

After performing the query, this method clears the current selection and resets the
current record to the first record in the list. (This method does not clear the contents of
the adhoc row.) To change the current record, use the SetCurrent, GetNext, and
GetPrevious methods. To set the current selection, use the SetSelected or
SetSelectedById method.

Parameters None

Return Values None

Example The following example demonstrates the Click event handler of a button. When the
user clicks the button, this event handler refreshes the Select List grid associated with
the Select CBX instance SelectOpportunity.
Sub btn_RefreshList_Click
Cbx_SelectOpportunity.Regenerate
End Sub

See Also AppendDefaultSort method

AppendPreFilter method
GetNext method
GetPrevious method
SetCurrent method
SetSelected method
SetSelectedById method

Regenerate 369
ClearBasic Control Reference
 Select CBX control

method RejectAdhocCellEntry

Syntax Cbx_InstanceName.RejectAdhocCellEntry Message, DialogType

Applies To Select CBX

Description The RejectAdhocCellEntry method lets you abort the changes to a cell in the
adhoc row before they are saved to the grid’s contextual object. Depending on the
value you specify for the DialogType parameter, you can abort the changes directly or
let the user decide whether or not to abort them.

This method operates only on the most recently changed cell in the adhoc row. You
must call this method only from an AdhocCellChanged event handler. If you
specified a dialog type of cbAbortDisplayOK or cbAbortDisplayYesNo, the
control waits for your event handler to exit before posting the dialog. As a result, you
should always call this method at the end of your event handler.

If you abort the changes directly, or if the user chooses to abort the changes, this
method restores the original value of the cell. Restoring the original value does not
generate a new AdhocCellChanged event.

Parameters This method accepts the following parameters:

Parameter Type Description

Message String Specify the prompt message to display to the user. If you specify
cbAbortUndo for the DialogType parameter, this message is not
displayed to the user.
DialogType Long Specify the type of notification to give to the user. You must specify
one of the following constants:
Constant Description
cbAbortUndo Abort the changes without
notifying the user.
cbAbortDisplayOK Abort the changes and notify the
user with a dialog.
cbAbortDisplayYesNo Prompt the user to accept or
abort the changes.

Return Values None.

Example The following example implements the AdhocCellChanged event handler of the
grid called SelectGrid. If the user tries to specify a negative value in the quantity field
of the grid, this method rejects the change and notifies the user that the quantity must
be a positive value.
Sub SelectGrid_AdhocCellChanged
dim rowNum as Integer
dim fieldName as String
dim fieldData as String

370 RejectAdhocCellEntry
ClearBasic Control Reference
 Select CBX control

dim numItems as Integer

' Get the info for the cell that changed.

Cbx_SelectPart.GetChangedCell fieldName, fieldData

' Validate the cell’s contents.

If fieldName = "quantity" Then
numItems = Val(fieldData)
If numItems < 0 Then
Cbx_SelectPart.RejectAdhocCellChange _
"Invalid quantity. Enter a positive _
value.", cbAbortDisplayOK
End If
End If
End Sub

See Also AbortCellChange method (Grid control)

AdhocCellChanged method (Grid control)

RejectAdhocCellEntry 371
ClearBasic Control Reference
 Select CBX control

method RemoveItem

Syntax Cbx_InstanceName.RemoveItem RecordObjId

Cbx_InstanceName.RemoveItem ListOfObjIds

Applies To Select CBX

Description The RemoveItem method removes one or more records from the Select List grid and
updates the grid display. When calling this method, you must specify the object ID of
the records you want to remove. (You should not use this method to remove the
currently-selected records; use the RemoveSelected method instead.)

Calling this method does not delete the records from the database; it simply removes
them from the Select List grid. Running the same query again (by calling the
Regenerate method) reinstates the records in the Select List grid.

This method does not trigger any events.

Parameters This method accepts one of the following parameters:

Parameter Type Description

RecordObjId Long Specify the object ID (objid) of the record you want to remove
from the grid.
If you specify this parameter, you cannot specify the ListOfObjIds
parameter.
ListOfObjIds List Specify a list of long integers, each of which contains the object ID
(objid) of a record you want to remove from the grid.
If you specify this parameter, you cannot specify the
RecordObjId parameter.

Return Values None

Example The following example removes the first ten records in the Select List grid. The
example implements a Click event handler for a button. When clicked, the button
obtains the object IDs of the records and calls RemoveItem. If there are fewer than 10
records in the Select List grid, this method removes as many records as exist in the
grid.
Sub btn_RemoveRecord_Click
'Set up required variables
Dim recObjIdList As New List
Dim recordList as List
Dim tempRec as New Record
Dim recObjId As Long
Dim numItems As Long

' Get the entire list of items.

set recordList = Cbx_SelectPart.GetList

372 RemoveItem
ClearBasic Control Reference
 Select CBX control

numItems = recordList.Count

' Limit the number of removed items to 10

' If there are fewer than 10 elements,
' remove as many as there are.
If numItems > 10 Then
numItems = 10
End If

' Get the object IDs of the records.

For i=1 to numItems
recordList.GetItemByIndex i-1, tempRec
recObjId = tempRec.GetField("objid")

recObjIdList.AppendItem recObjId
Next

' Remove the records.

Cbx_SelectPart.RemoveItem recObjIdList
End Sub

See Also Regenerate method

RemoveSelected method

RemoveItem 373
ClearBasic Control Reference
 Select CBX control

method RemoveSelected

Syntax Cbx_InstanceName.RemoveSelected

Applies To Select CBX

Description The RemoveSelected method removes the currently-selected records from the
Select List grid and updates the grid display.

Calling this method does not delete the records from the database; it simply removes
them from the Select List grid. Running the same query again (by calling the
Regenerate method) reinstates the records in the result set and in the Select List
grid.

This method does not trigger any events.

Parameters None

Return Values None

Example The following example subroutine removes all records currently selected in the Select
List grid associated with the Select CBX instance SelectContract.

You realize the above functionality when you click the button whose internal name is
btn_RemSel.
Sub btn_RemSel_Click
Cbx_SelectContract.RemoveSelected
End Sub

See Also RemoveItem method

374 RemoveSelected
ClearBasic Control Reference
 Select CBX control

method ReplaceSelected

Syntax Cbx_InstanceName.ReplaceSelected Record

Applies To Select CBX

Description The ReplaceSelected method replaces the data in the currently selected record
with the data in the Record parameter. You can use this method to update the contents
of the selected record all at once rather than call the SetCellText method for each
field you want to change.

There must be only one record selected when you call this method. This method
replaces the values in the fields of the selected record with the corresponding values
from the Record parameter. All of the fields are replaced, with the exception of the
objid field.

NOTE: The method replaces the information in the Select List grid’s contextual object but does
not update the database. If you want to retain the changes, you must save the information to
the database in your code.

Parameters This method accepts the following parameter:

Parameter Type Description

Record Record Specify the record with which you want to replace the
currently selected record.
The objid field of this record is ignored.

Return Values None

Example The following example gets the currently selected case record, adds the keyword
“Clarify” to the keywords field, and replaces the record.
Sub btn_AddKeyword_Click
'Set up required variables
Dim myRecord As New Record
Dim myRecList As New List
Dim myKeywords as String

' Get the selected record

myResult = CBX_SelectCase.GetSelected (myRecord)

if myResult = True Then

myKeywords = myRecord.GetField(“keywords”)
myKeywords = myKeywords + “,Clarify”

myRecord.SetField(“keywords”, myKeywords)

ReplaceSelected 375
ClearBasic Control Reference
 Select CBX control

'Replace the record currently selected in the

'Select List grid associated with the Select CBX
'instance SelectCampaign.
Cbx_SelectCampaign.ReplaceSelected myRecord
End If
End Sub

376 ReplaceSelected
ClearBasic Control Reference
 Select CBX control

method ResetDefaultSort

Syntax Cbx_InstanceName.ResetDefaultSort

Applies To Select CBX

Description The ResetDefaultSort method clears all of the sort criteria that were set using the
AppendDefaultSort method. You can use this method to clear any old sort criteria
before installing new sort criteria using the AppendDefaultSort method.

Parameters None

Return Values None

Example The following example shows the Click event handler for a button. The event
handler clears the sorting criteria associated with the Select CBX instance
SelectInvCnt. After clearing the criteria, the event handler runs the query again, at
which time the records are displayed in the order they were returned from the
database.
Sub btn_ResetDefSort_Click
Cbx_SelectInvCnt.ResetDefaultSort
CBX_SelectInvCnt.Regenerate
End Sub

See Also AppendDefaultSort method

ResetDefaultSort 377
ClearBasic Control Reference
 Select CBX control

method ResetPreFilter

Syntax Cbx_InstanceName.ResetPreFilter

Applies To Select CBX

Description The ResetPreFilter method clears all of the prefilters associated with the Select
CBX instance. This method does not clear any filters the user created in the Filter Set
window or in the adhoc row.

To selectively remove one or more filters, use the ClearPreFilter method instead.

Parameters None

Return Values None

Example The following example implements a Click event handler that removes the prefilters
associated with the Select CBX control. This event handler clears the prefilters and
then runs the query again, displaying the unfiltered records in the Select List grid.
Sub btn_ResetPreFil_Click
Cbx_SelectInvCnt.ResetPreFilter
Cbx_SelectInvCnt.Regenerate
End Sub

See Also AppendPreFilter method

ClearPreFilter method

378 ResetPreFilter
ClearBasic Control Reference
 Select CBX control

method SelectedList

Syntax YourList = Cbx_InstanceName.SelectedList CObjName

Applies To Select CBX

Description The SelectedList method returns a list containing zero or more record objects.
Each record in the list is a copy of a selected record in the Select List grid. Because
each record is a copy of the original, changes to the returned records do not affect the
data in the grid’s contextual object.

This method supports Select CBX controls with multiple contextual objects. If you
specify a value for the CObjName parameter, this method returns the selected records
in the specified contextual object. If you omit the CObjName parameter, this method
returns the selected records for the control’s current contextual object.

NOTE: Because of paging restrictions, the selection returned by this method never extends
beyond page boundaries.

If the Select List grid supports the selection of only one record at a time, you may use
the GetSelected method to retrieve the current selection instead.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Optionally, specify a contextual object name. If you specify a non-
empty string for this parameter, this method looks for a contextual
object with the specified name; otherwise, it uses the current
contextual object.

Return Values This method returns a list of the currently selected records. Each record in the list is a
copy of the original record.

Example The example subroutine shown below copies the records currently selected in the
Select List grid associated with the Select CBX instance SelectContract to the list
variable myRecList
Sub btn_GetSelList_Click
'Set up required variables
Dim myRecList As List
Set myRecList = Cbx_SelectContract.SelectedList

'Any additional code goes here

'...
End Sub

SelectedList 379
ClearBasic Control Reference
 Select CBX control

See Also GetSelected method

Regenerate method

380 SelectedList
ClearBasic Control Reference
 Select CBX control

method SetAdhocCellReadOnly

Syntax Cbx_InstanceName.SetAdhocCellReadOnly FieldName, ReadOnly

Applies To Select CBX

Description The SetAdhocCellReadOnly method sets the read-only status of a cell in the adhoc
row. You can use this method to prevent the user from entering search criteria for
specific fields.

The read-only status of a cell remains until the form is dismissed or until you change
it again using this method.

Parameters This method accepts the following parameters:

Parameter Type Description

FieldName String Specify the name of the field corresponding to the column
containing the desired cell. The cell’s row is automatically
assumed to be the adhoc row.
ReadOnly Boolean Specify True if the cell is read-only, otherwise False to allow
editing.

Return Values None.

See Also SetCellReadOnly method (Grid control)

SetAdhocCellReadOnly 381
ClearBasic Control Reference
 Select CBX control

method SetAdhocCellText

Syntax Cbx_InstanceName.SetAdhocCellText FieldName, CellData

YourInt = Cbx_InstanceName.SetAdhocCellText FieldName, CellData

Applies To Select CBX

Description The SetAdhocCellText method sets the value for the specified cell in the adhoc
row, even if the cell is not editable. After setting the new value, this method generates
an AdhocCellChanged event.

The length of the new data string must not exceed the maximum length allowed by
the cell’s field. You may set the cell text to the empty string, even if the field’s
Required property is set to True. Setting the cell text to the empty string eliminates
the field from the search criteria.

Parameters This method accepts the following parameters:

Parameter Type Description

FieldName String Specify the name of the field corresponding to the cell. The
row of the cell is automatically assumed to be the adhoc row.
CellData String Specify the new data to assign to the cell.

Return Values Returns one of the following values to indicate the result of the operation:

Value Result
0 The method successfully set the value of the cell.
1 The method was unable to set the text of the cell because the cell is not
currently visible.
2 The method was unable to set the text of the cell because the specified
cell could not be found or the control ID was invalid.

See Also SetCellText method (Grid control)

AdhocCellChanged event (Grid control)

382 SetAdhocCellText
ClearBasic Control Reference
 Select CBX control

method SetCObj

Syntax Cbx_InstanceName.SetCObj CObjName

Applies To Select CBX

Description The SetCObj method sets the contextual object used by the Select CBX control and its
Select List grid. The contextual object you specify must be a source contextual object
for the Select List grid. The name you specify for the CObjName parameter must
match the name of an existing contextual object on the same form as the Select CBX
control. If no contextual object with the given name exists, this method generates a
runtime error.

This method applies only to Select CBX controls that support multiple contextual
objects. For information on creating Select CBX controls that support multiple
contextual objects, see the User Interface Editor Guide.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Specify the name of the desired contextual object. This name
must not include the string "CObj_" normally added when
referring to the contextual object in your code.

Return Values None

See Also GetCObj method

SetCObj 383
ClearBasic Control Reference
 Select CBX control

method SetCurrent

Syntax Cbx_InstanceName.SetCurrent RecordObjId, RecordIndex,

SelectRecord, TotalRecords

Applies To Select CBX

Description The SetCurrent method marks a record as the “current,” or “reference,” record in
the Select List grid. You can use this method in conjunction with the GetNext and
GetPrevious methods to navigate the list of records in the Select List grid.

NOTE: By default, the first record in the Select List grid is marked as the current record.

The current record does not necessarily correspond to the selected record. Your
application uses the current record as an internal marker, whereas the selected record
is refers to which row is highlighted in the user interface. However, if you specify True
for the SelectRecord parameter, this method selects the current record in the user
interface.

If you provide variables for the RecordIndex and RecordsInList parameters, this
method returns the index of the current record and the total number of records in
those parameters.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordObjId Long Specify the object ID (objid) of the record you want to mark as
the current record.
RecordIndex Long Specify an empty variable of type Long. On return, this variable
contains the row index of the current record.
This index is relative to the beginning of the current page.
SelectRecord Long Specify 1 if you want to select the record in addition to
designating it as the current record; otherwise, specify 0.
This parameter is optional and is set to 1 by default.
TotalRecords Long Specify an empty variable of type Long. On return, this variable
contains the number of records currently displayed in the Select
List grid.

Return Values None

384 SetCurrent
ClearBasic Control Reference
 Select CBX control

Example The following example displays information about the record immediately after the
selected record. This method uses the SetCurrent and GetNext methods to get the
record immediately after the selected record.
Sub btn_SetCurRec_Click
'Set up required variables
Dim nextRecord As New Record
Dim selRecord as New Record
Dim recIndex As Long
Dim recObjId As Long
Dim recTotal As Long
Dim myResult As Boolean

' Mark the selected record as the current record.

myResult = Cbx_SelectTerritory.GetSelected(selRecord)

if myResult = TRUE Then

Cbx_SelectTerritory.SetCurrent _
selRecord.GetField(“objid”), recIndex, 1, recTotal

' Get the record after the selection

Set nextRecord = Cbx_SelectTerritory.GetNext _
(recObjId, recIndex, recTotal)

'Display details about the next record in the

'Debug Print window
Debug.Print nextRecord
Debug.Print "ObjId of nextRecord: ", _
’recObjId
Debug.Print "Index of nextRecord: ", _
recIndex
Debug.Print "Total records in list: ", _
recTotal
End If
End Sub

See Also GetNext method

GetPrevious method
Regenerate method

SetCurrent 385
ClearBasic Control Reference
 Select CBX control

method SetSelected

Syntax Cbx_InstanceName.SetSelected RecordIndex

Applies To Select CBX

Description The SetSelected method selects the record at the specified index in the Select List
grid. Normally, the user selects records using the interface of the Select List grid, but
you can use this method to set the selection programmatically.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordIndex Long Specify the row index of the record you want to select. This
index is relative to the beginning of the current page. The index
is 0 based, that is, the first record is at index 0, the second at
index 1, and so on.

Return Values None

Example The following example implements a Click event handler that iterates through the
first 8 records in the grid. For each record, the example selects the record and
performs
Sub btn_SetSelRec_Click
'Set up required variables
Dim recIndex As Long
Dim myResult As Long

For i= 1 to 8
Cbx_SelectTerritory.SetSelected i

'The code to process each record goes here:

myResult = MyProcessSelectedRec()
Next i
End Sub

See Also SetSelectedById method

UnSelect method

386 SetSelected
ClearBasic Control Reference
 Select CBX control

method SetSelectedById

Syntax Cbx_InstanceName.SetSelectedById RecordObjId

Applies To Select CBX

Description The SetSelectedById method selects the record with the specified object ID in the
Select List grid. Normally, the user selects records using the interface of the Select List
grid, but you can use this method to set the selection programmatically.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordObjId Long Specify the object ID (objid) of the record you want to select.

Return Values None

Example The following example changes the selection to the next current record. It gets this
record using the GetNext method and then uses the object ID of the record to set the
selection.
Sub btn_SelRecById
Dim nextRecord as Record
Dim recObjId as Long
Dim recIndex as Long
Dim recTotal as Long

Set nextRecord = Cbx_SelectTerritory.GetNext _

(recObjId, recIndex, recTotal)

Cbx_SelectTerritory.SetSelectedById recObjId

'Any additional code goes here

'...
End Sub

See Also SetSelected method

UnSelect method

SetSelectedById 387
ClearBasic Control Reference
 Select CBX control

method UnSelect

Syntax Cbx_InstanceName.UnSelect

Applies To Select CBX

Description The UnSelect method deselects all currently selected records in the Select List grid.

Parameters None

Return Values None

Example The following sample subroutine deselects all currently selected records in the multi-
Select List grid associated with the Select CBX instance SelectOpportunity.

You realize the above functionality when you click the button whose internal name is
btn_NoSelect.
Sub btn_NoSelect_Click
Cbx_SelectOpportunity.UnSelect
End Sub

See Also SetSelected method

SetSelectedById method

388 UnSelect
ClearBasic Control Reference
 Select CBX control

method UpdateItem

Syntax Cbx_InstanceName.UpdateItem Record

Cbx_InstanceName.UpdateItem ListOfRecords

Applies To Select CBX

Description The UpdateItem method updates one or more records in the select-list grid. This
method modifies only the contents of the grid and does not update the record
information stored in the database.

When you call this method, you may specify a single record or a list of records. This
method uses the object ID of each specified record to locate the corresponding record
in the grid. If a record with the specified ID does not exist in the grid, this method
does nothing.

This method updates every field of the record in the grid. If you want to change the
value of only one or two fields, get the original record from the grid and modify it
directly.

Parameters This method accepts one of the following parameters:

Parameter Type Description

Record Record Specify the record whose contents you updated. Each record must
have a valid object ID.
ListOfRecords List Specify a list of Record objects, each of which contains a record
whose contents you updated. Each record must have a valid object
ID

Return Values None

Example The following example updates the Name field of the selected record in the select-list
grid.
Sub btn_UpdateSelected_Click
Dim myRec as New Record
Dim bItemFound as Boolean

bItemFound = CBX_myCBXInst.GetSelected(myRec)

if (bItemFound = TRUE Then

’ Modify the Name field of the record.
myRec.SetField "Name", "Fred"
CBX_myCBXInst.UpdateItem myRec
End If
End Sub

UpdateItem 389
ClearBasic Control Reference
 Select CBX control

See Also RefreshItem method

390 UpdateItem
ClearBasic Control Reference
 Slider control

Description A slider control lets the user select a discrete value or consecutive set of values from
within a fixed range. The control consists of a rectangular area (with optional tick
marks) and a slider which indicates the currently selected value. The user can move
the slider by dragging it, by clicking to either side of it, or by using the keyboard
arrows when the control has the focus.

When the user moves the slider using the mouse or keyboard, the Slider control sends
two events to the underlying form: a Scroll event and a Change event. The Scroll event
indicates that the slider moved, either due to a mouse action or a key press. The
subsequent Change event then reports the new value of the Slider control.

You set the appearance and orientation of the Slider control using the User Interface
Editor. You can set the minimum and maximum values of the slider and you can set
the type and frequency of tick marks displayed along the axis of the control.

Referring to Slider You cannot create control objects directly using ClearBasic code. You must associate
Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the slider
control called YourSliderControl:
Dim YourControl As Control
Set YourControl = YourSliderControl

Source You can link a Slider to a contextual object to get the current value of the slider. The
slider obtains its initial value from the destination contextual object you specify using
the User Interface Editor.

You can also set the initial value of the slider using ClearBasic code by assigning a
value to the Value property of the slider control.

Destination When the user changes the value of the slider, the Slider control updates the value in
the destination contextual object. If no contextual object is associated with the slider,
you can obtain the resulting value from the slider’s Value property.

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ Refresh method [C]
■ SetFocus method [C]

ClearBasic Control Reference

 Slider control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ Max property
■ Min property
■ Name property [C]
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

Events This object supports the following events. Events marked with a [C] are documented
with the Control object.
■ Change event
■ GotFocus event [C]
■ LostFocus event [C]
■ Scroll event

392
ClearBasic Control Reference
 Slider control

property Max

Syntax YourValue = YourControl.Max

YourControl.Max = NewValue

Applies To Slider control

Description The Max property contains a Long value representing the maximum value applicable
to the slider control.

This property is readable and writable. The value in this property must be greater
than the value in the Min property.

See Also Min property

Value property

Max 393
ClearBasic Control Reference
 Slider control

property Min

Syntax YourValue = YourControl.Min

YourControl.Min = NewValue

Applies To Slider control

Description The Min property contains a Long value representing the minimum value applicable
to the slider control.

This property is readable and writable. The value in this property must be less than
the value in the Max property.

See Also Max property

Value property

394 Min
ClearBasic Control Reference
 Slider control

property Value

Syntax YourValue = YourControl.Value

YourControl.Value = NewValue

Applies To Slider control

Description The Value property contains a long integer value representing the current value
assigned to the control. You can set the value of the slider programmatically by
modifying the value in this property. This value must lie between the minimum and
maximum values you specified on the control’s property sheet using the User
Interface Editor.

This property is readable and writable. At runtime, if the control is associated with a
contextual object, the control copies this value to the contextual object.

See Also Change event

Value 395
ClearBasic Control Reference
 Slider control

event Change

Syntax Sub YourControl_Change

Applies To Slider control

Description The Change event occurs when the value associated with the Slider control changes.
When you receive this event, you can check the current value of the control and
respond to the change.

To set a new value for the slider, assign a new value to the slider’s Value property.

Example In the following example, Change events to the Slider control are intercepted for
debugging purposes. When the position of the slider changes, the new value is
printed.
Sub Slider1_Change()
DIM lnum as long
Debug.Print "Slider Change"
lnum = Slider1.Value
Debug.Print lnum
End Sub

See Also Value property

Scroll event

396 Change
ClearBasic Control Reference
 Slider control

event Scroll

Syntax Sub YourControl_Scroll

Applies To Slider control

Description The Scroll event occurs when the user moves the slider using either the mouse or
keyboard. This event only indicates that the slider moved and does not imply that the
value of the control changed.

Example In the following example, Scroll events to the Slider control are intercepted for
debugging purposes. When the position of the slider changes, the value of the control
is printed and then assigned to the TextBox1 control.
Sub Slider1_Scroll()
DIM lnum as long
Debug.Print "Slider Scroll"
lnum = Slider1.Value
Debug.Print lnums
TextBox1.Value = lnum
End Sub

See Also Change event

Scroll 397
ClearBasic Control Reference
 Slider control

398 Scroll
ClearBasic Control Reference
 Tab Button control

Description The tab button control coordinates the display of a child window from a parent
window. When you design a parent form, you must add a tab button for each child
window you plan to display. The tab button contains information about the position
of the tab window relative to its parent and also controls aspects of the tab’s display,
such as its style and visibility.

When you add a tab button to a form, you must specify the form ID for the window
you want to associate with the tab. The form you specify must be a child form of the
parent form.

At runtime, you can use the properties of the tab button control to access information
about the position and settings of the tab. You can also use the control’s Value
property to select the tab using ClearBasic code.

Referring to Tab You cannot create control objects directly using ClearBasic code. You must associate
Button Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the slider
control called YourSliderControl:
Dim YourControl As Control
Set YourControl = YourSliderControl

Methods This object supports the following methods. Methods marked with [C] are
documented with the Control object.
■ Refresh method [C]

ClearBasic Control Reference

 Tab Button control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ DataChanged property
■ Enabled property [C]
■ Height property [C]
■ hWnd property[C]
■ Id property [C]
■ Left property [C]
■ Name property [C]
■ Parent property
■ Tag property
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

Events This object supports the following events. Events marked with [C] are documented
with the Control object.
■ Click event

400
ClearBasic Control Reference
 Tab Button control

property DataChanged

Syntax ChangedBool = YourControl.DataChanged

YourControl.DataChanged = ChangedBool

Applies To Tab Button

Description The DataChanged property contains a boolean value indicating whether the user
modified the contents of this control. This value only indicates whether modifications
were made by the user; it does not reflect changes made to the control by your
ClearBasic code.

If you modify the control programmatically, you can set this property to reflect your
changes. Set this property to True to indicate you made modifications; otherwise, set it
to False to indicate the control is unchanged.

DataChanged 401
ClearBasic Control Reference
 Tab Button control

property Parent

Syntax Set YourForm = YourTab.Parent

Applies To Tab Button

Description The Parent property returns the form that contains the control. This property is read-
only.

402 Parent
ClearBasic Control Reference
 Tab Button control

property Tag

Syntax YourTab.Tag = "YourStringHere"

TagText = YourTab.Tag

Applies To Tab Button

Description The Tag property contains a custom string that you can assign at runtime. You can
use this string to identify the object internally in your application. You can also use
this property to store extra information about the object.

Tag 403
ClearBasic Control Reference
 Tab Button control

property Value

Syntax YourTab.Value = Setting

Setting = YourTab.Value

Applies To Tab Button

Description The Value property contains a long integer indicating whether the tab is currently
active. If the value is 1, the tab is active. If the value is 0, the tab is not active.

Assigning the value 1 to this property makes the tab active. You must use this
property to activate tab buttons that do not have a title banner (because there is no tab
for the user to click).

404 Value
ClearBasic Control Reference
 Tab Button control

event Click

Syntax Sub YourControl_Click

Applies To Tab Button

Description The Click event occurs when the user presses and releases the mouse button with
the cursor on or in the control. You can use this event to respond to user interactions
with the control.

Click 405
ClearBasic Control Reference
 Tab Button control

406 Click
ClearBasic Control Reference
 Text Box control

Description This control allows the user to view or input a single line of text information. (The text
box control is similar to the multiline text box control except that the multiline control
accepts/displays more than one line of text and supports scrolling.)

You use this control to display a single line of text, accept a single line of text from the
user, or accept user input in order to process the information and display a response.

Referring to Text You cannot create control objects directly using ClearBasic code. You must associate
Box Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the text box
control called YourTextBoxControl:
Dim YourControl As Control
Set YourControl = YourTextBoxControl

Context-Sensitive This control supports the display of a context-sensitive menu. The control
Menu Support automatically provides several control-related menu items to allow the user to cut,
copy, and paste text. You may add additional menu items using the methods of this
control.

If you add context-sensitive menu items to a control, you must provide an event
handler to respond to the selection of your menu items. The ContextMenu_Select
event handler lets you handle the selection of all your context-sensitive menu items.
You may also implement a ContextMenuDisplaying event handler to modify the
state of your menu items immediately before the menu is displayed.

Source You cannot link a source contextual object to this control.

Destination The text supplied by the user or programmatically supplied by your code is returned
to the destination contextual object.

Control Label This control does not contain a label. You may create a label control and place it next
to this control.

ClearBasic Control Reference

 Text Box control

Methods This object supports the following methods. Methods marked with [C} are
documented with the Control object.
■ AppendContextMenu method
■ ClearContextMenu method
■ SetContextMenuEnabled method
■ SetContextMenuVisible method
■ Refresh method [C]
■ SetFocus method [C]

Properties This object supports the following properties. Properties marked with [C} are
documented with the Control object.
■ BackColor property
■ ControlType property [C]
■ DataChanged property
■ Enabled property [C]
■ ForeColor property
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ MaxLength property
■ MultiLine property
■ Name property [C]
■ Parent property
■ Required property
■ RequiredColor property
■ SelLength property
■ SelStart property
■ SelText property
■ Tag property
■ Text property
■ Top property [C]
■ Value property
■ Visible property [C]

408
ClearBasic Control Reference
 Text Box control

Events This object supports the following events. Events marked with [C} are documented
with the Control object.
■ Click event
■ ContextMenuDisplaying event
■ ContextMenu_Select event
■ GotFocus event [C]
■ KeyPress event
■ LostFocus event [C]

Deprecated Events The following event has changed. The old event is still supported for compatibility
but its use is discouraged. Use the new event instead.

Old Event Name New Event Name

<MenuItem> event ContextMenu_Select event

409
ClearBasic Control Reference
 Text Box control

method AppendContextMenu

Syntax YourControl.AppendContextMenu ItemName, ItemLabel, AppMenuName,

Separator

Applies To Text Box

Description The AppendContextMenu method adds a new menu item to the end of the control’s
context-sensitive menu. You can use this method to supplement the menu items
specified using the User Interface Editor.

In addition to adding menu items, you can use this method to add a separator after an
existing menu item. To add a separator, specify True for the Separator parameter.

The menu items you add using this method are enabled and visible initially. To
change the appearance of an item, call the SetContextMenuEnabled or
SetContextMenuVisible method. You can also add code to a
ContextMenuDisplaying event handler to update the appearance of menu items
dynamically.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify an identification string for the menu item. Your
application uses this string to identify the menu item when
calling menu-related methods. This name does not have to
be the same as the menu item’s label.
ItemLabel String Specify the menu-item label. This is the string the user sees
in the menu.
AppMenuName String Specify the menu name associated with the context-
sensitive menu, if any.
Specify a value for this parameter only if the menu item is
already associated with one of the application menus.
Specifying the application menu name prevents the creation
of duplicate menu items.
If the menu item is unique, specify an empty string ("") for
this parameter.
Separator Boolean Specify True if the item should be a separator, otherwise
False. If you specify True for this parameter, the ItemLabel
and AppMenuName parameters are ignored.

Return Values None

410 AppendContextMenu
ClearBasic Control Reference
 Text Box control

Example The following example adds two new items to the context-sensitive menu associated
with a text box control. The new items allow the user to select all of the text in the
control and to deselect whatever is currently selected.
Sub Form_Load
Dim numSelItems As Integer
Dim numTotalItems As Integer

' Add two new menu items for selecting

' everything and nothing.
TextBoxCtl.AppendContextMenu "cntxSelectAll", _
"Select All", "", FALSE
TextBoxCtl.AppendContextMenu _
"cntxSelectNone", "Select None", "", _
FALSE

End Sub

See Also SetContextMenuEnabled method

SetContextMenuVisible method
ContextMenuDisplaying event

AppendContextMenu 411
ClearBasic Control Reference
 Text Box control

method ClearContextMenu

Syntax YourGrid.ClearContextMenu

Applies To Text Box

Description The ClearContextMenu method removes custom menu items from the control’s
context-sensitive menu. This method removes only menu items that were added
using the AppendContextMenu method of the control. This method does not remove
application-specific menu items or menu items added in the User Interface Editor.

Parameters None

Return Values None

See Also AppendContextMenu method

412 ClearContextMenu
ClearBasic Control Reference
 Text Box control

method SetContextMenuEnabled

Syntax YourControl.SetContextMenuEnabled ItemName, Enabled

Applies To Text Box

Description The SetContextMenuEnabled method enables or disables a menu item in a

context-sensitive menu. Disabled menu items are displayed in the menu but cannot be
selected by the user. Enabled menu items can be selected and generate an appropriate
menu item event.

You can call this method from a ContextMenuDisplaying event handler to adjust
the appearance of the items in the menu. The enabled state of the item does not
change until you call this method again.

You may use this method to modify both permanent menu items and those added
using the AppendContextMenu method. To set the default enabled state of a
permanent menu item, you must modify the item’s entry in the Clarify User Interface
Editor.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify the identification string of the desired menu item. This is
the string you assigned to the item in the Clarify User Interface
Editor or using the AppendContextMenu method.
Visible Boolean Specify True to enable the menu item; specify False to disable it.

Return Values None

See Also AppendContextMenu method

SetContextMenuVisible method
ContextMenuDisplaying event
ContextMenu_Select event

SetContextMenuEnabled 413
ClearBasic Control Reference
 Text Box control

method SetContextMenuVisible

Syntax YourControl.SetContextMenuVisible ItemName, Visible

Applies To Text Box

Description The SetContextMenuVisible method sets the visibility of a menu item in a

context-sensitive menu. The visibility of a menu item determines whether or not the
item appears in the menu. Calling this method with the Visible parameter set to False
removes the item from the menu. Specifying True for the Visible parameter displays
the item to its original place in the menu.

You can call this method from a ContextMenuDisplaying event handler to adjust
the appearance of the items in the menu. The visible state of the item does not change
until you call this method again.

You may use this method to modify both permanent menu items and those added
using the AppendContextMenu method. To set the default visible state of a
permanent menu item, you must modify the item’s entry in the Clarify User Interface
Editor.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify the identification string of the desired menu item. This
is the string you assigned to the item in the Clarify User
Interface Editor or using the AppendContextMenu method.
Visible Boolean Specify True to make the menu item visible; specify False to
hide it.

Return Values None

See Also AppendContextMenu method

SetContextMenuEnabled method
ContextMenuDisplaying event

414 SetContextMenuVisible
ClearBasic Control Reference
 Text Box control

property BackColor

Syntax YourControl.BackColor = "ColorLabel"

ControlColor = YourControl.BackColor

Applies To Text Box

Description The BackColor property allows you to set the background color of a control. You can
set this property directly for the control, or indirectly by setting the property on the
contextual object that is linked to the control.

Before using this property, you must establish a color scheme using either the
CreateColorScheme or SetColorScheme method.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored in UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The label
must be in the color scheme that is currently in effect for the form in which
you are performing color operations. (See CreateColorScheme and
SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the text box label and the textbox foreground text are assigned the
same color, red, and the background color for the text box is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", _
"Important", "Weak"

BackColor 415
ClearBasic Control Reference
 Text Box control

ColorList1.AppendItem "red", _
"cyan", "blue"

App.CreateColorScheme "Form2020", _
LabelList1,ColorList1
End Sub

Sub Form_Load
App.SetColorScheme "Form2020"

TextBox1_Label.ForeColor = "Urgent"
TextBox1.ForeColor = "Urgent"
TextBox1.BackColor = "Important"
End Sub

See Also RequiredColor property

CreateColorScheme method (App object in ClearBasic Object Reference)
SetColorScheme method (App object in ClearBasic Object Reference)

416 BackColor
ClearBasic Control Reference
 Text Box control

property DataChanged

Syntax RetBoolean = YourControl.DataChanged

YourControl.DataChanged = YourBoolean

Applies To Text Box

Description The DataChanged property contains a boolean value indicating whether the user
modified the contents of this control. This value only indicates whether modifications
were made by the user; it does not reflect changes made to the control by your
ClearBasic code.

If you modify the control programmatically, you can set this property to reflect your
changes. Set this property to True to indicate you made modifications; otherwise, set it
to False to indicate the control is unchanged.

DataChanged 417
ClearBasic Control Reference
 Text Box control

property ForeColor

Syntax YourControl.ForeColor = "ColorLabel"

ControlColor = YourControl.ForeColor

Applies To Text Box

Description The ForeColor property allows you to set the color of the control label text. You can
set this property directly for the control, or indirectly by setting the property on the
contextual object that is linked to the control.

Before using this property, you must establish a color scheme using either the
CreateColorScheme or SetColorScheme method.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored in UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The label
must be in the color scheme that is currently in effect for the form in which
you are performing color operations. (See CreateColorScheme and
SetColorScheme.)

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you set the color properties, you must create a color scheme and set it into
effect, as shown in the example. Only then can you color the object you want to color.
In this example, the text box label and the textbox foreground text are assigned the
same color, red, and the background color for the text box is set to cyan.
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", "Important",

"Weak"

418 ForeColor
ClearBasic Control Reference
 Text Box control

ColorList1.AppendItem "red", "cyan", "blue"

App.CreateColorScheme"Form2020",
LabelList1,ColorList1

End Sub

Sub Form_Load
App.SetColorScheme "Form2020"

TextBox1_Label.ForeColor = "Urgent"
TextBox1.ForeColor = "Urgent"
TextBox1.BackColor = "Important"
End Sub

See Also RequiredColor property

CreateColorScheme method (App object in ClearBasic Object Reference)
SetColorScheme method (App object in ClearBasic Object Reference)

ForeColor 419
ClearBasic Control Reference
 Text Box control

property MaxLength

Syntax YourControl.MaxLength = Length

Length = YourControl.MaxLength

Applies To Text Box

Description The MaxLength property contains a long integer indicating the maximum number of
bytes that may be displayed by the control. The value of this integer must be between
0 and 32000. (For UNIX-only implementations, this value may be between 0 and
64000.) This property is readable and writable.

You can use this property to obtain the initial design-time value specified in the User
Interface Editor. You may also change this value by assigning a new value to the
property. Any value you specify remains in effect until you change the property again
or until the current session ends.

420 MaxLength
ClearBasic Control Reference
 Text Box control

property MultiLine

Syntax IsMultiLine = YourControl.MultiLine

Applies To Text Box

Description The MultiLine property contains a boolean indicating whether the control is a
multiline control. For text boxes, this property always contains the value False.

This property is read-only.

See Also MaxLength property

MultiLine 421
ClearBasic Control Reference
 Text Box control

property Parent

Syntax Set YourForm = YourControl.Parent

Applies To Text Box

Description The Parent property contains the form object that owns the control. You can use this
property in to retrieve a reference to the form object containing the control.

This property is read-only.

422 Parent
ClearBasic Control Reference
 Text Box control

property Required

Syntax RetBoolean = YourBox.Required

Applies To Text Box

Description The Required property contains a boolean value indicating whether or not the user
must enter a value in the text box before dismissing the form. This property contains
the value True if the control is required, otherwise False.

This property is read-only. You must set this property at design time using the User
Interface Editor.

See Also RequiredColor property

Required 423
ClearBasic Control Reference
 Text Box control

property RequiredColor

Syntax YourControl.RequiredColor = "ColorLabel"

ColorLabel = YourControl.RequiredColor

Applies To Text Box

Description The RequiredColor property contains a color label indicating the background color
of a required textbox. Before setting this property, you must use
CreateColorScheme and SetColorScheme to create and set a color scheme for
the form in which the textbox is located.

This property is readable and writable. This property only applies to multiline text
box controls whose Required property is set to True. If the Required property is not
set to True, this property is ignored.

See Also BackColor property

ForeColor property
Required property
CreateColorScheme method (App object in ClearBasic Object Reference)
SetColorScheme method (App object in ClearBasic Object Reference)

424 RequiredColor
ClearBasic Control Reference
 Text Box control

property SelLength

Syntax YourControl.SelLength = YourLong

YourLong = YourControl.SelLength

Applies To Text Box

Description The SelLength property contains a long integer value indicating the number of
characters in the current selection. This property is readable and writable.

Changing the value in this property changes the length of the current selection. You
can use this property in combination with the SelStart property to select text in the
control.

See Also SelStart property

SelText property

SelLength 425
ClearBasic Control Reference
 Text Box control

property SelStart

Syntax YourControl.SelStart = Index

Index = YourControl.SelStart

Applies To Text Box

Description The SelStart property contains a long integer value indicating the location of the
current insertion point. Text typed by the user or entered programmatically is entered
before the character at the specified index. Indexes are 1 based, that is, the first
character is at index 1, the second at index 2, and so on.

If the SelLength property contains a value greater than 0, this property indicates the
beginning of a text selection. You can use this property in combination with
SelLength to select text in the control.

See Also SelLength property

SelText property

426 SelStart
ClearBasic Control Reference
 Text Box control

property SelText

Syntax YourControl.SelText = "String"

SelectedText = YourControl.SelText

Applies To Text Box

Description The SelText property contains a string with the text of the current selection. Getting
this property returns the selected text, setting it replaces the selected text with the
string you specify.

If no text is selected, this property contains an empty string (""). To determine if any
text is selected, check the SelLength property for a non-zero value.

See Also SelLength property

SelStart property

SelText 427
ClearBasic Control Reference
 Text Box control

property Tag

Syntax YourControl.Tag = "YourStringHere"

ControlTag = YourControl.Tag

Applies To Text Box

Description The Tag property contains a custom string that you assign at runtime. You can use
this string to identify the control internally to your application. You can also use this
property to store extra information about the control.

428 Tag
ClearBasic Control Reference
 Text Box control

property Text

Syntax YourControl.Text = "YourStringHere"

ControlText = YourControl.Text

Applies To Text Box

Description The Text property contains the complete text displayed by the text box control. The
text in this property is stored in the destination contextual object linked to the control.

This property is readable and writable. Setting this property replaces the text
currently in the control with the new string you specify. It also updates the contents of
the destination contextual object.

NOTE: This property behaves the same way as the Value property of the text box control.

Text 429
ClearBasic Control Reference
 Text Box control

property Value

Syntax ControlValue = YourControl.Value

YourControl.Value = NewValue

Applies To Text Box

Description The Value property contains the complete text displayed by the text box control. The
text in this property is stored in the destination contextual object linked to the control.

This property is readable and writable. Setting this property replaces the text
currently in the control with the new string you specify. It also updates the contents of
the destination contextual object.

430 Value
ClearBasic Control Reference
 Text Box control

event Click

Syntax Sub YourControl_Click

Applies To Text Box

Description The Click event handler for your multiline text box is called when the user presses
and releases the mouse button over the control. A Click event usually indicates the
positioning of the insertion point or the selection of text. You can use this event in
combination with the SelStart and SelLength properties to determine the new
selection.

See Also SelLength property

SelStart property

Click 431
ClearBasic Control Reference
 Text Box control

event ContextMenuDisplaying

Syntax Sub YourControl_ContextMenuDisplaying

Applies To Text Box

Description The ContextMenuDisplaying event notifies your control that its context-sensitive
menu is about to be displayed. Use this event to update the appearance of the menu
and its items. You can enable or disable items, set the visibility of items, or add items
to the menu as appropriate.

The control sends this event in response to a user request to display the context-
sensitive menu. The event is sent before the menu is displayed.

In your ContextMenuDisplaying event handler, modify the menu and its

appearance to reflect the current state of the control. For example, if your menu
contains a Select All command, you might want to disable the command if the entire
contents of the control are already selected.

See Also AppendContextMenu method

SetContextMenuEnabled method
SetContextMenuVisible method
ContextMenu_Select event

432 ContextMenuDisplaying
ClearBasic Control Reference
 Text Box control

event ContextMenu_Select

Syntax Sub YourControl_ContextMenu_Select (EventName)

Applies To Text Box

Description The ContextMenu_Select event notifies your application that the user chose an
item from the control’s context-sensitive menu. In your event handler, perform the
task associated with the menu item.

You must provide an event handler for each menu item you define in the context-
sensitive menu. You can define menu items at design time using the Clarify User
Interface Editor or at runtime using the AppendContextMenu method.

Parameters This event receives the following parameter:

Parameter Type Description

EventName String Contains the internal name you assigned to the event handler
using the User Interface Editor. If you used the
AppendContextMenu method to create the item, this
parameter contains the value you specified in the ItemName
parameter of that method.

See Also AppendContextMenu method

ContextMenuDisplaying event

ContextMenu_Select 433
ClearBasic Control Reference
 Text Box control

event KeyPress

Syntax Sub YourControl_KeyPress (YourKey As Integer)

Applies To Text Box

Description The KeyPress event occurs when the user presses an ASCII key or an extended
ASCII key in the control (when the control has the focus). Event handlers for this
event can perform tasks such as checking for valid characters.

The parameter YourKey returns the ASCII keycode for the key that was pressed.

To convert the parameter YourKey from ASCII into a character, use the function Chr:
Char = Chr (YourKey)

To convert the character back to ASCII use the Asc function:

YourKey = Asc(char)

Example The following code is part of an event procedure for a textbox that handles the
keypress for a plus "+" key event.
Sub SUB_BILLEXP_MOD_KeyPress(KeyAscii As Integer)
Dim increment As Boolean
increment = False

Debug.print "User entered ", KeyAscii, _

" Chr(", Chr(KeyAscii), ")"

If KeyAscii = Asc("+") Then

Debug.Print "Got a plus!!"
increment = True
End If
End Sub

434 KeyPress
ClearBasic Control Reference
 TreeView control

Description A TreeView control displays a hierarchical list of nodes and provides an interface for
manipulating those nodes. Each node consists of a label and an optional bitmap. If a
node has subnodes, the node can be expanded to display its subnodes and collapsed
to hide them again.

You use the methods of the TreeView control to add and remove nodes from the
hierarchical list. The control also defines methods for retrieving information about a
particular node and for assigning images to the nodes.

The TreeView control responds to clicks by calling one of several user-defined event
handlers. You can define a NodeClick event handler to respond to general clicks in
the control. If you want to know when a node is expanded or collapsed, define
Expand and Collapse event handlers, respectively.

Node Images In addition to displaying a text label, each node in the TreeView control can display a
custom icon. You can use icons to provide additional information about the content of
the node. For example, you can use a folder icon to represent a node that contains
other items.

The TreeView control loads individual icons from an image list that you specify using
the SetImageList method. You refer to an individual icon by referring to its index
in the image list.

You can associate two permanent icons with each node at design time. These two
icons represent the node when it is unselected and when it is selected. At runtime, you
can overlay additional icons on top of these permanent icons to add highlights.

Keyboard In addition to using the mouse, users can use the keyboard to navigate the list of
Navigation nodes in a TreeView control. The Up and Down arrow keys let you navigate around
all of the visible nodes, that is, all top-level nodes and the contents of all expanded
nodes. Typing one of these arrow keys moves the current selection up or down by one
entry.

If a collapsed node is currently selected, the user can expand the node by typing the
Right arrow key. Similarly, typing the Left arrow key on an expanded node, collapses
that node.

Users can jump to a node by typing the first letter of its label. Subsequent presses of
the same key cycle through all of the nodes beginning with that letter.

Referring to You cannot create control objects directly using ClearBasic code. You must associate
Treeview Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

ClearBasic Control Reference

 TreeView control

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the treeview
control called YourTreeviewControl:
Dim YourControl As Control
Set YourControl = YourTreeviewControl

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ Add method
■ Clear method
■ Expand method
■ GetItemText method
■ GetSelectedItem method
■ Key method
■ Remove method
■ SetFocus method [C]
■ SetImageList method
■ SetItemOverlayImage method
■ SetItemText method
■ SetOverlayImage method
■ SetSelectedItem method

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ Name property [C]
■ Top property [C]
■ Visible property [C]
■ Width property [C]

436
ClearBasic Control Reference
 TreeView control

Events This object supports the following events. Events marked with a [C] are documented
with the Control object.
■ Collapse
■ Expand
■ GotFocus [C]
■ LostFocus [C]
■ NodeClick

437
ClearBasic Control Reference
 TreeView control

method Add

Syntax NewNodeID = YourControl.Add (Relative, Relationship, Key, Text,

Image, SelectedImage)

Applies To TreeView

Description The Add method adds a node to the TreeView control. When you call this method,
specify a label and an optional bitmap image to represent the node. If you assign a key
value to the node, you can use that value to identify the node later.

If you specify values for the relative and relationship parameters, this method adds
the node at the specified position in the hierarchy. If you do not specify these
parameters, the node is added immediately after (and at the same level as) the
previously added node.

The bitmap images you associate with a node must reside in the control’s current
image list. To assign an image list to the control, call the SetImageList method.

Parameters The Add method accepts the following parameters:

Parameter Type Description

Relative String Specify the key (or ID) of another node. You use this
(or Long) parameter in conjunction with the relationship parameter to
specify the position of the new node in the TreeView control.
If you do not specify a value for this parameter, the new node
becomes the root node of the tree.
See the discussion following this table for more information.
Relationship Long Specify a value indicating the relationship between the node
being added and the node specified by the relative
parameter. See the discussion following this table for more
information.
This parameter is optional but should be specified if you
specified a value for the relative parameter.
Key String Specify a string that uniquely identifies the node.
This parameter is optional.
Text String Specify a string containing the text of the node label. Users
see this string in the TreeView control.
This parameter is optional.
Image Long Specify the index of an image in the associated image list.
Users see this image, along with the node text, when the node
is not selected in the TreeView control. See the SetImageList
method for more information.
This parameter is optional.
SelectedImage Long Specify the index of an image in the associated image list.
Users see this image, along with the node text, when the node
is selected in the TreeView control.
This parameter is optional.

438 Add
ClearBasic Control Reference
 TreeView control

The relative and relationship parameters work together to specify the position
of the new node in the TreeView control. The relative parameter contains the key
or ID of a node previously added to the treeview control. The following table lists the
acceptable values for the relationship parameter:

Value Position Description

0 First The node is placed before all other nodes whose level is the same
as the node in the relative parameter.
1 Last The node is placed after all other nodes whose level is the same as
the node in the relative parameter.
2 Next The node is placed immediately after (and at the same level as)
the node in the relative parameter. This is the default option.
3 Previous The node is placed immediately before (and at the same level as)
the node in the relative parameter.
4 Child The node becomes a child node of the node in the relative
parameter.

The image and selectedImage parameters are indexes into the image list
associated with the control. You associate an image list with the control by calling the
SetImageList method.

Return Values Returns a Long value containing the ID of the node that was added.

Example The following example initializes the TreeView control of the form by adding several
nodes. In this example, there is a top-level node with the label "Parent" and 3
subnodes. Two of those subnodes ("Child1" and "Child2") are direct children of
"Parent" while "Child3" is a subnode of "Child2".
Sub Form_Load()
Dim colorval, iconResId as Long

Me.DoDefault

colorval =16711935
iconResId = 180

num = 1
Cobj_test.Fill num

'Tree.SetImageList iconResId,16711935, 16
nodX = Tree.Add(, , "r", "Parent",1,2)
nodX = Tree.Add("r", 4, "child1",
"Child1",3,4)
nodX = Tree.Add("r", 4, "child2",
"Child2",5,6)
nodX = Tree.Add(nodX, 4, "child3",
"Child3",7,8)
End Sub

See Also Clear method

Remove method
SetImageList method

Add 439
ClearBasic Control Reference
 TreeView control

method Clear

Syntax YourControl.Clear

Applies To TreeView

Description The Clear method removes all of the nodes from the TreeView control.

Parameters None

Return Values None

See Also Add method

Remove method

440 Clear
ClearBasic Control Reference
 TreeView control

method Expand

Syntax YourControl.Expand NodeID, Options

Applies To TreeView

Description The Expand method expands or collapses the specified node. If the specified node
does not have any children—or is already in the given state—this method does
nothing.

In addition to simply expanding or collapsing a node, you can toggle its state by
specifying the value 3 for the options parameter. When you specify this option, this
method collapses an already expanded node or expands a collapsed node.

Parameters This method accepts the following parameters:

Parameter Type Description

NodeID Long Specify the ID of the node. This ID is the same value that was
returned by the Add method when you created the node.
Options Long Specify one of the following values:
Value Description
1 Collapse the node
2 Expand the node
3 Toggle the current state of the node

Return Values Returns True if the node’s state was successfully modified, otherwise False.

See Also Collapse event

Expand event

Expand 441
ClearBasic Control Reference
 TreeView control

method GetItemText

Syntax ItemText = YourControl.GetItemText (NodeID)

ItemText = YourControl.GetItemText (Key)

Applies To TreeView

Description The GetItemText method returns the text string associated with a node. This text
string corresponds to the string the user sees in the control display.

Parameters This method accepts the following parameters:

Parameter Type Description

NodeID Long Specify the ID of the node. This ID is the same value that was
returned by the Add method when you created the node.
If you specify this parameter, do not specify the Key parameter.
Key String Specify the key string associated with the node. This string is the
same string you passed to the key parameter of the Add method
when you created the node.
If you specify this parameter, do not specify the NodeID
parameter.

Return Values Returns a String containing the text of the specified item. If the specified item cannot
be found, this method returns an empty string ("").

See Also SetItemText method

442 GetItemText
ClearBasic Control Reference
 TreeView control

method GetSelectedItem

Syntax YourControl.GetSelectedItem

Applies To TreeView

Description The GetSelectedItem method returns the ID of the currently selected node.

Parameters None

Return Values Returns a Long value, which corresponds to the ID of the currently selected node. You
can pass this value to other methods to identify the given node.

See Also Add method

Key method

GetSelectedItem 443
ClearBasic Control Reference
 TreeView control

method Key

Syntax YourControl.Key NodeID

Applies To TreeView

Description The Key method returns the key string associated with a node. You would typically
use this method in conjunction with the GetSelectedItem method to determine the
key of the selected node.

Parameters This method accepts the following parameter:

Parameter Type Description

NodeID Long Specify the ID of the node. This ID is the same value that was
returned by the Add method when you created the node.

Return Values Returns the string that uniquely identifies the node. This string is the same string that
you supplied in the key parameter of the Add method.

See Also Add method

GetSelectedItem method

444 Key
ClearBasic Control Reference
 TreeView control

method Remove

Syntax YourControl.Remove NodeID

YourControl.Remove Key

Applies To TreeView

Description The Remove method removes the specified node from the TreeView control. If the
node contains any children, those nodes are removed as well.

Parameters This method accepts one of the following parameter:

Parameter Type Description

NodeID Long Specify the ID of the node. This ID is the same value that was
returned by the Add method when you created the node.
If you specify this parameter, do not specify the Key parameter.
Key String Specify the key string associated with the node. This string is the
same string you passed to the key parameter of the Add method
when you created the node.
If you specify this parameter, do not specify the NodeID
parameter.

Return Values Returns True if the node was removed, otherwise it returns False.

See Also Add method

Clear method

Remove 445
ClearBasic Control Reference
 TreeView control

method SetImageList

Syntax YourControl.SetImageList ResourceID, Mask, Size

YourControl.SetImageList FileName, Mask, Size

Applies To TreeView

Description The SetImageList method associates an image list with the TreeView control. The
control uses this image list to obtain the bitmaps associated with each node.

The image list you associate with the control is itself a bitmap image. You can obtain
this bitmap image either from the resource file that shipped with the CeFO
application or you can specify a separate bitmap file.

The image list itself is a series of icon bitmaps arranged horizontally in the bitmap file.
The width and height of each icon must be identical to the value in the size parameter.
The TreeView control assigns each icon an index number corresponding to its order in
the bitmap. The first icon is at index 0, the second at index 1 and so on.

Parameters This method accepts the following parameters:

Parameter Type Description

ResourceID Long Specify the resource ID of the desired bitmap. This bitmap must
reside in the resdll.dll file that comes with the CeFO client
application.
If you specify this parameter, do not specify the FileName
parameter.
FileName String Specify the Windows pathname for the desired bitmap file (.bmp).
You can specify a relative or full pathname for this parameter.
If you specify this parameter, do not specify the Id parameter.
Mask Long Specify an RGB color value that matches the background color of
the icons in the image list.
This parameter is optional. See the discussion that follows this
table for more information.
Size Long Specify the size of each icon bitmap. The value you specify
indicates both the horizontal and vertical dimensions of each icon
bitmap.
If you do not specify this parameter, the default value of 16 is
assumed.

The TreeView control creates a mask bitmap for each icon in the image list. The control
uses these bitmaps to highlight the currently selected node. When applied to an icon,
the mask inverts some of the icon pixels to give the icon the appearance of being
selected.

The size of each mask bitmap is identical to the size of each icon bitmap. That is, the
size parameter specifies both the horizontal and vertical dimensions of the mask
bitmap. The pixels in the mask bitmap can be either black or white.

446 SetImageList
ClearBasic Control Reference
 TreeView control

The pixel values for each mask bitmap are calculated using the corresponding icon
bitmap and the color value specified in the mask parameter. All mask pixels are set to
the value 0 by default. If the color of an icon pixel matches the color specified in the
mask parameter, the corresponding mask pixel is set to 1. When the mask is applied to
the icon, the color of that icon pixel is set to black.

To specify a color value in the mask parameter, you must assign values for each red,
green, and blue component of the color. Each value must be between 0 and 255. You
can use the following equation to add the color values together and obtain the mask
color:
color = (blue * 65536) +
(green * 256) +
(red * 1)

For example, a shade of purple whose red and blue component values are 128 and
whose green component value is 0 would result in the mask value of 8388736, as
shown by the following calculations:
(128 * 65536) + (0 * 256) + (128 * 1) = 8388736

Return Values None

Example The following example initializes the TreeView control of the form by adding several
nodes. Before adding any nodes to the form’s TreeView control, this method assigns
an image list to that control. The color value specified in the colorval parameter
corresponds to an RGB value.
Sub Form_Load()
Dim colorval, iconResId as Long

Me.DoDefault

colorval = 16711935 '0x00FF00FF

iconResId = 100

num = 1
Cobj_test.Fill num

Tree.SetImageList iconResId, colorval, 16

nodX = Tree.Add(, , "r", "Parent",1,2)
nodX = Tree.Add("r", 4, "child1",
"Child1",3,4)
nodX = Tree.Add("r", 4, "child2",
"Child2",5,6)
nodX = Tree.Add(nodX, 4, "child3",
"Child3",7,8)
End Sub

See Also Add method

SetImageList 447
ClearBasic Control Reference
 TreeView control

method SetItemOverlayImage

Syntax YourBoolean = YourControl.SetItemOverlayImage (NodeID,

OverlayIndex)
YourBoolean = YourControl.SetItemOverlayImage (Key,
OverlayIndex)

Applies To TreeView

Description The SetItemOverlayImage method adds an overlay image to the icon of the
specified node. This method places the overlay image directly on top of the existing
node icon. The overlay image remains on top of the node icon until you call this
method again and specify the value 0 for the OverlayIndex parameter.

Before calling this method, you must register one or more overlay images with the
control. See the SetOverlayImage for information on how to register overlay
images.

Parameters This method accepts the following parameters:

Parameter Type Description

NodeID Long Specify the ID of the node. This ID is the same value that was
returned by the Add method when you created the node.
If you specify this parameter, do not specify the Key parameter.
Key String Specify the key string associated with the node. This string is
the same string you passed to the key parameter of the Add
method when you created the node.
If you specify this parameter, do not specify the NodeID
parameter.
OverlayIndex Long Specify the index of the overlay image. Specify 0 to clear the
current overlay image assigned to the node.
This is an index into the overlay image map and not into the
treeview image map. This index is one based, that is, the first
item is at index 1, the second at index 2, and so on.

Return Values Returns True if the node text was successfully set; otherwise, returns False to indicate
an error occurred.

See Also SetOverlayImage method

448 SetItemOverlayImage
ClearBasic Control Reference
 TreeView control

method SetItemText

Syntax YourBoolean = YourControl.SetItemText (NodeID, NewText)

YourBoolean = YourControl.SetItemText (Key, NewText)

Applies To TreeView

Description The SetItemText method assigns a new text string to the specified node. This text
string corresponds to the string the user sees in the control display.

Parameters This method accepts the following parameters:

Parameter Type Description

NodeID Long Specify the ID of the node. This ID is the same value that was
returned by the Add method when you created the node.
If you specify this parameter, do not specify the Key parameter.
Key String Specify the key string associated with the node. This string is the
same string you passed to the key parameter of the Add method
when you created the node.
If you specify this parameter, do not specify the NodeID
parameter.
NewText String Specify the new node text.

Return Values Returns True if the node text was successfully set; otherwise, returns False to indicate
an error occurred.

See Also GetItemText method

SetItemText 449
ClearBasic Control Reference
 TreeView control

method SetOverlayImage

Syntax YourBoolean = YourControl.SetOverlayImage (ImageIndex,

OverlayIndex)

Applies To TreeView

Description The SetOverlayImage method registers an existing image in the control’s image list
as an overlay image. Typically, you call this method several times from a Form_Load
procedure to establish which icons in the image list are to be used as overlay icons.
You must call this method before applying an overlay icon with the
SetItemOverlayImage method.

Parameters This method accepts the following parameters:

Parameter Type Description

ImageIndex Long Specify the index of the image you want to register as an overlay
image. The index you specify must refer to a valid image in the
current image list.
Indexes for this parameter are zero-based, that is, the first image
is at index 0, the second at index 1, and so on.
OverlayIndex Long Specify the index you want to apply to the overlay icon. Future
calls to SetItemOverlayImage must use this index when
referring to a particular icon.
The index you specify must be unique for each overlay icon
associated with the TreeView control. Valid index numbers
begin at 1 and continue up to the maximum positive long
integer value.

Return Values Returns True if the node text was successfully set; otherwise, returns False to indicate
an error occurred.

Example The following example initializes the TreeView control of the form and adds several
nodes. In addition to setting the image list used by the nodes, this routine also
registers every third icon in the image list as an overlay icon.
Sub Form_Load()
Dim colorval, iconResId as Long
Dim ret As Bool

Me.DoDefault

colorval = 16711935 '0x00FF00FF

iconResId = 100

' Initialize the TreeView control.

Tree.SetImageList iconResId, colorval, 16

450 SetOverlayImage
ClearBasic Control Reference
 TreeView control

' Register every third icon as an overlay

' icon.
ret = Tree.SetOverlayImage (3, 1)
ret = Tree.SetOverlayImage (6, 2)
ret = Tree.SetOverlayImage (9, 3)

' Add the nodes

nodX = Tree.Add(, , "parNode", "Parent",1,2)
nodX = Tree.Add("parNode", 4, "child1",
"Child1",4,5)
nodX = Tree.Add("parNode", 4, "child2",
"Child2",4,5)
nodX = Tree.Add(nodX, 4, "child3",
"Child3",7,8)
End Sub

See Also SetItemOverlayImage method

SetOverlayImage 451
ClearBasic Control Reference
 TreeView control

method SetSelectedItem

Syntax YourControl.SetSelectedItem NodeID

YourControl.SetSelectedItem Key

Applies To TreeView

Description The SetSelectedItem method selects the specified node of the TreeView control.
The TreeView control highlights the specified node and displays its selected image
icon as appropriate.

Parameters This method accepts one of the following parameters:

Parameter Type Description

NodeID Long Specify the ID of the node. This ID is the same value that was
returned by the Add method when you created the node.
If you specify this parameter, do not specify the Key parameter.
Key String Specify the key string associated with the node. This string is the
same string you passed to the key parameter of the Add method
when you created the node.
If you specify this parameter, do not specify the NodeID
parameter.

Return Values Returns True if the operation was successful, otherwise False.

See Also GetSelectedItem method

452 SetSelectedItem
ClearBasic Control Reference
 TreeView control

event Collapse

Syntax Sub YourControl_Collapse (nodeID as Long)

Applies To TreeView control

Description The Collapse event occurs when the user collapses a node in the TreeView control.

You can use this event notification to perform any additional tasks related to the
collapse of the node. You do not need to collapse the node yourself as that is handled
automatically by the ClarifyCRM eFrontOffice application.

Parameters The control passes the following parameter to your event handler:

Parameter Type Description

nodeID Long Contains the ID of the node that collapsed. This ID is the same
value that was returned by the Add method when you created
the node.

See Also Expand event

Collapse 453
ClearBasic Control Reference
 TreeView control

event Expand

Syntax Sub YourControl_Expand (nodeID as Long)

Applies To TreeView control

Description The Expand event occurs when the user expands a node in the TreeView control.

You can use this event notification to perform any additional tasks related to the
expansion of the node. You do not need to expand the node yourself as that is handled
automatically by the CeFO application.

Parameters The control passes the following parameter to your event handler:

Parameter Type Description

nodeID Long Contains the ID of the node that expanded. This ID is the same
value that was returned by the Add method when you created
the node.

See Also Expand method

Collapse event

454 Expand
ClearBasic Control Reference
 TreeView control

event NodeClick

Syntax Sub YourControl_NodeClick (nodeID as Long)

Applies To TreeView control

Description The NodeClick event occurs when the user clicks on a node in the TreeView control.

You can use this event notification to perform any additional tasks related to selecting
the node. You do not need to select the node yourself as that is handled automatically
by the CeFO application.

Parameters The control passes the following parameter to your event handler:

Parameter Type Description

nodeID Long Contains the ID of the node that was clicked. This ID is the
same value that was returned by the Add method when you
created the node.

See Also Collapse event

Expand event

NodeClick 455
ClearBasic Control Reference
 TreeView control

456 NodeClick
ClearBasic Control Reference
 UpDown control

Description The UpDown control consists of a pair of arrow buttons that the user clicks to
increment or decrement a value. Normally, you associate an UpDown control with
another control, called a "buddy control". When the user clicks on the arrows of the
UpDown control, the value in the buddy control is incremented or decremented
accordingly.

If an UpDown control does not have an associated buddy control, the UpDown control
functions as a simplified scroll bar. You use the events sent by the control to respond
to clicks in the control. For example, you can use an UpDown control on a form to
scroll additional tabs into view.

Referring to You cannot create control objects directly using ClearBasic code. You must associate
UpDown Controls controls with a form, frame, or tab using the User Interface Editor. When the form,
frame, or tab is subsequently displayed, the corresponding control object is created
automatically.

If you need to refer to a control object explicitly, such as when passing a control object
as a method parameter, use a variable of type Control to refer to the control object.
For example, you would use the following code to obtain a reference to the UpDown
control called YourUpDownControl:
Dim YourControl As Control
Set YourControl = YourUpDownControl

Methods This object supports the following methods. Methods marked with a [C] are
documented with the Control object.
■ SetFocus method [C]

ClearBasic Control Reference

 UpDown control

Properties This object supports the following properties. Properties marked with [C] are
documented with the Control object.
■ ControlType property [C]
■ Enabled property [C]
■ Height property [C]
■ hWnd property [C]
■ Id property [C]
■ Left property [C]
■ Max property
■ Min property
■ Name property [C]
■ Top property [C]
■ Value property
■ Visible property [C]
■ Width property [C]

Events This object supports the following events. Events marked with a [C] are documented
with the Control object.
■ Change event
■ DownClick event
■ GotFocus event [C]
■ LostFocus event [C]
■ UpClick event

458
ClearBasic Control Reference
 UpDown control

property Max

Syntax YourValue = YourControl.Max

YourControl.Max = NewValue

Applies To UpDown control

Description The Max property contains a long integer representing the maximum value applicable
to the UpDown control.

This property is readable and writable. The value in this property must be greater
than the value in the Min property.

See Also Min property

Value property

Max 459
ClearBasic Control Reference
 UpDown control

property Min

Syntax YourValue = YourControl.Min

YourControl.Min = NewValue

Applies To UpDown control

Description The Min property contains a long integer representing the minimum value applicable
to the UpDown control.

This property is readable and writable. The value in this property must be less than
the value in the Max property.

See Also Max property

Value property

460 Min
ClearBasic Control Reference
 UpDown control

property Value

Syntax YourValue = YourControl.Value

YourControl.Value = NewValue

Applies To UpDown control

Description The Value property contains a long integer representing the current value assigned
to the control. You can set the value of the UpDown control programmatically by
modifying the value in this property. If the control is associated with a buddy control,
setting this value also sets the value of the buddy control.

This property is readable and writable.

See Also Change event

Value 461
ClearBasic Control Reference
 UpDown control

event Change

Syntax Sub YourControl_Change

Applies To UpDown control

Description The Change event reports an updated value for the UpDown control. This event is
generated after an UpClick or DownClick event, even if clicking one of those
buttons does not result in a change to the control’s value.

The UpDown control automatically updates the contents of the buddy control upon
receipt of this event. You can use this event to perform any additional tasks required
by your application.

See Also DownClick event

UpClick event

462 Change
ClearBasic Control Reference
 UpDown control

event DownClick

Syntax Sub YourControl_DownClick

Applies To UpDown control

Description The DownClick event occurs when the user clicks the control’s down button. If the
UpDown control does not have a buddy control, you can use this event to trigger
additional events. For example, you can use this event to scroll through the tabs of a
form.

See Also UpClick event

DownClick 463
ClearBasic Control Reference
 UpDown control

event UpClick

Syntax Sub YourControl_UpClick

Applies To UpDown control

Description The UpClick event occurs when the user clicks the control’s up button. If the
UpDown control does not have a buddy control, you can use this event to trigger
additional events. For example, you can use this event to scroll through the tabs of a
form.

See Also DownClick event

464 UpClick
ClearBasic Control Reference
Appendix A
Supported Methods,
Properties, and Events

In This Chapter
Control and Method Matrix . . . . . . . . . . . . . . . . . . . 466
Control and Property Matrix . . . . . . . . . . . . . . . . . . 469
Control and Event Matrix. . . . . . . . . . . . . . . . . . . . . 471

ClearBasic Control Reference 465

 Supported Methods, Properties, and Events

Control and Method Matrix

Table 8 lists the ClearBasic controls and the methods supported by each.

Table 8 Supported methods for controls

Dropdown Combo Box

Dropdown List Box

Multiline Text Box

Command Button

Grid/Custom List

Option Button
ProgressBar
Select CBX

Tab Button
Check Box
Animation

TreeView
Text Box

UpDown
List Box
Control
Bitmap

Graph

Slider
Label
Object or Control >

Method
AbortCellChange •
AbortRowChange •
Add •
AppendAdhocFilter •
AppendContextMenu • • •
AppendDefaultSort •
AppendItem • • • • •
AppendPreFilter •
Clear • • • • •
ClearAdhocRow •
ClearAll •
ClearContextMenu • • •
ClearData •
ClearPreFilter •
Close •
ColorCells •
Contains • • • •
Down • • • •
EnableAdhoc •
Expand •
GenerateSQL •
GetAdhocRow •
GetChangedCell • •
GetChangedRow •
GetChoiceList •
GetChoiceListDefault •
GetChoiceListUserData •
GetCObj •
GetColumnControlType •
GetColumnMaxLength •
GetColumnNames •
GetCount •
GetItemText •

466 Control and Method Matrix

ClearBasic Control Reference
 Supported Methods, Properties, and Events

Table 8 Supported methods for controls (Continued)

Dropdown Combo Box

Dropdown List Box

Multiline Text Box

Command Button

Grid/Custom List

Option Button
ProgressBar
Select CBX

Tab Button
Check Box
Animation

TreeView
Text Box

UpDown
List Box
Control
Bitmap

Graph

Slider
Label
Object or Control >

Method
GetLabel •
GetLastError
GetLegend •
GetList • • • • •
GetNext •
GetPoint •
GetPrevious •
GetSelCount •
GetSelected • • • • •
GetSelectedColumns •
GetSelectedItem •
HideColumn •
InsertItem •
IsColumnEditable •
IsColumnRequired •
Key •
Open •
OwnsGrid •
Play •
Refresh • • • • • • • • • • • • •
RefreshItem •
Regenerate •
RejectAdhocCellEntry •
Remove •
RemoveByItem • • • •
RemoveItem • • • • •
RemoveSelected • • • • •
ReplaceItem • • • •
ReplaceSelected •
ResetDefaultSort •
ResetPreFilter •
SaveAnyChanges •
SelectedIndexes • • • •
SelectedList • • • • •
SetAdhocCellReadOnly •
SetAdhocCellText •

Control and Method Matrix 467

ClearBasic Control Reference
 Supported Methods, Properties, and Events

Table 8 Supported methods for controls (Continued)

Dropdown Combo Box

Dropdown List Box

Multiline Text Box

Command Button

Grid/Custom List

Option Button
ProgressBar
Select CBX

Tab Button
Check Box
Animation

TreeView
Text Box

UpDown
List Box
Control
Bitmap

Graph

Slider
Label
Object or Control >

Method
SetCellColoring •
SetCellFocus •
SetCellReadOnly •
SetCellText •
SetCObj •
SetContextMenuEnabled • • •
SetContextMenuVisible • • •
SetCurrent •
SetEditStates •
SetFocus • • • • • • • • • • • •
SetImageList •
SetItemOverlayImage •
SetItemText •
SetLabel •
SetLegend •
SetNewRowIndicator •
SetOverlayImage •
SetPoint •
SetRowReadOnly •
SetSelected • • • • •
SetSelectedById •
SetSelectedItem •
Stop •
UndoRowChanges •
UnSelect • • • • •
Up • • • •
UpdateItem •

468 Control and Method Matrix

ClearBasic Control Reference
 Supported Methods, Properties, and Events

Control and Property Matrix

Table 9 lists the ClearBasic controls and the properties supported by each. In the table,
R signifies Read-only, W signifies write-only, and ” • “ signifies both read and write at
run time.

Table 9 Supported properties for controls

Dropdown Combo Box

Dropdown List Box

Multiline Text Box

Command Button

Grid/Custom List

Option Button
ProgressBar
Select CBX

Tab Button
Check Box
Animation

TreeView
Text Box

UpDown
List Box
Control
Bitmap

Graph

Slider
Label
Object or Control >

Property
AppendRows R
BackColor • • • • •
BackStyle •
BorderStyle •
Caption • • • •
CObj •
ControlType R R R R R R R R R R R R R R R R R
DataChanged • • • • • • • • •
Default •
Dirty R
Enabled • • • • • • • • • • • • • • • •
ForeColor • • • •
GraphType •
Height R R R R R R R R R R R R R R R R R R
hWnd R R R R R R R R R R R R R R R
Id R R R R R R R R R R R R R R R R R R
Left R R R R R R R R R R R R R R R R R R
LegendPos •
ListCount R R R R
ListIndex R R R R
Max • • •
MaxLength • •
Min • • •
Multiline R R
MultiSelect • R
Name R R R R R R R R R R R R R R R R R R
NewIndex R R R R
NumSets R
PagingEvent R
Parent R R R R R R R R R R R R
ParentKey

Control and Property Matrix 469

ClearBasic Control Reference
 Supported Methods, Properties, and Events

Table 9 Supported properties for controls (Continued)

Dropdown Combo Box

Dropdown List Box

Multiline Text Box

Command Button

Grid/Custom List

Option Button
ProgressBar
Select CBX

Tab Button
Check Box
Animation

TreeView
Text Box

UpDown
List Box
Control
Bitmap

Graph

Slider
Label
Object or Control >

Property
PromptOnSave R
Required R R
RequiredColor • •
SelCount R R
Selected R R R R
SelLength • •
SelStart • •
SelText • •
ShowLegend •
Sorted R R R R
Tag • • • • • • • • • • • •
Text • •
Top R R R R R R R R R R R R R R R R R R
TopIndex • •
TotalRows R
UserData R R
Value • W • • • • • • • • • •
Visible • • • • • • • • • • • • • • • • •
Width R R R R R R R R R R R R R R R R R R

470 Control and Property Matrix

ClearBasic Control Reference
 Supported Methods, Properties, and Events

Control and Event Matrix

Table 10 lists the ClearBasic controls and the events supported by each.
Table 10 Supported events for controls

Dropdown Combo Box

Dropdown List Box

Multiline Text Box

Command Button

Grid/Custom List

Option Button
ProgressBar
Select CBX

Tab Button
Check Box
Animation

TreeView
Text Box

UpDown
List Box
Control
Bitmap

Graph

Slider
Label
Object or Control >

Events
AdhocCellChanged •
Cell_Btn_Click •
CellChanged •
Cell_Click •
Cell_List_Select •
Change • •
Click • • • • • • • • • • •
Collapse •
ContextMenuDisplaying • • •
ContextMenu_Select • • •
DblClick • •
DoAdhocQuery •
DownClick •
Expand •
GotFocus • • • • • • • • • • • • •
KeyPress • •
LostFocus • • • • • • • • • • • • •
NewRow •
NodeClick •
Refresh •
RowChanged •
Scroll •
SortColumn •
UpClick •

Control and Event Matrix 471

ClearBasic Control Reference
 Supported Methods, Properties, and Events

472 Control and Event Matrix

ClearBasic Control Reference
Index
A cells
AbortCellChange method 155 changing 230
AbortRowChange method 157 clicking 232
ActiveX control clicking cell buttons 228
described 15 selecting 233
Add method 438 Change event 396, 462
adhoc filters Check Box control
See Also filters described 25–26
defined 334 Caption property 27
AdhocCellChanged event 227 Click event 32
Animation control DataChanged property 28
described 17–18 Parent property 29
Close method 19 Tag property 30
Open method 20 Value property 31
Play method 21 Clear method 69, 99, 162, 259, 440
Stop method 22 ClearAdhocRow method 345
AppendAdhocFilter method 339 ClearAll method 346
AppendContextMenu method 159, 292, 410 ClearContextMenu method 163, 294, 412
AppendDefaultSort method 340 ClearData method 129
AppendItem method 68, 98, 161, 258, 341 ClearPreFilter method 347
AppendPreFilter method 343 Click event 32, 44, 124, 234, 254, 287, 312, 324, 405,
AppendRows property 210
431
Click property 93
B Close method 19
BackColor property 35, 137, 247, 297, 415 CObj property 211
BackStyle property 139 Collapse event 453
Bitmap control ColorCells method 164
described ??–23 colors, applying to controls 35, 39, 137, 247, 250, 297, 299, 415,
Bitmap control, described 23–?? 418
BorderStyle property 140 Command Button control
described 33–34
C BackColor property 35
Caption property 27, 37, 249, 319 Caption property 37
cell coloring 193 Click event 44
Cell_Btn_Click event 228 Default property 38
Cell_Click event 232 ForeColor property 39
Cell_List_Select event 233 Parent property 41
CellChanged event 230 Tag property 42

ClearBasic Control Reference 473

 Value property 43 described 65–67
comparison operators 333 AppendItem method 68
Contains method 70, 100, 167, 260 Clear method 69
ContextMenu_Select event 236, 314, 433 Click property 93
ContextMenuDisplaying event 235, 313, 432 Contains method 70
context-sensitive menus DataChanged property 84
handling selections 236, 314 Down method 71
updating 235, 313, 432 GetList method 72
Control object GetSelected method 74
described 45–48 ListCount property 85
ControlType property 51 ListIndex property 86
Enabled property 53 NewIndex property 87
GotFocus event 62 Parent property 88
Height property 54 RemoveByItem method 75
hWnd property 55 RemoveItem method 76
Id property 56 RemoveSelected method 77
Left property 57 ReplaceItem method 78
LostFocus event 63 Selected property 89
Name property 58 SelectedIndexes method 79
Refresh method 49 SelectedList method 80
SetFocus method 50 SetSelected method 81
Top property 59 Sorted property 90
Visible property 60 Tag property 91
Width property 61 UnSelect method 82
controls Up method 83
animation 17 Value property 92
applying colors 35, 39, 137, 247, 250, 297, 299, 415, 418 Dropdown List Box control
disabling 53 described 95–97
enabling 53 AppendItem method 98
getting the focus 62 Clear method 99
hiding 60 Click event 124
identifying 56, 58 Contains method 100
losing the focus 63 DataChanged property 114
setting the focus 50 Down method 101
using tags 30, 42, 253 GetList method 102
ControlType property 51 GetSelected method 104
Custom List control See Grid control ListCount property 115
ListIndex property 116
D NewIndex property 117
database paths, specifying 333 Parent property 118
DataChanged property 28, 84, 114, 212, 274, 320, 401, RemoveByItem method 105
417
RemoveItem method 106
DblClick event 237, 288
RemoveSelected method 107
Default property 38
ReplaceItem method 108
Dirty property 213
Selected property 119
display object type 332
SelectedIndexes method 109
DoAdhocQuery event 238
SelectedList method 110
Down method 71, 101, 168, 261
SetSelected method 111
DownClick event 463
Sorted property 120
driving object type 332
Tag property 121
Dropdown Combo Box control
UnSelect method 112

474 Index
ClearBasic Control Reference
 Up method 113 GetLabel method 131
UserData property 122 GetLegend method 132
Value property 123 GetList method 72, 102, 179, 262, 355
GetNext method 356
E GetPoint method 133
EnableAdhoc method 349 GetPrevious method 360
Enabled property 53 GetSelCount method 362
events GetSelected method 74, 104, 180, 264, 363
adhoc cell changes 227 GetSelectedColumns method 182
adhoc query 238 GetSelectedItem method 443
cell change 230 GotFocus event 62
cell click 232 Graph control
context-sensitive menu display 235 described 125–128
context-sensitive menu select 236 BackColor property 137
double-click 237 BackStyle property 139
grid click 234 BorderStyle property 140
grid column sort 243 ClearData method 129
grid control clicks 228 GetLabel method 131
grid control select 233 GetLegend method 132
grid row change 241 GetPoint method 133
keypress 315, 434 GraphType property 141
new grid row 239 LegendPos property 143
refresh 240 NumSets property 144
Expand event 454 SetLabel method 134
Expand method 441 SetLegend method 135
F SetPoint method 136
ShowLegend property 145
Field Array control, See Grid control
GraphType property 141
filter operators 333
Grid control
filters
described 147–154
defined 333
AbortCellChange method 155
prefilters 334
AbortRowChange method 157
focus
AdhocCellChanged event 227
getting 62
AppendContextMenu method 159
losing 63
AppendItem method 161
setting 50
AppendRows property 210
ForeColor property 39, 250, 299, 418
Cell_Btn_Click event 228
G Cell_Click event 232
GenerateSQL method 350 Cell_List_Select event 233
GetAdhocRow method 351 CellChanged event 230
GetChangedCell method 169, 352 Clear method 162
GetChangedRow method 171 ClearContextMenu method 163
GetChoiceList method 173 Click event 234
GetChoiceListDefault method 174 CObj property 211
GetChoiceListUserData method 175 ColorCells method 164
GetCObj method 353 Contains method 167
GetColumnControlType method 176 ContextMenu_Select event 236
GetColumnMaxLength method 177 ContextMenuDisplaying event 235
GetColumnNames method 178 DataChanged property 212
GetCount method 354 DblClick event 237
GetItemText method 442 Dirty property 213

Index 475
ClearBasic Control Reference
 DoAdhocQuery event 238 UnSelect method 208
Down method 168 Up method 209
GetChangedCell method 169
GetChangedRow method 171
H
GetChoiceList method 173 Height property 54
GetChoiceListDefault method 174 HideColumn method 183
GetChoiceListUserData method 175 hWnd property 55
GetColumnControlType method 176 I
GetColumnMaxLength method 177
Id property 56
GetColumnNames method 178
InsertItem method 365
GetList method 179
IsColumnEditable method 184
GetSelected method 180
IsColumnRequired method 185
GetSelectedColumns method 182
HideColumn method 183 K
IsColumnEditable method 184 Key method 444
IsColumnRequired method 185 KeyPress event 315, 434
ListCount property 214 keypress events, handling 315, 434
ListIndex property 215
MultiSelect property 216 L
NewIndex property 217 Label control
NewRow event 239 described 245–246
PagingEvent property 218 BackColor property 247
Parent property 219 Caption property 249
PromptOnSave property 220 Click event 254
Refresh event 240 ForeColor property 250
RemoveByItem method 186 Parent property 252
RemoveItem method 187 Tag property 253
RemoveSelected method 188 Left property 57
ReplaceItem method 189 LegendPos property 143
RowChanged event 241 List Box control
SaveAnyChanges method 190 described 255–257
SelCount property 221 AppendItem method 258
Selected property 222 Clear method 259
SelectedIndexes method 191 Click event 287
SelectedList method 192 Contains method 260
SetCellColoring method 193 DataChanged property 274
SetCellFocus method 196 DblClick event 288
SetCellReadOnly method 197 Down method 261
SetCellText method 198 GetList method 262
SetContextMenuEnabled method 199 GetSelected method 264
SetContextMenuVisible method 200 ListCount property 275
SetEditStates method 201 ListIndex property 276
SetNewRowIndicator method 204 MultiSelect property 277
SetRowReadOnly method 205 NewIndex property 278
SetSelected method 206 Parent property 279
SortColumn event 243 RemoveByItem method 265
Sorted property 223 RemoveItem method 266
Tag property 224 RemoveSelected method 267
TopIndex property 225 ReplaceItem method 268
TotalRows property 226 SelCount property 280
UndoRowChanges method 207 Selected property 281

476 Index
ClearBasic Control Reference
 SelectedIndexes method 269 NodeClick event 455
SelectedList method 270 NumSets property 144
SetSelected method 271
Sorted property 282
O
Tag property 283 Open method 20
TopIndex property 284 Option Button control
UnSelect method 272 described 317–318
Up method 273 Caption property 319
UserData property 285 Click event 324
Value property 286 DataChanged property 320
ListCount property 85, 115, 214, 275 Parent property 321
ListIndex property 86, 116, 215, 276 Tag property 322
LostFocus event 63 Value property 323
OwnsGrid method 367
M
Max property 327, 393, 459
P
MaxLength property 301, 420 paging, in grids 149, 335
Min property 328, 394, 460 PagingEvent property 218
multiCBX control Parent property 29, 41, 88, 118, 219, 252, 279, 303,
321, 402, 422
defined 335
paths, specifying 333
getting the contextual object 353
Play method 21
setting the contextual object 383
prefilters
MultiLine property 302, 421
See Also filters
Multiline Text Box control
adding 343
described 289–291
defined 334
AppendContextMenu method 292
ProgressBar control
BackColor property 297
described 325–326
ClearContextMenu method 294
Max property 327
Click event 312
Min property 328
ContextMenu_Select event 314
Value property 329
ContextMenuDisplaying event 313
PromptOnSave property 220
ForeColor property 299
KeyPress event 315 R
MaxLength property 301 Refresh event 240
MultiLine property 302 Refresh method 49
Parent property 303 RefreshItem method 368
Required property 304 Regenerate method 369
RequiredColor property 305 RejectAdhocCellEntry method 370
SelLength property 306 Remove method 445
SelStart property 307 RemoveByItem method 75, 105, 186, 265
SelText property 308 RemoveItem method 76, 106, 187, 266, 372
SetContextMenuEnabled method 295 RemoveSelected method 77, 107, 188, 267, 374
SetContextMenuVisible method 296 ReplaceItem method 78, 108, 189, 268
Tag property 309 ReplaceSelected method 375
Text property 310 Required property 304, 423
Value property 311 RequiredColor property 305, 424
MultiSelect property 216, 277 ResetDefaultSort method 377
ResetPreFilter method 378
N
RowChanged event 241
Name property 58
NewIndex property 87, 117, 217, 278
NewRow event 239

Index 477
ClearBasic Control Reference
 S SetCellColoring method 193
SaveAnyChanges method 190 SetCellFocus method 196
Scroll event 397 SetCellReadOnly method 197
SelCount property 221, 280 SetCellText method 198
Select CBX control SetCObj method 383
described 331–338 SetContextMenuEnabled method 199, 295, 413
AppendAdhocFilter method 339 SetContextMenuVisible method 200, 296, 414
AppendDefaultSort method 340 SetCurrent method 384
AppendItem method 341 SetEditStates method 201
AppendPreFilter method 343 SetFocus method 50
ClearAdhocRow method 345 SetImageList method 446
ClearAll method 346 SetItemOverlayImage method 448
ClearPreFilter method 347 SetItemText method 449
EnableAdhoc method 349 SetLabel method 134
GenerateSQL method 350 SetLegend method 135
GetAdhocRow method 351 SetNewRowIndicator method 204
GetChangedCell method 352 SetOverlayImage method 450
GetCObj method 353 SetPoint method 136
GetCount method 354 SetRowReadOnly method 205
GetList method 355 SetSelected method 81, 111, 206, 271, 386
GetNext method 356 SetSelectedById method 387
GetPrevious method 360 SetSelectedItem method 452
GetSelCount method 362 ShowLegend property 145
GetSelected method 363 Slider control
InsertItem method 365 described 391–392
OwnsGrid method 367 Change event 396
RefreshItem method 368 Max property 393
Regenerate method 369 Min property 394
RejectAdhocCellEntry method 370 Scroll event 397
RemoveItem method 372 Value property 395
RemoveSelected method 374 SortColumn event 243
ReplaceSelected method 375 Sorted property 90, 120, 223, 282
ResetDefaultSort method 377 Stop method 22
ResetPreFilter method 378
T
SelectedList method 379
Tab Button control
SetAdhocCellReadOnly method 381
described 399–400
SetAdhocCellText method 382
Click event 405
SetCObj method 383
DataChanged property 401
SetCurrent method 384
Parent property 402
SetSelected method 386
Tag property 403
SetSelectedById method 387
Value property 404
UnSelect method 388
Tag property 30, 42, 91, 121, 224, 253, 283, 309, 322,
UpdateItem method 389 403, 428
Selected property 89, 119, 222, 281 Text Box control
SelectedIndexes method 79, 109, 191, 269 described 407–409
SelectedList method 80, 110, 192, 270, 379 AppendContextMenu method 410
SelLength property 306, 425 BackColor property 415
SelStart property 307, 426 ClearContextMenu method 412
SelText property 308, 427 Click event 431
SetAdhocCellReadOnly method 381 ContextMenu_Select event 433
SetAdhocCellText method 382

478 Index
ClearBasic Control Reference
 ContextMenuDisplaying event 432 UpClick event 464
DataChanged property 417 Value property 461
ForeColor property 418 UserData property 122, 285
KeyPress event 434
MaxLength property 420
V
MultiLine property 421 Value property 31, 43, 92, 123, 286, 311, 323, 329, 395,
Parent property 422
404, 430, 461
Visible property 60
Required property 423
RequiredColor property 424 W
SelLength property 425 Width property 61
SelStart property 426
SelText property 427
SetContextMenuEnabled method 413
SetContextMenuVisible method 414
Tag property 428
Text property 429
Value property 430
Text property 310, 429
Top property 59
TopIndex property 225, 284
TotalRows property 226
TreeView control
described 435–437
Add method 438
Clear method 440
Collapse event 453
Expand event 454
Expand method 441
GetItemText method 442
GetSelectedItem method 443
Key method 444
NodeClick event 455
Remove method 445
SetImageList method 446
SetItemOverlayImage method 448
SetItemText method 449
SetOverlayImage method 450
SetSelectedItem method 452

U
UndoRowChanges method 207
UnSelect method 82, 112, 208, 272, 388
Up method 83, 113, 209, 273
UpClick event 464
UpdateItem method 389
UpDown control
described 457–458
Change event 462
DownClick event 463
Max property 459
Min property 460

Index 479
ClearBasic Control Reference
480 Index
ClearBasic Control Reference