2 ABC Library Reference

COPYRIGHT SoftVelocity Inc. All rights reserved.

This publication is protected by copyright and all rights are reserved by SoftVelocity Incorporated. It may not, in whole or
part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form
without prior consent, in writing, from SoftVelocity Incorporated.

This publication supports Clarion. It is possible that it may contain technical or typographical errors. SoftVelocity
Incorporated provides this publication ―as is,‖ without warranty of any kind, either expressed or implied.

SoftVelocity Incorporated
P.O. Box 510190
Melbourne Beach, Florida 32951
(866) 783-4320
www.softvelocity.com

Trademark Acknowledgements:

SoftVelocity is a trademark of SoftVelocity Incorporated.

Clarion is a trademark of SoftVelocity Incorporated.
Btrieve is a registered trademark of Pervasive Software.
Microsoft , Windows , and Visual Basic are registered trademarks of Microsoft Corporation.
All other products and company names are trademarks of their respective owners.

Printed in the United States of America (0111)

Contents and Forward 3

Contents:
Foreword 36
Welcome .................................................................................................................................................................. 36
Documentation Conventions .................................................................................................................................... 37
Keyboard Conventions ................................................................................................................................ 37
Other Conventions ...................................................................................................................................... 37
ABC Library Overview 38
About This Book ....................................................................................................................................................... 38
Application Builder Class (ABC) Library .................................................................................................................. 38
Class Libraries Generally ............................................................................................................................ 38
Application Builder Classes—The ABCs of Rapid Application Development ............................................. 38
ABC Library and the ABC Templates ......................................................................................................... 42
ABC Coding Conventions ........................................................................................................................................ 44
Method Names ............................................................................................................................................ 44
Where to Initilize & Kill Objects ................................................................................................................... 45
Return Values ............................................................................................................................................. 45
PRIVATE (undocumented) Items ................................................................................................................ 46
PROTECTED, VIRTUAL, DERIVED, and PROC Attributes ....................................................................... 47
Documentation Conventions .................................................................................................................................... 48
Reference Item and Syntax Diagram .......................................................................................................... 48
Property (short description of intended use) ............................................................................................... 48
Method (short description of what the method does) .................................................................................. 48
Conceptual Example ................................................................................................................................... 49
ASCIIFileClass 50
ASCIIFileClass Overview .................................................................................................................................. 50
AsciiFileClass Properties ................................................................................................................................... 53
ASCIIFile (the ASCII file)............................................................................................................................. 53
ErrorMgr (ErrorClass object) ....................................................................................................................... 53
OpenMode (file access/sharing mode) ....................................................................................................... 53
AsciiFileClass Methods ..................................................................................................................................... 54
ASCIIFileClass Functional Organization--Expected Use ............................................................................ 54
FormatLine (a virtual to format text) ............................................................................................................ 55
GetDOSFilename (let end user select file) ................................................................................................. 56
GetFilename (return the filename) .............................................................................................................. 57
GetLastLineNo (return last line number) ..................................................................................................... 58
GetLine (return line of text) ......................................................................................................................... 59
GetPercentile (convert file position to percentage:ASCIIFileClass) ........................................................... 60
Init (initialize the ASCIIFileClass object) ..................................................................................................... 61
Kill (shut down the ASCIIFileClass object).................................................................................................. 62
Reset (reset the ASCIIFileClass object) ..................................................................................................... 63
SetLine (a virtual to position the file) ........................................................................................................... 64
SetPercentile (set file to relative position) ................................................................................................... 65
ValidateLine (a virtual to implement a filter) ................................................................................................ 66
ASCIIPrintClass 68
ASCIIPrintClass Overview ................................................................................................................................. 68
AsciiPrintClass Properties ................................................................................................................................. 71
FileMgr (AsciiFileClass object:AsciiPrintClass) .......................................................................................... 71
PrintPreview (print preview switch) ............................................................................................................. 71
Translator (TranslatorClass object:AsciiPrintClass) ................................................................................... 71
AsciiPrintClass Methods .................................................................................................................................... 72
Ask (solicit print specifications) ................................................................................................................... 72
Init (initialize the ASCIIPrintClass object).................................................................................................... 73
4 ABC Library Reference

PrintLines (print or preview specified lines) ................................................................................................ 74

ASCIISearchClass 76
ASCIISearchClass Overview ............................................................................................................................. 76
AsciiSearchClass Properties ............................................................................................................................. 79
Find (search constraints)............................................................................................................................. 79
FileMgr (AsciiFileClass object:AsciiSearchClass) ...................................................................................... 80
LineCounter (current line number) .............................................................................................................. 80
Translator (TranslatorClass object:ASCIISearchClass) .............................................................................. 80
AsciiSearchClass Methods ................................................................................................................................ 81
Ask (solicit search specifications) ............................................................................................................... 81
Init (initialize the ASCIISearchClass object)................................................................................................ 82
Next (find next line containing search text) ................................................................................................. 83
Setup (set search constraints) .................................................................................................................... 84
ASCIIViewerClass 86
ASCIIViewerClass Overview ............................................................................................................................. 86
AsciiViewerClass Properties .............................................................................................................................. 89
Popup (PopupClass object) ........................................................................................................................ 89
Printer (ASCIIPrintClass object) .................................................................................................................. 89
Searcher (ASCIISearchClass object) .......................................................................................................... 90
TopLine (first line currently displayed) ........................................................................................................ 90
AsciiViewerClass Methods ................................................................................................................................ 91
AsciiViewerClass Functional Organization--Expected Use ........................................................................ 91
AddItem (program the AsciiViewer object).................................................................................................. 93
AskGotoLine (go to user specified line) ...................................................................................................... 94
DisplayPage (display new page) ................................................................................................................. 95
Init (initialize the ASCIIViewerClass object) ................................................................................................ 96
Kill (shut down the ASCIIViewerClass object) ............................................................................................ 98
PageDown (scroll down one page) ............................................................................................................. 99
PageUp (scroll up one page) .................................................................................................................... 100
Reset (reset the ASCIIViewerClass object) .............................................................................................. 101
SetLine (position to specific line) .............................................................................................................. 102
SetLineRelative (move n lines) ................................................................................................................. 103
SetTranslator (set run-time translator:ASCIIViewerClass) ....................................................................... 104
TakeEvent (process ACCEPT loop event:ASCIIViewerClass) ................................................................. 105
BreakManagerClass 106
BreakManagerClass - Overview ............................................................................................................... 106
BreakManagerClass - Concepts ............................................................................................................... 106
BreakManagerClass - Relationship to Other Application Builder Classes ............................................... 106
BreakManagerClass - ABC Template Implementation ............................................................................. 106
BreakManagerClass - Source Files ......................................................................................................... 106
BreakManagerClass - Conceptual Example ............................................................................................. 107
BreakManagerClass - Properties ................................................................................................................... 109
BreakManagerClass - Methods ....................................................................................................................... 109
AddBreak (add a Break)............................................................................................................................ 109
AddLevel (add a Level to the BreakId Break) ........................................................................................... 110
AddResetField (add a reset field to the last Level added) ........................................................................ 111
AddTotal (add a total field to the last Level added) .................................................................................. 112
Construct (automatic initialization of the BreakManager object)............................................................... 113
Destruct (automatic destroy of the Breakmanager object) ....................................................................... 113
Init (initialize the BreakManager object) .................................................................................................... 113
TakeEnd (Break closed)............................................................................................................................ 114
TakeStart (Break opened) ......................................................................................................................... 115
UpdateTotal (Calculate Break totaling) ..................................................................................................... 116
BrowseEIPManagerClass 118
BrowseEIPManagerClass--Overview .............................................................................................................. 118
Contents and Forward 5

BrowseEIPManagerClass Concepts ............................................................................................................... 119

BrowseEIPManagerClass--Relationship to Other Application Builder Classes .............................................. 120
BrowseEIPManagerClass--ABC Template Implementation ............................................................................ 120
BrowseEIPManagerClass Source Files .......................................................................................................... 120
BrowseEIPManagerClass--Conceptual Example ............................................................................................ 121
BrowseEIPManagerClass Properties .............................................................................................................. 124
BrowseEIPManagerClass Properties ........................................................................................................ 124
BC (browse class) .................................................................................................................................... 124
BrowseEIPManagerClass Methods ................................................................................................................. 125
BrowseEIPManagerClass--Functional Organization--Expected Use ....................................................... 125
ClearColumn (reset column property values) ........................................................................................... 126
Init (initialize the BrowseEIPManagerClass object) .................................................................................. 127
Kill (shut down the BrowseEIPManagerClass object) ............................................................................... 128
TakeCompleted (process completion of edit) ........................................................................................... 129
TakeNewSelection (reset edit-in-place column) ...................................................................................... 130
BrowseClass 131
BrowseClass Overview .................................................................................................................................... 131
BrowseClass Properties .................................................................................................................................. 135
BrowseClass Properties ............................................................................................................................ 135
ActiveInvisible (obscured browse list action) ............................................................................................ 135
AllowUnfilled (display filled list) ................................................................................................................. 136
ArrowAction (edit-in-place action on arrow key) ....................................................................................... 137
AskProcedure (update procedure) ............................................................................................................ 138
ChangeControl (browse change/update control number) ......................................................................... 138
CurrentChoice (current LIST control entry number) ................................................................................. 139
DeleteAction (edit-in-place action on delete key) ..................................................................................... 139
DeleteControl (browse delete control number) ......................................................................................... 139
EditList (list of edit-in-place controls) ........................................................................................................ 140
EIP (edit-in-place manager) ...................................................................................................................... 140
EnterAction (edit-in-place action on enter key) ......................................................................................... 141
FocusLossAction (edit-in-place action on lose focus) ............................................................................... 142
HasThumb (vertical scroll bar flag) ........................................................................................................... 143
HideSelect (hide select button) ................................................................................................................. 143
ILC(reference to IListControl interface) ..................................................................................................... 143
InsertControl (browse insert control number)............................................................................................ 144
ListQueue (browse data queue reference) ............................................................................................... 144
Loaded (browse queue loaded flag) ......................................................................................................... 144
Popup (browse popup menu reference) ................................................................................................... 145
PrevChoice (prior LIST control entry number) .......................................................................................... 145
PrintControl (browse print control number) ............................................................................................... 145
PrintProcedure (print procedure) .............................................................................................................. 146
Processors (reference to ProcessorQueue) ............................................................................................. 146
Query (reference to QueryClass) .............................................................................................................. 146
QueryControl (browse query control number)........................................................................................... 147
QueryShared (share query with multiple sorts) ........................................................................................ 147
QuickScan (buffered reads flag) ............................................................................................................... 148
RetainRow (highlight bar refresh behavior) .............................................................................................. 149
SelectControl (browse select control number) .......................................................................................... 149
Selecting (select mode only flag) .............................................................................................................. 150
SelectWholeRecord (select entire record flag) ......................................................................................... 150
Sort (browse sort information) ................................................................................................................... 151
StartAtCurrent (initial browse position) ..................................................................................................... 152
TabAction (edit-in-place action on tab key)............................................................................................... 153
Toolbar (browse Toolbar object) ............................................................................................................... 154
ToolbarItem (browse ToolbarTarget object).............................................................................................. 155
ToolControl (browse toolbox control number) ........................................................................................... 156
6 ABC Library Reference

ViewControl (view button) ......................................................................................................................... 156

Window (WindowManager object) ............................................................................................................ 156
BrowseClass Methods ..................................................................................................................................... 157
BrowseClass Methods .............................................................................................................................. 157
BrowseClass Functional Organization--Expected Use ............................................................................. 157
AddEditControl (specify custom edit-in-place class) ................................................................................. 159
AddField (specify a FILE/QUEUE field pair) ............................................................................................. 160
AddItem(program the BrowseClass object) .............................................................................................. 161
AddLocator (specify a locator) .................................................................................................................. 161
AddResetField (set a field to monitor for changes) ................................................................................... 162
AddSortOrder (specify a browse sort order) ............................................................................................. 163
AddToolbarTarget (set the browse toolbar) .............................................................................................. 164
ApplyRange (refresh browse based on resets and range limits) .............................................................. 165
Ask (update selected browse item) ........................................................................................................... 166
AskRecord (edit-in-place selected browse item) ...................................................................................... 167
Fetch (get a page of browse items) .......................................................................................................... 168
Init(initialize the BrowseClass object) ....................................................................................................... 169
InitSort (initialize locator values) ............................................................................................................... 170
Kill (shut down the BrowseClass object) ................................................................................................... 170
Next (get the next browse item) ................................................................................................................ 171
NotifyUpdateError (throw error on update) ............................................................................................... 172
PostNewSelection (post an EVENT:NewSelection to the browse list) ..................................................... 173
Previous (get the previous browse item)................................................................................................... 174
Records (return the number of browse queue items) ............................................................................... 175
ResetFields(reinitialize FieldPairsClass) ................................................................................................... 175
ResetFromAsk (reset browse after update) .............................................................................................. 176
ResetFromBuffer (fill queue starting from record buffer) .......................................................................... 177
ResetFromFile (fill queue starting from file POSITION) ............................................................................ 178
ResetFromView (reset browse from current result set) ............................................................................ 179
ResetQueue (fill or refill queue) ................................................................................................................ 180
ResetResets (copy the Reset fields) ......................................................................................................... 181
ResetSort (apply sort order to browse) ..................................................................................................... 182
ScrollEnd (scroll to first or last item) ......................................................................................................... 183
ScrollOne (scroll up or down one item) ..................................................................................................... 184
ScrollPage (scroll up or down one page) .................................................................................................. 185
SetAlerts (alert keystrokes for list and locator controls) ............................................................................ 186
SetLocatorField (set sort free element to passed field) ............................................................................ 187
SetLocatorFromSort (use sort like locator field) ....................................................................................... 187
SetQueueRecord (copy data from file buffer to queue buffer:BrowseClass) ............................................ 188
SetSort (apply a sort order to the browse) ................................................................................................ 189
TakeAcceptedLocator (apply an accepted locator value) ......................................................................... 190
TakeEvent (process the current ACCEPT loop event:BrowseClass) ....................................................... 191
TakeKey (process an alerted keystroke:BrowseClass) ............................................................................ 192
TakeNewSelection (process a new selection:BrowseClass) .................................................................... 193
TakeScroll (process a scroll event) ........................................................................................................... 194
TakeVCRScroll (process a VCR scroll event)........................................................................................... 195
UpdateBuffer (copy selected item from queue buffer to file buffer) .......................................................... 196
UpdateQuery (set default query interface) ................................................................................................ 197
UpdateResets (copy reset fields to file buffer) .......................................................................................... 198
UpdateThumb (position the scrollbar thumb) ............................................................................................ 199
UpdateThumbFixed (position the scrollbar fixed thumb) .......................................................................... 200
UpdateViewRecord (get view data for the selected item) ......................................................................... 201
UpdateWindow (update display variables to match browse) .................................................................... 202
BrowseQueue Interface 204
BrowseQueue Concepts .................................................................................................................................. 204
Relationship to Other Application Builder Classes .......................................................................................... 204
BrowseQueue Source Files ............................................................................................................................. 204
BrowseQueue Methods ................................................................................................................................... 205
Contents and Forward 7

Delete(remove entry in LIST queue) ......................................................................................................... 205

Fetch(retrieve entry from LIST queue) ...................................................................................................... 205
Free(clear contents of LIST queue) .......................................................................................................... 205
GetViewPosition(retrieve VIEW position) .................................................................................................. 205
Insert(add entry to LIST queue) ................................................................................................................ 205
Records(return number of records) ........................................................................................................... 206
SetViewPosition(set VIEW position) ......................................................................................................... 206
Update(update entry in LIST queue) ......................................................................................................... 206
Who(returns field name)............................................................................................................................ 206
BrowseToolbarClass 208
BrowseToolbarClass Overview ....................................................................................................................... 208
BrowseToolbarClass Concepts ....................................................................................................................... 208
Relationship to Other Application Builder Classes .......................................................................................... 208
BrowseToolbarClass ABC Template Implementation ..................................................................................... 208
BrowseToolbarClass Source Files .................................................................................................................. 208
BrowseToolbarClass Properties ...................................................................................................................... 209
Browse (BrowseClass object) ................................................................................................................... 209
Button (toolbar buttons FEQ values) ......................................................................................................... 209
Window (WindowManager object) ............................................................................................................ 209
BrowseToolbarClass Methods ......................................................................................................................... 210
Init (initialize the BrowseToolbarClass object) .......................................................................................... 210
InitBrowse (initialize the BrowseToolbarClass update buttons) ................................................................ 210
InitMisc (initialize the BrowseToolbarClass miscellaneous buttons) ........................................................ 211
InitVCR (initialize the BrowseToolbarClass VCR buttons)........................................................................ 212
ResetButton (synchronize toolbar with a corresponding browse control) ................................................. 213
ResetFromBrowse(synchronize toolbar controls with browse controls) ................................................... 214
TakeEvent(process the current event) ...................................................................................................... 214
BufferedPairsClass 216
BufferedPairsClass Overview .......................................................................................................................... 216
BufferedPairsClass Properties ........................................................................................................................ 218
BufferedPairsClass Properties .................................................................................................................. 218
RealList (recognized field pairs) ................................................................................................................ 218
BufferedPairsClass Methods ........................................................................................................................... 219
BufferedPairsClass Methods .................................................................................................................... 219
BufferedPairsClass Functional Organization Expected Use..................................................................... 219
AddPair (add a field pair:BufferedPairsClass) .......................................................................................... 221
AssignBufferToLeft (copy from "buffer" fields to "left" fields) .................................................................... 222
AssignBufferToRight (copy from "buffer" fields to "right" fields) ............................................................... 223
AssignLeftToBuffer (copy from "left" fields to "buffer" fields) .................................................................... 224
AssignRightToBuffer (copy from "right" fields to "buffer" fields) ............................................................... 225
EqualLeftBuffer (compare "left" fields to "buffer" fields) ............................................................................ 226
EqualRightBuffer (compare "right" fields to "buffer" fields) ....................................................................... 227
Init (initialize the BufferedPairsClass object)............................................................................................. 228
Kill (shut down the BufferedPairsClass object) ......................................................................................... 229
ConstantClass 230
ConstantClass Overview ................................................................................................................................. 230
ConstantClass Properties ................................................................................................................................ 234
TerminatorField (identify the terminating field) ......................................................................................... 234
TerminatorInclude (include matching terminator record) .......................................................................... 234
TerminatorValue (end of data marker) ...................................................................................................... 235
ConstantClass Methods .................................................................................................................................. 236
ConstantClass Functional Organization--Expected Use........................................................................... 236
AddItem (set constant datatype and target variable) ................................................................................ 237
Init (initialize the ConstantClass object) .................................................................................................... 238
8 ABC Library Reference

Kill (shut down the ConstantClass object) ................................................................................................ 239

Next (load all constant items to file or queue) ........................................................................................... 240
Next (copy next constant item to targets) ................................................................................................. 241
Reset (reset the object to the beginning of the constant data) ................................................................. 242
Set (set the constant data to process) ...................................................................................................... 243
Crystal8 Class 244
Crystal8 Class Properties ................................................................................................................................ 244
Crystal8 Methods ............................................................................................................................................. 245
AllowPrompt (prompt for runtime parameter data) .......................................................................................... 245
CanDrillDown(allow Crystal drill down support ) ............................................................................................. 246
HasCancelButton (display cancel button on report preview) .......................................................................... 247
HasCloseButton (display close button on report preview) .............................................................................. 248
HasExportButton (display export button on report preview) ............................................................................ 249
HasLaunchButton (display launch button on report preview) .......................................................................... 250
HasNavigationControls (display navigation controls on report preview) ......................................................... 251
HasPrintButton (display print button on report preview) .................................................................................. 252
HasPrintSetupButton (display print setup button on report preview) .............................................................. 253
HasProgressControls (display progress controls on report preview) .............................................................. 254
HasRefreshButton (display refresh button on report preview) ........................................................................ 255
HasSearchButton (display search button on report preview) .......................................................................... 256
HasZoomControl (display zoom control on report preview) ............................................................................ 257
Init (initialize Crystal8 object) ........................................................................................................................... 258
Kill (shut down Crystal8 object) ...................................................................................................................... 259
Preview (preview a Crystal Report) ................................................................................................................. 260
_Print (print a Crystal Report) .......................................................................................................................... 261
Query (retrieve or set the SQL data query) ..................................................................................................... 262
SelectionFormula (retrieve or set the Crystal formula ) ................................................................................... 263
ShowDocumentTips (show tips on docuement in the preview window) .......................................................... 264
ShowReportControls (show print controls) ...................................................................................................... 265
ShowToolbarTips (show tips on preview window toolbar) .............................................................................. 266
cwRTF Class 268
cwRTF Overview ............................................................................................................................................. 268
cwRTF Class Concepts ................................................................................................................................... 268
cwRTF Relationship to Other Application Builder Classes ............................................................................. 269
cwRTF ABC Template Implementation ........................................................................................................... 269
cwRTF Source Files ........................................................................................................................................ 269
cwRTF Properties ............................................................................................................................................ 269
cwRTF Properties ..................................................................................................................................... 269
hRTFWindow(RTF control handle) ........................................................................................................... 269
cwRTF Methods............................................................................................................................................... 270
AlignParaCenter (center paragraph) ......................................................................................................... 270
AlignParaLeft (left justify paragraph) ......................................................................................................... 270
AlignParaRight (right justify paragraph) .................................................................................................... 270
ChangeFontStyle (set current font style) .................................................................................................. 271
CanRedo (check for redo data) ................................................................................................................. 271
CanUndo (check for undo data) ................................................................................................................ 272
Color (set text color) .................................................................................................................................. 272
Copy (copy selected text to clipboard) ...................................................................................................... 272
Cut (cut selected text ) .............................................................................................................................. 273
Find (set current font style) ....................................................................................................................... 273
FlatButtons (use flat button style) ............................................................................................................. 274
Font (apply font attributes) ........................................................................................................................ 275
GetText (copy text to variable) .................................................................................................................. 276
Init (initialize the cwRTF object) ................................................................................................................ 277
IsDirty (indicates modified data) ................................................................................................................ 278
Kill (shut down the csRTF object) ............................................................................................................. 279
LeftIndent (indent the current or selected paragraph) .............................................................................. 279
Contents and Forward 9

LimitTextSize (limit amount of text) ........................................................................................................... 280

LoadField (load rich text data from field)................................................................................................... 280
LoadFile (load rich text data from file) ....................................................................................................... 281
NewFile (clear rich text data) .................................................................................................................... 281
Offset (offset current or selected paragraph) ............................................................................................ 281
PageSetup (set page attributes) ............................................................................................................... 281
ParaBulletsOff (turn off paragraph bullets) ............................................................................................... 282
ParaBulletsOn (turn on paragraph bullets) ............................................................................................... 282
Paste (paste text from clipboard) .............................................................................................................. 283
_Print (print rich text control contents) ...................................................................................................... 283
Redo (reapply action) ................................................................................................................................ 284
Replace (find and replace search) ............................................................................................................ 284
ResizeControls (used internally) ............................................................................................................... 285
RightIndent (indent the current or selected paragraph) ............................................................................ 285
SaveField (save rich text data to field) ...................................................................................................... 285
SaveFile (save rich text data to file) .......................................................................................................... 286
SelectText (select characters) .................................................................................................................. 286
SetDirtyFlag (set modified flag) ................................................................................................................. 287
SetFocus (give rich text control focus) ...................................................................................................... 287
SetText (place text into rich text control)................................................................................................... 288
ShowControl (hide/unhide RTF control).................................................................................................... 289
Undo (undo action) .................................................................................................................................... 289
DbAuditManager 290
DbAuditManager Overview .............................................................................................................................. 290
Relationship to Other Application Builder Classes .......................................................................................... 290
DbAuditManager ABC Template Implementation ........................................................................................... 290
DbAuditManager Source Files ......................................................................................................................... 290
DbAuditManager Properties ............................................................................................................................ 291
Action (log file action column) ................................................................................................................... 291
ColumnInfo (log file column queue) .......................................................................................................... 291
LogFiles (log file queue) ............................................................................................................................ 291
FM (DbLogFileManager object) ................................................................................................................ 292
Errors (ErrorClass object) ......................................................................................................................... 292
DbAuditManager Methods ............................................................................................................................... 293
AddItem (maintain the columninfo structure) ............................................................................................ 293
AddLogFile (maintain log file structure) .................................................................................................... 294
AppendLog (initiate audit log file update).................................................................................................. 294
BeforeChange (update audit log file before file change) .......................................................................... 295
CreateHeader (create log file header records) ......................................................................................... 295
Init (initialize the DbAuditManager object) ................................................................................................ 296
Kill (shut down DbAuditManger object) ..................................................................................................... 296
OnChange (update audit log file after a record change) ........................................................................... 297
OnDelete (update audit log file when a record is deleted) ........................................................................ 297
OnFieldChange (virtual method for each field change) ............................................................................ 298
OnInsert (update audit log file when a record is added) ........................................................................... 299
OpenLogFile (open the audit log file) ........................................................................................................ 299
SetFM (determine log file status) .............................................................................................................. 300
DbChangeManager 302
DbChangeManager Overview ......................................................................................................................... 302
Relationship to Other Application Builder Classes .......................................................................................... 302
DbChangeManager ABC Template Implementation ....................................................................................... 302
DbChangeManager Source Files .................................................................................................................... 302
DbChangeManager Properties ........................................................................................................................ 303
NameQueue (pointer into trigger queue) .................................................................................................. 303
TriggerQueue (pointer to BFP for field changes) ...................................................................................... 303
10 ABC Library Reference

DbChangeManager Methods .......................................................................................................................... 304

AddItem (maintain the namequeue structure) .......................................................................................... 304
AddThread (maintains the triggerqueue) .................................................................................................. 304
CheckChanges(check record for changes) .............................................................................................. 305
CheckPair(check field pairs for changes) ................................................................................................. 305
Equal(checks for equal before and after values) ...................................................................................... 306
Init (initialize the DbChangeManager object) ............................................................................................ 306
Kill (shut down DbChangeManger object) ................................................................................................ 307
SetThread (read triggerqueue) ................................................................................................................. 307
Update (update the audit log file buffer).................................................................................................... 308
DbLogFileManager 310
DbLogFileManager Overview .......................................................................................................................... 310
Relationship to Other Application Builder Classes .......................................................................................... 310
DbLogFileManager ABC Template Implementation ........................................................................................ 310
DbLogFileManager Source Files ..................................................................................................................... 310
DbLogFileManager Properties ......................................................................................................................... 311
DbLogFileManager Properties .................................................................................................................. 311
Opened (file opened flag) ......................................................................................................................... 311
DbLogFileManager Methods ........................................................................................................................... 312
DbLogFileManager Methods ..................................................................................................................... 312
Init (initialize the DbLogFileManager object) ............................................................................................. 312
EditClass 314
EditClass Overview.......................................................................................................................................... 314
EditClass Concepts ......................................................................................................................................... 314
Relationship to Other Application Builder Classes .......................................................................................... 314
ABC Template Implementation ........................................................................................................................ 315
EditClass Source Files .................................................................................................................................... 315
EditClass Conceptual Example ....................................................................................................................... 316
EditClass Properties ........................................................................................................................................ 319
FEQ (the edit-in-place control number)..................................................................................................... 319
ReadOnly ( edit-in-place control is read-only) .......................................................................................... 319
EditClass Methods ........................................................................................................................................... 320
Functional Organization--Expected Use ................................................................................................... 320
CreateControl (a virtual to create the edit control) .................................................................................... 321
Init (initialize the EditClass object) ............................................................................................................ 322
Kill (shut down the EditClass object) ......................................................................................................... 323
SetAlerts (alert keystrokes for the edit control) ......................................................................................... 323
SetReadOnly (set edit control to read-only) .............................................................................................. 324
TakeAccepted (validate EIP field) ............................................................................................................. 324
TakeEvent (process edit-in-place events)................................................................................................ 325
EditSpinClass 326
EditSpinClass--Overview ................................................................................................................................. 326
EditSpinClass Concepts .................................................................................................................................. 326
EditSpinClass -- Relationship to Other Application Builder Classes ............................................................... 326
EditSpinClass--ABC Template Implementation ............................................................................................... 326
EditSpinClass--Conceptual Example............................................................................................................... 327
EditSpinClass Properties ................................................................................................................................. 329
EditSpinClass Properties .......................................................................................................................... 329
EditSpinClass Methods ................................................................................................................................... 330
EditSpinClass Methods ............................................................................................................................. 330
EditSpinClass--Functional Organization--Expected Use .......................................................................... 330
CreateControl (create the edit-in-place SPIN control) .............................................................................. 331
EditCheckClass 332
EditCheckClass Overview ............................................................................................................................... 332
EditCheckClass Concepts ............................................................................................................................... 332
Contents and Forward 11

EditCheckClass Relationship to Other Application Builder Classes ............................................................... 332

EditCheckClass ABC Template Implementation ............................................................................................. 332
EditCheckClass Source Files .......................................................................................................................... 332
EditCheckClass Conceptual Example ............................................................................................................. 333
EditCheckClass Properties .............................................................................................................................. 336
EditCheckClass Methods ................................................................................................................................ 337
EditCheckClass Functional Organization—Expected Use ....................................................................... 337
CreateControl (create the edit-in-place CHECK control) .......................................................................... 338
EditColorClass 340
EditColorClassOverview .................................................................................................................................. 340
EditColorClass Concepts ................................................................................................................................. 340
EditColorClass Relationship to Other Application Builder Classes ................................................................. 340
EditColorClass ABC Template Implementation ............................................................................................... 340
EditColorClass Source Files ............................................................................................................................ 340
EditColorClass Conceptual Example............................................................................................................... 341
EditColorClass Properties ............................................................................................................................... 344
EditColorClass Properties ......................................................................................................................... 344
Title (color dialog title text) ........................................................................................................................ 344
EditColorClass Methods .................................................................................................................................. 345
EditColorClass Functional Organization--Expected Use .......................................................................... 345
CreateControl (create the edit-in-place control) ........................................................................................ 346
TakeEvent (process edit-in-place events:EditColorClass)....................................................................... 347
EditDropComboClass 348
EditDropComboClass Overview ...................................................................................................................... 348
EditDropComboClass Concepts ...................................................................................................................... 348
Relationship to Other Application Builder Classes .......................................................................................... 348
EditDropComboClass ABC Template Implementation .................................................................................... 348
EditDropComboClass Source Files ................................................................................................................. 348
EditDropComboClass Conceptual Example .................................................................................................... 349
EditDropComboClass Properties ..................................................................................................................... 351
EditDropComboClass Methods ....................................................................................................................... 352
EditDropComboClass Functional Organization ............................................................................................... 352
CreateControl (create the edit-in-place COMBO control) ............................................................................... 353
EditDropListClass 354
EditDropListClass Overview ............................................................................................................................ 354
EditDropListClass Concepts ............................................................................................................................ 354
EditDropListClass Relationship to Other Application Builder Classes ............................................................ 354
EditDropListClass ABC Template Implementation .......................................................................................... 354
EditDropListClass Source Files ....................................................................................................................... 354
EditDropListClass Conceptual Example .......................................................................................................... 355
EditDropListClass Properties ........................................................................................................................... 358
EditDropListClass Properties .................................................................................................................... 358
EditDropListClass Methods ............................................................................................................................. 359
EditDropListClass Functional Organization--Expected Use ..................................................................... 359
CreateControl (create the edit-in-place DROPLIST control)..................................................................... 360
SetAlerts (alert keystrokes for the edit control:EditDropListClass) ........................................................... 361
SetReadOnly (set edit control to read-only:EditDropClass)...................................................................... 362
TakeEvent (process edit-in-place events:EditDropList Class) ................................................................. 363
EditEntryClass 364
EditEntryClass Overview ................................................................................................................................. 364
EditEntryClass Concepts ................................................................................................................................. 364
EditEntryClass Relationship to Other Application Builder Classes ................................................................. 364
EditEntryClass ABC Template Implementation ............................................................................................... 365
12 ABC Library Reference

EditEntryClass Source Files ............................................................................................................................ 365

EditEntryClass Conceptual Example ............................................................................................................... 365
EditEntryClass Properties ................................................................................................................................ 368
EditEntryClass Properties ......................................................................................................................... 368
EditEntryClass Methods .................................................................................................................................. 369
EditEntryClass Methods ............................................................................................................................ 369
EditEntryClass Functional Organization--Expected Use .......................................................................... 369
CreateControl (create the edit-in-place ENTRY control) .......................................................................... 370
EditFileClass 372
EditFileClass Overview .................................................................................................................................... 372
EditFileClass Concepts ................................................................................................................................... 372
EditFileClass Relationship to Other Application Builder Classes .................................................................... 372
EditFileClass ABC Template Implementation ................................................................................................. 372
EditFileClass Source Files ............................................................................................................................... 372
EditFileClass Conceptual Example ................................................................................................................. 373
EditFileClass Properties .................................................................................................................................. 377
EditFileClass Properties ............................................................................................................................ 377
FileMask (file dialog behavior) .................................................................................................................. 377
FilePattern (file dialog filter) ...................................................................................................................... 377
Title (file dialog title text) ........................................................................................................................... 378
EditFileClass Methods ..................................................................................................................................... 379
EditFileClass Functional Organization--Expected Use ............................................................................. 379
CreateControl (create the edit-in-place control:EditFileClass).................................................................. 380
TakeEvent (process edit-in-place events:EditFileClass) ......................................................................... 381
EditFontClass 383
EditFontClass Overview .................................................................................................................................. 383
EditFontClass Concepts .................................................................................................................................. 383
EditFontClass Relationship to Other Application Builder Classes .................................................................. 383
EditFontClass ABC Template Implementation ................................................................................................ 383
EditFontClass Source Files ............................................................................................................................. 383
EditFontClass Conceptual Example ................................................................................................................ 384
EditFontClass Properties ................................................................................................................................. 388
EditFontClass Properties .......................................................................................................................... 388
Title (font dialog title text) .......................................................................................................................... 388
EditFontClass Methods ................................................................................................................................... 389
EditFontClass Methods ............................................................................................................................. 389
EditFontClass Functional Organization--Expected Use ............................................................................ 389
CreateControl (create the edit-in-place control:EditFontClass) ................................................................ 390
TakeEvent (process edit-in-place events:EditFontClass) ........................................................................ 391
EditMultiSelectClass 393
EditMultiSelectClass Overview ........................................................................................................................ 393
EditMultiSelectClass Concepts ........................................................................................................................ 393
EditMultiSelectClass Relationship to Other Application Builder Classes ........................................................ 393
EditMultiSelectClass ABC Template Implementation ...................................................................................... 393
EditMultiSelectClass Source Files ................................................................................................................... 393
EditMultiSelectClass Conceptual Example ..................................................................................................... 394
EditMultiSelectClass Properties ...................................................................................................................... 398
EditMultiSelectClass Properties ................................................................................................................ 398
Title (font dialog title text:EditMultiSelectClass) ........................................................................................ 398
EditMultiSelectClass Methods ......................................................................................................................... 399
EditMultiSelectClass Methods .................................................................................................................. 399
EditMultiSelectClass Functional Organization--Expected Use ................................................................. 399
AddValue (prime the MultiSelect dialog) ................................................................................................... 401
CreateControl (create the edit-in-place control:EditMultiSelectClass) ...................................................... 402
Reset (reset the EditMultiSelectClass object) ........................................................................................... 402
TakeAction (process MultiSelect dialog action) ....................................................................................... 403
Contents and Forward 13

TakeEvent (process edit-in-place events:EditMultiSelectClass).............................................................. 405

EditTextClass 407
EditTextClass: Overview ................................................................................................................................. 407
EditTextClass Properties ................................................................................................................................. 409
Title (text dialog title text) .......................................................................................................................... 409
EditTextClass Methods .................................................................................................................................... 410
CreateControl (create the edit-in-place control:EditTextClass) ................................................................ 411
TakeEvent (process edit-in-place events:EditTextClass) ........................................................................ 412
EIPManagerClass 413
EIPManagerClass--Overview .......................................................................................................................... 413
EIPManagerClass Concepts ........................................................................................................................... 413
EIPManagerClass--Relationship to Other Application Builder Classes .......................................................... 413
EIPManagerClass--ABC Template Implementation ........................................................................................ 414
EIPManagerClass Source Files ....................................................................................................................... 414
EIPManagerClass--Conceptual Example ........................................................................................................ 415
EIPManagerClass Properties .......................................................................................................................... 417
Again (column usage flag) ........................................................................................................................ 417
Arrow (edit-in-place action on arrow key) ................................................................................................ 417
Column (listbox column)............................................................................................................................ 417
Enter (edit-in-place action on enter key) .................................................................................................. 418
EQ (list of edit-in-place controls) .............................................................................................................. 418
Fields (managed fields) ............................................................................................................................. 419
FocusLoss ( action on loss of focus)......................................................................................................... 419
Insert (placement of new record) .............................................................................................................. 420
ListControl (listbox control number) .......................................................................................................... 421
LastColumn (previous edit-in-place column)............................................................................................. 421
Repost (event synchronization) ................................................................................................................ 422
RepostField (event synchronization field) ................................................................................................. 422
Req (database request) ............................................................................................................................ 423
SeekForward (get next field flag) .............................................................................................................. 423
Tab (action on a tab key) .......................................................................................................................... 423
EIPManagerClass Methods ............................................................................................................................. 424
EIPManagerClass--Functional Organization--Expected Use.................................................................... 424
AddControl (register edit-in-place controls) .............................................................................................. 426
ClearColumn (reset column property values:EIPManagerClass) ............................................................. 427
GetEdit (identify edit-in-place field) ........................................................................................................... 428
Init (initialize the EIPManagerClass object) .............................................................................................. 429
InitControls (initialize edit-in-place controls) ............................................................................................. 429
Kill (shut down the EIPManagerClass object) ........................................................................................... 430
Next (get the next edit-in-place field) ........................................................................................................ 431
ResetColumn (reset edit-in-place object to selected field) ....................................................................... 432
Run (run the EIPManager) ....................................................................................................................... 433
SetColumnEditType (set column's EditClass) .......................................................................................... 434
TakeAcceptAll (validate completed row) ................................................................................................... 435
TakeAction (process edit-in-place action) ................................................................................................. 436
TakeCompleted (process completion of edit:EIPManagerClass) ............................................................. 437
TakeEvent (process window specific events) .......................................................................................... 438
TakeFieldEvent (process field specific events) ........................................................................................ 439
TakeFocusLoss (a virtual to process loss of focus) .................................................................................. 440
TakeNewSelection (reset edit-in-place column:EIPManagerClass) ........................................................ 441
EntryLocatorClass 443
EntryLocatorClass Overview ........................................................................................................................... 443
EntryLocatorClass Properties .......................................................................................................................... 446
EntryLocatorClass Properties ................................................................................................................... 446
14 ABC Library Reference

Shadow (the search value) ....................................................................................................................... 446

EntryLocatorClass Methods ............................................................................................................................ 447
GetShadow(return shadow value) ............................................................................................................ 447
Init (initialize the EntryLocatorClass object) .............................................................................................. 448
Set (restart the locator:EntryLocatorClass) ............................................................................................... 449
SetShadow(set shadow value) ................................................................................................................. 450
TakeAccepted (process an accepted locator value:EntryLocatorClass) .................................................. 450
TakeKey (process an alerted keystroke:EntryLocatorClass) .................................................................... 451
Update (update the locator control and free elements) ............................................................................ 452
UpdateWindow (redraw the locator control).............................................................................................. 452
ErrorClass 453
ErrorClass Overview ................................................................................................................................. 453
Overview of ErrorClass changes after Clarion version 6.1 ....................................................................... 453
ErrorClass Source Files ............................................................................................................................ 454
Multiple Customizable Levels of Error Treatment ..................................................................................... 454
Predefined Windows and Database Errors ............................................................................................... 455
Dynamic Extensibility of Errors ................................................................................................................. 455
ErrorClass ABC Template Implementation ............................................................................................... 455
ErrorClass Relationship to Other Application Builder Classes ................................................................. 455
ErrorClass Macro Expansion .................................................................................................................... 456
ErrorClass Multi-Language Capability ...................................................................................................... 457
ErrorClass Conceptual Example ............................................................................................................... 458
ErrorClass Properties ...................................................................................................................................... 459
ErrorClass Properties ................................................................................................................................ 459
DefaultCategory (error category) .............................................................................................................. 459
ErrorLog (errorlog interface) ..................................................................................................................... 460
Errors (recognized error definitions) ......................................................................................................... 460
FieldName (field that produced the error) ................................................................................................. 460
FileName (file that produced the error) ..................................................................................................... 461
History (error history structure) ................................................................................................................. 461
HistoryResetOnView(clear error history log file) ....................................................................................... 462
HistoryThreshold (determine size of error history) .................................................................................... 462
HistoryViewLevel (trigger error history) ..................................................................................................... 462
KeyName (key that produced the error).................................................................................................... 462
LogErrors (turn on error history logging) ................................................................................................... 463
MessageText (custom error message text) .............................................................................................. 463
Silent (silent error flag) .............................................................................................................................. 463
ErrorClass Methods ......................................................................................................................................... 464
ErrorClass Functional Organization--Expected Use ................................................................................. 464
AddErrors (add or override recognized errors) ......................................................................................... 465
AddHistory (update History structure) ....................................................................................................... 466
GetCategory (retrieve error category) ....................................................................................................... 466
GetDefaultCategory (get default error category) ...................................................................................... 466
GetError (Retrieve the current error message) ......................................................................................... 467
GetErrorcode (Retrieve the current Errorcode)......................................................................................... 467
GetFieldName (get field that produced the error) ..................................................................................... 467
GetFileName (get file that produced the error) ......................................................................................... 467
GetHistoryResetOnView (get the error reset mode) ................................................................................. 468
GetHistoryThreshold (get size of error history) ......................................................................................... 469
GetHistoryViewLevel (get error history viewing mode) ............................................................................. 469
GetKeyName (get key name that produced the error) .............................................................................. 470
GetLogErrors (get state of error log) ......................................................................................................... 470
GetMessageText (get current error message text) ................................................................................... 471
GetProcedureName (return procedure name ) ......................................................................................... 471
GetSilent (get silent error flag) .................................................................................................................. 472
HistoryMsg (initialize the message window) ............................................................................................. 472
Init (initialize the ErrorClass object) .......................................................................................................... 473
Kill (perform any necessary termination code) ......................................................................................... 474
Contents and Forward 15

Message (display an error message) ........................................................................................................ 475

Msg (initiate error message destination) ................................................................................................... 476
MessageBox (display error message to window) ..................................................................................... 477
RemoveErrors (remove or restore recognized errors) .............................................................................. 478
ResetHistory(clear History structure) ........................................................................................................ 478
SetCategory (set error category) .............................................................................................................. 479
SetDefaultCategory (set default error category) ....................................................................................... 479
SetErrors (save the error state) ................................................................................................................ 480
SetFatality (set severity level for a particular error) .................................................................................. 481
SetField (set the substitution value of the %Field macro)......................................................................... 482
SetFieldName (set field name that produced the error) ............................................................................ 482
SetFile (set the substitution value of the %File macro)............................................................................. 483
SetFileName (set the file that produced the error) .................................................................................... 483
SetHistoryResetOnView (set error reset mode)........................................................................................ 484
SetHistoryThreshold (set size of error history).......................................................................................... 484
SetHistoryViewLevel (set error history viewing mode) ............................................................................. 485
SetKey (set the substitution value of the %Key macro) ............................................................................ 486
SetKeyName (set the key name that produced the error) ........................................................................ 487
SetId (make a specific error current) ......................................................................................................... 488
SetLogErrors (set error log mode) ............................................................................................................ 489
SetMessageText (set the current error message text) ............................................................................. 490
SetProcedureName ( stores procedure names) ....................................................................................... 491
SetSilent (set silent error flag) ................................................................................................................... 492
SubsString (resolves error message macros)........................................................................................... 493
TakeBenign (process benign error) .......................................................................................................... 494
TakeError (process specified error) .......................................................................................................... 495
TakeFatal (process fatal error) .................................................................................................................. 496
TakeNotify (process notify error) ............................................................................................................... 497
TakeOther (process other error) ............................................................................................................... 498
TakeProgram (process program error) .................................................................................................... 499
TakeUser (process user error) .................................................................................................................. 500
Throw (process specified error) ............................................................................................................... 501
ThrowFile (set value of %File, then process error) ................................................................................... 502
ThrowMessage (set value of %Message, then process error) ................................................................. 503
ViewHistory (initiates the view of the current errors) ................................................................................ 503
ErrorLogInterface 505
ErrorLogInterface Concepts ............................................................................................................................ 505
Relationship to Other Application Builder Classes .......................................................................................... 505
ErrorLogInterface Source Files ........................................................................................................................ 505
ErrorLogInterface Methods .............................................................................................................................. 506
ErrorLogInterface Methods ....................................................................................................................... 506
Close (initiate close of log file) .................................................................................................................. 506
Open (method to initiate open of log file) .................................................................................................. 507
Take (update the log file) .......................................................................................................................... 507
FieldPairsClass 509
FieldPairsClass Overview ................................................................................................................................ 509
FieldPairsClass Properties .............................................................................................................................. 511
List (recognized field pairs) ....................................................................................................................... 511
FieldPairsClass Methods ................................................................................................................................. 512
FieldPairsClass Functional Organization--Expected Use ......................................................................... 512
AddItem (add a field pair from one source field) ...................................................................................... 513
AddPair (add a field pair:FieldPairsClass) ................................................................................................ 514
AssignLeftToRight (copy from "left" fields to "right" fields) ....................................................................... 515
AssignRightToLeft (copy from "right" fields to "left" fields) ....................................................................... 516
ClearLeft (clear each "left" field)................................................................................................................ 517
16 ABC Library Reference

ClearRight (clear each "right" field) ........................................................................................................... 518

Equal (return 1 if all pairs are equal) ......................................................................................................... 519
EqualLeftRight (return 1 if all pairs are equal) .......................................................................................... 520
Init (initialize the FieldPairsClass object) .................................................................................................. 520
Kill (shut down the FieldPairsClass object) ............................................................................................... 521
FileDropComboClass 523
Overview:FileDropComboClass ...................................................................................................................... 523
FileDropComboClass Properties ..................................................................................................................... 527
FileDropComboClass Properties .............................................................................................................. 527
AskProcedure (update procedure) ............................................................................................................ 527
ECOn (current state of entry completion) ................................................................................................. 527
EntryCompletion (automatic fill-ahead flag) .............................................................................................. 528
RemoveDuplicatesFlag (remove duplicate data) ...................................................................................... 528
UseField (COMBO USE variable) ............................................................................................................. 529
FileDropComboClass Methods ........................................................................................................................ 530
FileDropComboClass Methods ................................................................................................................. 530
FileDropComboClass Functional Organization--Expected Use ................................................................ 530
AddRecord (add a record filedrop queue)................................................................................................. 532
Ask (add a record to the lookup file) ......................................................................................................... 532
GetQueueMatch (locate a list item) .......................................................................................................... 533
Init (initialize the FileDropComboClass object) ......................................................................................... 534
KeyValid (check for valid keystroke) ......................................................................................................... 536
Kill (shut down the FileDropComboClass object) ..................................................................................... 536
ResetFromItem (reset entry and list control)............................................................................................. 537
ResetFromList (reset VIEW) ..................................................................................................................... 537
ResetQueue (refill the filedrop queue) ...................................................................................................... 538
TakeAccepted (process accepted event).................................................................................................. 538
TakeEvent (process the current ACCEPT loop event:FileDropComboClass) .......................................... 539
TakeNewSelection (process NewSelection events:FileDropComboClass) .............................................. 540
UniquePosition (check queue for duplicate record by key position) ......................................................... 541
FileDropClass 543
FileDropClass Overview .................................................................................................................................. 543
FileDropClass Properties ................................................................................................................................. 547
FileDropClass Properties .......................................................................................................................... 547
AllowReset (allow a reset)......................................................................................................................... 547
DefaultFill (initial display value) ................................................................................................................. 547
InitSyncPair (initial list position) ................................................................................................................ 547
FileDropClass Methods ................................................................................................................................... 548
FileDropClass Methods ............................................................................................................................. 548
FileDropClass Functional Organization--Expected Use ........................................................................... 548
AddField (specify display fields) ................................................................................................................ 549
AddRecord (update filedrop queue) .......................................................................................................... 550
AddUpdateField (specify field assignments) ............................................................................................. 550
Init (initialize the FileDropClass object) ..................................................................................................... 551
Kill (shut down the FileDropClass object) ................................................................................................. 552
ResetQueue (fill filedrop queue) ............................................................................................................... 553
SetQueueRecord (copy data from file buffer to queue buffer:FileDropClass) .......................................... 554
TakeAccepted (a virtual to accept data) ................................................................................................... 554
TakeEvent (process the current ACCEPT loop event--FileDropClass) .................................................... 555
TakeNewSelection (process EVENT:NewSelection events:FileDropClass) ............................................ 556
ValidateRecord (a virtual to validate records) ........................................................................................... 557
FileManager 559
FileManager Overview ..................................................................................................................................... 559
FileManager Properties ................................................................................................................................... 563
AliasedFile (the primary file) ..................................................................................................................... 563
Buffer (the record buffer) ........................................................................................................................... 564
Contents and Forward 17

Buffers (saved record buffers) .................................................................................................................. 564

Create (create file switch) ......................................................................................................................... 565
Errors (the ErrorManager) ......................................................................................................................... 565
File (the managed file) .............................................................................................................................. 565
FileName (variable filename) .................................................................................................................... 566
FileNameValue (constant filename) .......................................................................................................... 567
LazyOpen (delay file open until access) ................................................................................................... 568
LockRecover (/RECOVER wait time parameter) ...................................................................................... 568
OpenMode (file access/sharing mode) ..................................................................................................... 569
SkipHeldRecords (HELD record switch) ................................................................................................... 569
FileManager Methods ...................................................................................................................................... 571
Naming Conventions and Dual Approach to Database Operations ......................................................... 571
FileManager Functional Organization--Expected Use .............................................................................. 572
AddField(track fields in a structure) .......................................................................................................... 574
AddKey (set the file's keys) ....................................................................................................................... 575
BindFields (bind fields when file is opened) .............................................................................................. 576
CancelAutoInc (undo PrimeAutoInc) ......................................................................................................... 577
ClearKey (clear specified key components).............................................................................................. 579
Close (close the file) .................................................................................................................................. 580
Deleted (return record status) ................................................................................................................... 581
DeleteRecord (delete a record) ................................................................................................................. 582
Destruct (automatic destructor) ................................................................................................................. 583
EqualBuffer (detect record buffer changes) .............................................................................................. 583
Fetch (get a specific record by key value) ................................................................................................ 584
GetComponents (return the number of key components) ........................................................................ 585
GetEOF (return end of file status) ............................................................................................................. 586
GetError (return the current error ID) ........................................................................................................ 587
GetField (return a reference to a key component) .................................................................................... 588
GetFieldName (return a key component field name) ................................................................................ 590
GetFields(get number of fields) ................................................................................................................. 591
GetFieldPicture(get field picture) .............................................................................................................. 591
GetFieldType(get field type) ...................................................................................................................... 591
GetName (return the filename) ................................................................................................................. 592
Init (initialize the FileManager object) ....................................................................................................... 593
Insert (add a new record) .......................................................................................................................... 594
KeyToOrder (return ORDER expression for a key) .................................................................................. 595
Kill (shutdown the FileManager object) ..................................................................................................... 596
Next (get next record in sequence) ........................................................................................................... 597
Open (open the file) .................................................................................................................................. 598
Position (return the current record position).............................................................................................. 599
PostDelete(trigger delete action post-processing) .................................................................................... 600
PostInsert(trigger insert action post-processing) ...................................................................................... 602
PostUpdate(trigger update action post-processing) ................................................................................. 605
PreDelete(trigger delete action pre-processing) ....................................................................................... 607
PreInsert(trigger insert action pre-processing) ......................................................................................... 609
PreUpdate(trigger update action pre-processing) ..................................................................................... 610
Previous (get previous record in sequence) ............................................................................................. 611
PrimeAutoInc (prepare an autoincremented record for adding) ............................................................... 612
PrimeFields (a virtual to prime fields) ........................................................................................................ 614
PrimeRecord (prepare a record for adding:FileManager) ......................................................................... 615
RestoreBuffer (restore a previously saved record buffer) ......................................................................... 617
RestoreFile (restore a previously saved file state) .................................................................................... 618
SaveBuffer (save a copy of the record buffer) .......................................................................................... 619
SaveFile (save the current file state) ........................................................................................................ 620
SetError (save the specified error and underlying error state).................................................................. 621
SetErrors (set the error class used) .......................................................................................................... 622
SetKey (set current key)............................................................................................................................ 623
18 ABC Library Reference

SetName (set current filename) ................................................................................................................ 624

Throw (pass an error to the error handler for processing) ........................................................................ 625
ThrowMessage (pass an error and text to the error handler) ................................................................... 626
TryFetch (try to get a specific record by key value) .................................................................................. 627
TryInsert (try to add a new record) ............................................................................................................ 628
TryNext (try to get next record in sequence)............................................................................................. 629
TryOpen (try to open the file) .................................................................................................................... 630
TryPrevious (try to get previous record in sequence) ............................................................................... 631
TryPrimeAutoInc (try to prepare an autoincremented record for adding) ................................................. 632
TryReget (try to get a specific record by position) .................................................................................... 634
TryUpdate (try to change the current record)............................................................................................ 634
TryValidateField(validate field contents) ................................................................................................... 635
Update (change the current record) .......................................................................................................... 636
UseFile (use LazyOpen file) ...................................................................................................................... 637
ValidateField (validate a field) ................................................................................................................... 638
ValidateFields (validate a range of fields) ................................................................................................. 639
ValidateFieldServer(validate field contents).............................................................................................. 640
ValidateRecord (validate all fields) ............................................................................................................ 641
FilterLocatorClass 643
FilterLocatorClass Overview............................................................................................................................ 643
FilterLocatorClass Properties .......................................................................................................................... 646
FilterLocatorClass Properties .................................................................................................................... 646
FloatRight ("contains" or "begins with" flag) .............................................................................................. 646
FilterLocatorClass Methods ............................................................................................................................. 647
FilterLocatorClass Methods ...................................................................................................................... 647
TakeAccepted (process an accepted locator value:FilterLocatorClass) ................................................... 647
UpdateWindow (apply the search criteria) ................................................................................................ 648
FuzzyClass 649
FuzzyClass Overview ...................................................................................................................................... 649
Relationship to Other Application Builder Classes .......................................................................................... 649
FuzzyClass ABC Template Implementation .................................................................................................... 649
FuzzyClass Source Files ................................................................................................................................. 649
FuzzyClass Properties ..................................................................................................................................... 650
FuzzyClass Methods ....................................................................................................................................... 650
Construct (initialize FuzzyClass object) .................................................................................................... 650
Init (initialize FuzzyClass object) ............................................................................................................... 650
Kill (shutdown FuzzyClass object) ............................................................................................................ 650
Match (find query matches) ...................................................................................................................... 651
SetOption (set fuzzymatch options) .......................................................................................................... 651
FormVCRClass 653
FormVCRClass Overview ................................................................................................................................ 653
FormVCRClass Concepts ............................................................................................................................... 653
FormVCRClass Relationship to Other Application Builder Classes ................................................................ 653
FormVCRClass ABC Template Implementation ............................................................................................. 653
FormVCRClass Source Files ........................................................................................................................... 654
FormVCRClass Properties .............................................................................................................................. 654
QuickScan (buffered reads flag) ............................................................................................................... 654
Toolbar (FormVCR Toolbar object) ........................................................................................................... 655
ToolbarItem (FormVCR ToolbarTarget object) ......................................................................................... 655
ViewPosition (store the current record position) ....................................................................................... 656
FormVCRClass Methods: ................................................................................................................................ 657
AddToolbarTarget (set the FormVCR toolbar) .......................................................................................... 657
Init (initialize the FormVCR object) ........................................................................................................... 658
InitSort (initialize locator values) ............................................................................................................... 658
Kill (shut down the FormVCR object) ........................................................................................................ 659
CheckBorders (check for existence of records) ........................................................................................ 659
Contents and Forward 19

GetAction (return FormVCR action) .......................................................................................................... 660

GetActionAllowed (validate a requested FormVCR action) ...................................................................... 661
Next (get the next FormVCR item) ............................................................................................................ 662
Previous (get the previous FormVCR item) .............................................................................................. 663
ResetSort (apply sort order to FormVCR)................................................................................................. 663
SetAlerts (alert keystrokes for FormVCR controls) ................................................................................... 663
SetRequestControl (assign field equates to FormVCR actions) ............................................................... 664
SetVCRControls (assign field equates to FormVCR scrolling) ................................................................. 665
SetSort (apply a sort order to the FormVCR group) ................................................................................. 666
TakeAcceptedLocator (apply an accepted FormVCR locator value) ........................................................ 667
TakeEvent (process the current ACCEPT loop event) ............................................................................. 667
TakeLocate (a FormVCR virtual to process each sort) ............................................................................. 668
TakeScroll (process a FormVCR scroll event) .......................................................................................... 668
UpdateWindow (update display variables to match FormVCR action) ..................................................... 669
GraphClass 671
GraphClass Overview ...................................................................................................................................... 671
Relationship to Other Application Builder Classes .......................................................................................... 671
GraphClass ABC Template Implementation ................................................................................................... 671
GraphClass Source Files ................................................................................................................................. 671
GraphClass Properties .................................................................................................................................... 672
eShowSBonFirstThread (display on base status bar) .............................................................................. 672
eSumYMax (calculated maximum node value) ........................................................................................ 672
gShowDiagramName (show diagram name on target) ............................................................................. 673
gShowDiagramNameV (show diagram value on target) ........................................................................... 674
gShowMouse (show mouse coordinates on target) .................................................................................. 675
gShowMouseX (show mouse X coordinate on target) .............................................................................. 676
gShowMouseY (show mouse Y coordinate on target) .............................................................................. 677
gShowNodeName (show node name on target) ....................................................................................... 678
gShowNodeNameV (show node name value on target) ........................................................................... 679
gShowNodeValue (show node axis values on target) .............................................................................. 680
gShowNodeValueX (show node x-axis value on target)........................................................................... 681
gShowNodeValueY (show node y-axis value on target)........................................................................... 682
GraphClass Methods ....................................................................................................................................... 683
AllText (return full graph text information) ................................................................................................. 683
BeginRefresh (prepare drawing of graph class object) ............................................................................. 683
CalcBestPositionNodeText (calculate graph text best fit position) ........................................................... 684
CalcCurrentGraph (calculates values for current graph type) .................................................................. 684
CalcCurrentNode (calculates values of current node) .............................................................................. 685
CalcGraph (calculates all graph object values) ........................................................................................ 685
CalcPopup (create popup menu for graph object) .................................................................................... 686
CalcPopupAdd2 (create popup menu item text for graph object) ............................................................. 687
DiagramNameText (create diagram name text) ....................................................................................... 687
DiagramText (create diagram name text with prompts) ............................................................................ 688
DiagramNameText (create diagram name text) ....................................................................................... 688
DiagramText (create diagram name text with prompts) ............................................................................ 689
Draw (calculate and draw GraphClass object).......................................................................................... 689
DrawGraph (draws calculated values) ...................................................................................................... 689
DrawReport (draw graph object on report) ............................................................................................... 691
DrawWallpaper (draw background wallpaper for graph object) ................................................................ 691
DrillDown (transfer control to new graph object) ....................................................................................... 692
FindNearbyNodes (locate nodes based on mouse position) .................................................................... 693
GetMouse (get mouse coordinates in all formats) .................................................................................... 694
GetValueFromField (get contents of specified field) ................................................................................. 695
GetValueFromStatusBar (return status bar zone contents)...................................................................... 695
ImageToWMF (Save object and return WMF file name) .......................................................................... 696
Init (Initialize the graph object) .................................................................................................................. 696
20 ABC Library Reference

Interactivity (process mouse location data to tool tip or control ................................................................ 697
IsOverNode ( is mouse over node location).............................................................................................. 697
Kill (shut down the GraphClass object) ..................................................................................................... 698
MouseText (creates text and mouse coordinate information)................................................................... 698
MouseXText (generate X coordinate text only) ........................................................................................ 698
MouseYText (generate Y coordinate text only) ........................................................................................ 699
NodeNameText (generate current node name identifier) ......................................................................... 699
NodeText (generate label, name, and node value) .................................................................................. 700
NodeTipText (generate node information for tool tip) ............................................................................... 700
NodeValueText (generate current node value text) .................................................................................. 701
NodeXText (generate X node text value).................................................................................................. 701
NodeYText (generate Y node text value).................................................................................................. 702
Popup (GraphClass object popup menu manager) .................................................................................. 702
PopupAsk (Display popup menu for graph object) ................................................................................... 703
PostEvent (send an event to the GraphClass object) ............................................................................... 704
PrintGraph (send graph object to printer) ................................................................................................. 706
Refresh (refresh drawing of GraphClass object) ...................................................................................... 707
Resize (conditional refresh when size changed) ...................................................................................... 707
ReturnFromDrillDown ( transfer control to graph object after drilldown) .................................................. 708
SaveAsGraph (save graph to WMF file selected) ..................................................................................... 709
SaveGraph (auto-save graph to WMF file) ............................................................................................... 709
SetDefault (initialize selected graph properties) ....................................................................................... 710
ShowOnField (show text contents to specified field) ................................................................................ 710
ShowOnStatusBar (show text to status bar zone) .................................................................................... 711
TakeEvent (process graph control events) ............................................................................................... 711
TakeEventofParent (process all graph events) ......................................................................................... 712
ToolTip (show all text to tool tips) ............................................................................................................. 712
ToShowValues (show all composite text to all graph targets) .................................................................. 713
GridClass 714
GridClass Overview ......................................................................................................................................... 714
Relationship to Other Application Builder Classes .......................................................................................... 714
GridClass ABC Template Implementation ....................................................................................................... 714
GridClass Source Files .................................................................................................................................... 714
GridClass Properties ....................................................................................................................................... 715
GridClass Properties ................................................................................................................................. 715
Children (reference to child group controls) .............................................................................................. 715
Chosen (current browse queue element).................................................................................................. 715
ClickPress (forward control) ...................................................................................................................... 716
ControlBase (base control number) .......................................................................................................... 716
ControlNumber (number of controls) ........................................................................................................ 716
GroupColor (background color of group fields) ......................................................................................... 717
GroupControl (GROUP control number) ................................................................................................... 717
GroupTitle (title of group element) ............................................................................................................ 717
SelColor (color of selected element) ......................................................................................................... 718
Selectable (element selectable flag) ......................................................................................................... 718
UpdateControl (file update trigger) ............................................................................................................ 718
UpdateControlEvent .................................................................................................................................. 718
GridClass Methods .......................................................................................................................................... 719
AddLocator (specify a locator) ................................................................................................................. 719
FetchRecord (retrieve selected record) .................................................................................................... 719
GetAcross (number of horizontal grids) .................................................................................................... 720
GetClickPress (forward click control) ........................................................................................................ 720
GetDown (number of vertical grids ) ......................................................................................................... 720
GetPosition (retrieve group control position)............................................................................................. 721
IfGroupField (determine if current control is a GROUP) ........................................................................... 721
Init (initialize the GridClass object) ............................................................................................................ 722
IsSkelActive ............................................................................................................................................... 722
Kill (shutdown the GridClass object) ......................................................................................................... 723
Contents and Forward 21

SetAlerts (initialize and create child controls) ........................................................................................... 723

SyncGroup (initialize GROUP field properties) ......................................................................................... 723
TakeEvent (process the current ACCEPT loop event) ............................................................................. 724
UpdateRecord (refresh BrowseGrid) ........................................................................................................ 724
UpdateWindow (refresh window display) .................................................................................................. 724
HistHandlerClass 726
HistHandlerClass Source Files ........................................................................................................................ 726
HistHandlerClass Properties ........................................................................................................................... 726
Err (errorclass obejct)................................................................................................................................ 726
History (error history structure) ................................................................................................................. 726
LBColumns (number of listbox columns) .................................................................................................. 727
Win (reference to window) ........................................................................................................................ 727
HistHandlerClass Methods .............................................................................................................................. 728
Init (initialize the HistHandlerClass object)................................................................................................ 728
TakeEvent (process window events) ........................................................................................................ 728
VLBProc (retrieve LIST and error history information.) ............................................................................. 729
IDbChangeAudit Interface 730
IDbChangeAudit Concepts .............................................................................................................................. 730
Relationship to Other Application Builder Classes .......................................................................................... 730
IDbChangeAudit Source Files ......................................................................................................................... 730
IDbChangeAudit Methods ............................................................................................................................... 730
BeforeChange (update audit log file before file change) .......................................................................... 730
ChangeField (virtual method for managing field changes) ....................................................................... 731
OnChange (update audit log file after a record change) ........................................................................... 732
IListControl Interface 734
IListControl Concepts ...................................................................................................................................... 734
Relationship to Other Application Builder Classes .......................................................................................... 734
IListControl Source Files ................................................................................................................................. 734
IListControl Methods ........................................................................................................................................ 734
Choice(returns current selection number)................................................................................................. 734
GetControl(returns control number) .......................................................................................................... 735
GetItems(returns number of entries) ......................................................................................................... 735
GetVisible(returns visibility of control) ....................................................................................................... 735
SetChoice(change selected entry) ............................................................................................................ 736
SetControl(change selected entry) ........................................................................................................... 736
IncrementalLocatorClass 738
IncrementalLocatorClass Overview ................................................................................................................. 738
IncrementalLocatorClass Properties ............................................................................................................... 741
IncrementalLocatorClass Properties ......................................................................................................... 741
IncrementalLocatorClass Methods .................................................................................................................. 742
IncrementalLocatorClass Methods ........................................................................................................... 742
SetAlerts (alert keystrokes for the LIST control:IncrementalLocatorClass) .............................................. 742
TakeKey (process an alerted keystroke:IncrementalLocatorClass) ......................................................... 743
INIClass 744
INIClass Overview ........................................................................................................................................... 744
INIClass Properties .......................................................................................................................................... 746
INIClass Properties ................................................................................................................................... 746
FileName ................................................................................................................................................... 746
INIClass Methods ............................................................................................................................................ 747
Fetch (get INI file entries) .......................................................................................................................... 747
FetchField (return comma delimited INI file value) ................................................................................... 749
FetchQueue (get INI file queue entries) .................................................................................................... 750
22 ABC Library Reference

Init (initialize the INIClass object) .............................................................................................................. 751

TryFetch (get a value from the INI file) ..................................................................................................... 752
TryFetchField (return comma delimited INI file value) .............................................................................. 753
Update (write INI file entries) .................................................................................................................... 754
IReportGenerator Interface 756
IReportGenerator Interface .............................................................................................................................. 756
IReportGenerator Concepts ............................................................................................................................ 756
IReportGenerator Methods .............................................................................................................................. 756
AskProperties (pop up window to set properties) ..................................................................................... 756
CloseDocument (end document printing) ................................................................................................. 757
ClosePage (end a page print) ................................................................................................................... 757
GetProperty (get a property value) ........................................................................................................... 758
Init (initialize error class before printing) ................................................................................................... 758
OpenDocument (begin document printing) ............................................................................................... 759
OpenPage (begin a page print) ................................................................................................................. 759
Opened (file opened flag) ......................................................................................................................... 759
ProcessArc (print an arc) .......................................................................................................................... 760
ProcessBand (begin/end report band processing) ................................................................................... 761
ProcessCheck (print a checkbox) ............................................................................................................. 761
ProcessChord (print a section of an ellipse) ............................................................................................. 762
ProcessEllipse (print an ellipse) ................................................................................................................ 763
ProcessImage (print an image) ................................................................................................................. 763
ProcessLine (print a line) .......................................................................................................................... 763
ProcessOption (print an option control) .................................................................................................... 764
ProcessRadio (print a radio button) .......................................................................................................... 765
ProcessRectangle (print a box control) ..................................................................................................... 765
ProcessString (print a string control)......................................................................................................... 766
ProcessText (print a text control) .............................................................................................................. 766
SetProperty (set a property value) ............................................................................................................ 767
WhoAmI (identify the report generator type) ............................................................................................. 767
LocatorClass 768
LocatorClass Overview .................................................................................................................................... 768
LocatorClass Properties .................................................................................................................................. 769
Control (the locator control number) ......................................................................................................... 769
FreeElement (the locator's first free key element) .................................................................................... 769
NoCase (case sensitivity flag) ................................................................................................................... 770
ViewManager (the locator's ViewManager object) .................................................................................... 770
LocatorClass Methods ..................................................................................................................................... 771
GetShadow(return shadow value) ............................................................................................................ 771
Init (initialize the LocatorClass object) ...................................................................................................... 772
Reset (reset the locator for next search)................................................................................................... 773
Set (restart the locator:LocatorClass) ....................................................................................................... 774
SetAlerts (alert keystrokes for the LIST control:LocatorClass) ................................................................. 774
SetEnabled (enable or disable the locator control) ................................................................................... 775
SetShadow (update shadow value) .......................................................................................................... 775
TakeAccepted (process an accepted locator value:LocatorClass) ........................................................... 776
TakeKey (process an alerted keystroke:LocatorClass) ............................................................................ 776
UpdateWindow (redraw the locator control with its current value) ........................................................... 777
MsgBoxClass 778
MsgBoxClass Overview ................................................................................................................................... 778
MsgBoxClass Source Files .............................................................................................................................. 778
MsgBoxClass Properties ................................................................................................................................. 779
ButtonTypes (standard windows buttons) ................................................................................................. 779
Caption (window title) ................................................................................................................................ 779
Err (errorclass object)............................................................................................................................... 779
Icon (icon for image control) ..................................................................................................................... 779
Contents and Forward 23

HistoryHandler (windowcomponent interface) ......................................................................................... 780

MsgRVal (message box return value) ....................................................................................................... 780
Style (font style) ........................................................................................................................................ 780
Win (reference to window) ........................................................................................................................ 780
MsgBoxClass Methods .................................................................................................................................... 781
FetchFeq (retrieve button feq) .................................................................................................................. 781
FetchStdButton (determine button pressed) ............................................................................................. 781
Init (initialize the MsgBoxClass object) ..................................................................................................... 782
Kill (perform any necessary termination code) ......................................................................................... 782
SetupAdditionalFeqs (initialize additional control properties) ................................................................... 783
TakeAccepted (process accepted event).................................................................................................. 783
PopupClass 784
PopupClass Overview ..................................................................................................................................... 784
PopupClass Properties .................................................................................................................................... 788
ClearKeycode (clear KEYCODE character).............................................................................................. 788
PopupClass Methods ...................................................................................................................................... 789
PopupClass Functional Organization--Expected Use ............................................................................... 789
AddItem (add menu item).......................................................................................................................... 790
AddItemEvent (set menu item action) ....................................................................................................... 791
AddItemMimic (tie menu item to a button) ................................................................................................ 792
AddMenu (add a menu) ............................................................................................................................ 793
AddSubMenu (add submenu) ................................................................................................................... 794
Ask (display the popup menu) .................................................................................................................. 795
DeleteItem (remove menu item) ............................................................................................................... 796
DeleteMenu (remove a popup submenu) ................................................................................................. 797
GetItemChecked (return toggle item status) ............................................................................................. 798
GetItemEnabled (return item status) ......................................................................................................... 799
GetItems(returns number of popup entries) .............................................................................................. 800
GetLastNumberSelection (get last menu item number selected) ............................................................. 800
GetLastSelection (return selected item).................................................................................................... 801
Init (initialize the PopupClass object) ........................................................................................................ 802
Kill (shut down the PopupClass object) .................................................................................................... 802
Restore (restore a saved menu) ............................................................................................................... 803
Save (save a menu for restoration) ........................................................................................................... 804
SetIcon (set icon name for popup menu item) .......................................................................................... 805
SetItemCheck (set toggle item status) ...................................................................................................... 806
SetItemEnable (set item status) ................................................................................................................ 807
SetLevel (set menu item level) .................................................................................................................. 808
SetText (set menu item text) ..................................................................................................................... 809
SetToolbox (set menu item toolbox status)............................................................................................... 810
SetTranslator (set run-time translator:PopupClass) ................................................................................. 811
Toolbox (start the popup toolbox menu) ................................................................................................... 812
ViewMenu (popup menu debugger) .......................................................................................................... 813
PrintPreviewClass 814
PrintPreviewClass Overview ........................................................................................................................... 814
PrintPreviewClass Properties .......................................................................................................................... 820
AllowUserZoom (allow any zoom factor) .................................................................................................. 820
ConfirmPages (force 'pages to print' confirmation) ................................................................................... 820
CurrentPage (the selected report page) ................................................................................................... 821
Maximize (number of pages displayed horizontally) ................................................................................. 821
PagesAcross (number of pages displayed horizontally) ........................................................................... 821
PagesDown (number of vertical thumbnails) ............................................................................................ 822
PagesToPrint (the pages to print) ............................................................................................................. 822
UserPercentile (custom zoom factor) ........................................................................................................ 822
WindowPosSet (use a non-default initial preview window position) ......................................................... 823
24 ABC Library Reference

WindowSizeSet (use a non-default initial preview window size) .............................................................. 823

ZoomIndex (index to applied zoom factor)................................................................................................ 824
PrintPreviewClass Methods ............................................................................................................................. 825
PrintPreviewClass Functional Organization--Expected Use ..................................................................... 825
AskPage (prompt for new report page) ..................................................................................................... 826
AskPrintPages (prompt for pages to print) ................................................................................................ 827
AskThumbnails (prompt for new thumbnail configuration) ........................................................................ 828
DeleteImageQueue (remove non-selected pages) ................................................................................... 829
Display (preview the report) ...................................................................................................................... 830
Init (initialize the PrintPreviewClass object) .............................................................................................. 831
InPageList (check page number) .............................................................................................................. 832
Kill (shut down the PrintPreviewClass object)........................................................................................... 833
Open (prepare preview window for display) ............................................................................................. 834
SetINIManager (save and restore window coordinates) ........................................................................... 835
SetPosition (set initial preview window coordinates) ................................................................................ 836
SetZoomPercentile (set user or standard zoom factor) ........................................................................... 837
SetDefaultPages (set the default pages to print) ...................................................................................... 838
SyncImageQueue (sync image queue with PagesToPrint) ...................................................................... 838
TakeAccepted (process EVENT:Accepted events:PrintPreviewClass) .................................................... 839
TakeEvent (process all events:PrintPreviewClass) .................................................................................. 840
TakeFieldEvent (a virtual to process field events:PrintPreviewClass) ...................................................... 841
TakeWindowEvent (process non-field events:PrintPreviewClass) .......................................................... 842
ProcessClass 843
ProcessClass Overview ................................................................................................................................... 843
ProcessClass Properties ................................................................................................................................. 846
CaseSensitiveValue (case sensitive flag) ................................................................................................. 846
Percentile (portion of process completed) ................................................................................................ 846
PText (progress control number) .............................................................................................................. 847
RecordsProcessed (number of elements processed) ............................................................................... 847
RecordsToProcess (number of elements to process) .............................................................................. 847
ProcessClass Methods .................................................................................................................................... 848
ProcessClass Functional Organization--Expected Use ............................................................................ 848
Init (initialize the ProcessClass object) ..................................................................................................... 849
Kill (shut down the ProcessClass object) .................................................................................................. 850
Next (get next element) ............................................................................................................................. 851
Reset (position to the first element) .......................................................................................................... 852
SetProgressLimits (calibrate the progress monitor) .................................................................................. 852
TakeLocate (a virtual to process each filter) ............................................................................................. 852
TakeRecord (a virtual to process each report record) .............................................................................. 853
QueryClass 855
QueryClass Overview ...................................................................................................................................... 855
QueryClass Concepts ...................................................................................................................................... 855
QueryClass Relationship to Other Application Builder Classes ...................................................................... 855
QueryClass ABC Template Implementation .................................................................................................... 856
QueryClass Source Files ................................................................................................................................. 856
QueryClass Conceptual Example.................................................................................................................... 857
QueryClass Properties .................................................................................................................................... 860
QKCurrentQuery ( popup menu choice ) .................................................................................................. 860
QKIcon ( icon for popup submenu ) .......................................................................................................... 860
QKMenuIcon ( icon for popup menu ) ....................................................................................................... 860
QKSupport ( quickqbe flag) ....................................................................................................................... 860
Window ( browse window:QueryClass ) ................................................................................................... 860
QueryClass Methods ....................................................................................................................................... 861
QueryClass Functional Organization--Expected Use ............................................................................... 861
AddItem (add field to query) ...................................................................................................................... 862
Ask (a virtual to accept query criteria) ....................................................................................................... 863
ClearQuery ( remove loaded query ) ........................................................................................................ 864
Contents and Forward 25

Delete ( remove saved query ) .................................................................................................................. 865

GetFilter (return filter expression) ............................................................................................................. 866
GetLimit (get searchvalues) ...................................................................................................................... 867
Init (initialize the QueryClass object) ......................................................................................................... 868
Kill (shut down the QueryClass object) ..................................................................................................... 869
Reset (reset the QueryClass object) ......................................................................................................... 870
Restore ( retrieve saved query ) ............................................................................................................... 871
Save ( save a query ) ................................................................................................................................ 872
SetLimit (set search values) ...................................................................................................................... 873
SetQuickPopup ( add QuickQBE to browse popup ) ................................................................................ 875
Take ( process QuickQBE popup menu choice ) ...................................................................................... 876
QueryFormClass 877
QueryFormClass Overview ............................................................................................................................. 877
QueryFormClass Concepts ............................................................................................................................. 877
QueryFormClass Relationship to Other Application Builder Classes .............................................................. 877
QueryFormClass ABC Template Implementation ........................................................................................... 878
QueryFormClass Source Files ........................................................................................................................ 878
QueryFormClass Conceptual Example ........................................................................................................... 879
QueryFormClass Properties ............................................................................................................................ 882
QueryFormClass Methods ............................................................................................................................... 883
QueryFormClass Functional Organization--Expected Use ....................................................................... 883
Ask (solicit query criteria) .......................................................................................................................... 884
Init (initialize the QueryFormClass object) ................................................................................................ 885
Kill (shut down the QueryFormClass object)............................................................................................. 886
QueryFormVisual 887
QueryFormVisual Overview ............................................................................................................................. 887
QueryFormVisual Concepts ............................................................................................................................ 887
QueryFormVisual Relationship to Other Application Builder Classes ............................................................. 887
QueryFormVisual ABC Template Implementation .......................................................................................... 887
QueryFormVisual Source Files ........................................................................................................................ 887
QueryFormVisual Conceptual Example .......................................................................................................... 888
QueryFormVisual Properties ........................................................................................................................... 891
QFC (reference to the QueryFormClass).................................................................................................. 891
QueryFormVisual Methods .............................................................................................................................. 892
QueryFormVisual Functional Organization--Expected Use ...................................................................... 892
GetButtonFeq(returns a field equate label) ............................................................................................... 893
Init (initialize the QueryFormVisual object) ............................................................................................... 894
ResetFromQuery ( reset the QueryFormVisual object ) ........................................................................... 895
SetText ( set prompt text:QueryFormVisual ) ........................................................................................... 896
TakeAccepted (handle query dialog Accepted events: QueryFormVisual) .............................................. 897
TakeCompleted (complete the query dialog: QueryFormVisual) .............................................................. 898
TakeFieldEvent (a virtual to process field events:QueryFormVisual) ....................................................... 899
UpdateFields ( process query values ) ..................................................................................................... 900
QueryListClass 901
QueryListClass--Overview ............................................................................................................................... 901
QueryListClass Concepts ................................................................................................................................ 901
QueryListClass--Relationship to Other Application Builder Classes ............................................................... 901
QueryListClass--ABC Template Implementation ............................................................................................. 901
QueryListClass Source Files ........................................................................................................................... 901
QueryListClass--Conceptual Example............................................................................................................. 902
QueryListClass Properties ............................................................................................................................... 905
QueryListClass Methods ................................................................................................................................. 906
QueryListClass--Functional Organization--Expected Use ........................................................................ 906
Ask (solicit query criteria:QueryListClass) ................................................................................................ 907
26 ABC Library Reference

Init (initialize the QueryListClass object) ................................................................................................... 908

Kill (shut down the QueryListClass object) ............................................................................................... 909
QueryListVisual 911
QueryListVisual--Overview .............................................................................................................................. 911
QueryListVisual Concepts ............................................................................................................................... 911
QueryListVisual--Relationship to Other Application Builder Classes .............................................................. 911
QueryListVisual--ABC Template Implementation ............................................................................................ 911
QueryListVisual Source Files .......................................................................................................................... 911
QueryListVisual--Conceptual Example ............................................................................................................ 912
QueryListVisual Properties .............................................................................................................................. 915
QFC (reference to the QueryListClass) .................................................................................................... 915
OpsEIP (reference to the EditDropListClass) ........................................................................................... 915
FldsEIP (reference to the EditDropListClass) ........................................................................................... 915
ValueEIP(reference to QEditEntryClass) .................................................................................................. 915
QueryListVisual Methods ................................................................................................................................. 916
QueryListVisual--Functional Organization--Expected Use ....................................................................... 916
Init (initialize the QueryListVisual object) .................................................................................................. 917
Kill (shutdown the QueryListVisual object)................................................................................................ 917
ResetFromQuery ( reset the QueryList Visual object ) ............................................................................. 918
SetAlerts (alert keystrokes for the edit control:QueryListVisual) .............................................................. 919
TakeAccepted (handle query dialog EVENT:Accepted events) ............................................................... 920
TakeCompleted (complete the query dialog) ............................................................................................ 921
TakeEvent (process edit-in-place events:QueryListVisual) ..................................................................... 922
TakeFieldEvent (a virtual to process field events:QueryListVisual) .......................................................... 923
UpdateControl(updates the edit-in-place entry control) ............................................................................ 924
UpdateFields ( process query values ) ..................................................................................................... 924
QueryVisualClass 925
QueryVisualClass: Overview ........................................................................................................................... 925
QueryVisualClass Properties ........................................................................................................................... 926
QC (reference to the QueryClass) ............................................................................................................ 926
Resizer (reference to the WindowResizeClass:QueryVisualClass) ......................................................... 926
QueryVisualClass Methods ............................................................................................................................. 927
Init (initialize the QueryVisual object ) ....................................................................................................... 927
Kill (shut down the QueryVisual object) .................................................................................................... 928
Reset ( reset the dialog for display:QueryVisualClass ) ........................................................................... 929
TakeAccepted (handle query dialog EVENT:Accepted events) ............................................................... 930
TakeFieldEvent (a virtual to process field events:QueryVisualClass) ...................................................... 931
TakeWindowEvent (a virtual to process non-field events:QueryVisualClass) .......................................... 932
RelationManager 933
RelationManager Overview ............................................................................................................................. 933
RelationManager Properties ............................................................................................................................ 937
RelationManager Properties ..................................................................................................................... 937
Me (the primary file's FileManager object) ................................................................................................ 937
UseLogout (transaction framing flag) ........................................................................................................ 937
RelationManager Methods .............................................................................................................................. 938
RelationManager Functional Organization--Expected Use....................................................................... 938
AddRelation (set a file relationship) .......................................................................................................... 939
AddRelationLink (set linking fields for a relationship) ............................................................................... 942
CancelAutoInc (undo autoincrement) ....................................................................................................... 943
Close (close a file and any related files) ................................................................................................... 944
Delete (delete record subject to referential constraints) ........................................................................... 945
GetNbFiles(returns number of children).................................................................................................... 946
GetNbRelations(returns number of relations) ........................................................................................... 946
GetRelation(returns reference to relation manager) ................................................................................. 947
GetRelationType(returns relation type) ..................................................................................................... 947
Init (initialize the RelationManager object) ................................................................................................ 948
Contents and Forward 27

Kill (shut down the RelationManager object) ............................................................................................ 949

ListLinkingFields (map pairs of linked fields) ............................................................................................ 950
Open (open a file and any related files) .................................................................................................... 951
Save (copy the current record and any related records) .......................................................................... 951
SetAlias (set a file alias) ............................................................................................................................ 952
SetQuickScan (enable QuickScan on a file and any related files) ........................................................... 953
Update (update record subject to referential constraints) ......................................................................... 954
ReportManager Class 956
ReportManager Overview ................................................................................................................................ 956
ReportManager Concepts ............................................................................................................................... 956
ReportManager Properties .............................................................................................................................. 961
Attribute (ReportAttributeManager object) ................................................................................................ 961
BreakMan (BreakManagerClass object) ................................................................................................... 961
DeferOpenReport (defer open) ................................................................................................................. 962
DeferWindow (defer progress window) ..................................................................................................... 962
KeepVisible (keep progress window visible) ............................................................................................. 963
OutputFileQueue (advanced report generation filenames)....................................................................... 963
Preview (PrintPreviewClass object) .......................................................................................................... 964
PreviewQueue (report metafile pathnames) ............................................................................................. 964
Process (ProcessClass object) ................................................................................................................. 965
QueryControl (query button) ..................................................................................................................... 965
Report (the managed REPORT) ............................................................................................................... 966
ReportTarget (IReportGenerator interface)............................................................................................... 966
SkipPreview (print rather than preview) .................................................................................................... 966
TargetSelector (ReportTargetSelectorClass object) ................................................................................. 967
TargetSelectorCreated (report target active) ............................................................................................ 967
TimeSlice (report resource usage) ............................................................................................................ 968
WaitCursor (activate Wait cursor during report processing) ..................................................................... 968
WMFParser (WMFDocumentParser object) ............................................................................................. 968
Zoom (initial report preview magnification) ............................................................................................... 969
ReportManager Methods ................................................................................................................................. 970
ReportManager Functional Organization--Expected Use ......................................................................... 970
AddItem (program the ReportManager object) ......................................................................................... 971
Ask (display window and process its events:ReportManager) ................................................................. 971
AskPreview (preview or print the report) ................................................................................................... 972
CancelPrintReport (cancel report printing)................................................................................................ 973
EndReport (close the report) ..................................................................................................................... 974
Init (initialize the ReportManager object) .................................................................................................. 975
Kill (shut down the ReportManager object) ............................................................................................... 976
Next (get next report record) ..................................................................................................................... 977
Open (a virtual to execute on EVENT:OpenWindow--ReportManager) ................................................... 978
OpenReport (prepare report for execution)............................................................................................... 979
PrintReport (print the report) ..................................................................................................................... 980
ProcessResultFiles (process generated output files) ............................................................................... 981
SetReportTarget (set ReportGenerator target) ......................................................................................... 982
SetStaticControlsAttributes (set report's static controls) ........................................................................... 982
SetDynamicControlsAttributes (set report's static controls) ...................................................................... 983
TakeAccepted (process Accepted event) ................................................................................................. 983
TakeCloseEvent (a virtual to process EVENT:CloseWindow) .................................................................. 984
TakeNoRecords (process empty report) ................................................................................................... 985
TakeRecord(process each record) ........................................................................................................... 985
TakeWindowEvent (a virtual to process non-field events:ReportManager) .............................................. 986
RuleManager 988
Overview ................................................................................................................................................................ 988
RuleManager Concepts ................................................................................................................................... 988
28 ABC Library Reference

RuleManager ABC Template Implementation ................................................................................................. 990

Implementation Steps using hand code .................................................................................................... 994
Rule Class Properties ............................................................................................................................................ 996
Rule Class Methods ............................................................................................................................................... 997
SetGlobalRule (post address to GlobalRule) .................................................................................................. 998
ResetGlobalRule (clear address in GlobalRule) .............................................................................................. 999
RuleIsBroken (test rule and return result) ..................................................................................................... 1000
SetIndicator (set error indicator) .................................................................................................................... 1001
RulesCollection Class Properties ......................................................................................................................... 1001
RulesCollection Class Methods ........................................................................................................................... 1001
Construct (initialize RulesCollection object) .................................................................................................. 1002
Destruct (shut down RulesCollection object) ................................................................................................. 1002
RuleCount (count rules in the collection) ....................................................................................................... 1002
BrokenRuleCount (count rules in the collection which are broken)............................................................... 1003
AddRule (add a rule to this collection) ........................................................................................................... 1003
AddControl (add managed control ) .............................................................................................................. 1004
AddControlToRule (add managed control ) ................................................................................................... 1005
CheckRule (check a particular rule) .............................................................................................................. 1006
CheckAllRules (check all rules in this collection) .......................................................................................... 1006
Item (locate a particular rule) ......................................................................................................................... 1007
TakeAccepted (handle acceptance of error indicators) ................................................................................. 1008
SetEnumerateIcons (set icons for broken rules display) ............................................................................... 1009
EnumerateBrokenRules (display a list of rules with status of each) ............................................................. 1010
SetControlsStatus (set status of managed controls) ..................................................................................... 1011
NeedChangeControlStatus (check if control status needs to change) .......................................................... 1012
RulesManager Properties .................................................................................................................................... 1013
RulesManager Methods ....................................................................................................................................... 1013
Construct (initialize RulesManager object) .................................................................................................... 1013
Destruct (shut down RulesManager object) .................................................................................................. 1013
RulesManagerCount (count rules in the collection) ....................................................................................... 1013
BrokenRulesCount (count rules in the collection which are broken) ............................................................. 1014
AddRulesCollection (add a rule to this collection) ......................................................................................... 1014
CheckAllRules (check all rules in all collections) ........................................................................................... 1014
TakeAccepted (handle acceptance of error indicators) ................................................................................. 1015
SetEnumerateIcons (set icons for broken rules display) ............................................................................... 1016
EnumerateBrokenRules (display a list of rules with status of each) ............................................................. 1017
SetControlsStatus (set status of managed controls) ..................................................................................... 1018
SelectFileClass 1020
SelectFileClass Concepts .............................................................................................................................. 1020
SelectFileClass Properties ............................................................................................................................ 1022
DefaultDirectory (initial path) ................................................................................................................... 1022
DefaultFile (initial filename/filemask) ...................................................................................................... 1022
Flags (file dialog behavior) ...................................................................................................................... 1023
WindowTitle (file dialog title text) ............................................................................................................ 1023
SelectFileClass Methods ............................................................................................................................... 1024
AddMask (add file dialog file masks) ...................................................................................................... 1024
Ask (display Windows file dialog) ............................................................................................................ 1025
Init (initialize the SelectFileClass object)................................................................................................. 1026
SetMask (set file dialog file masks)......................................................................................................... 1027
StandardBehavior Class 1030
StandardBehavior Overview .......................................................................................................................... 1030
StandardBehavior Class Concepts................................................................................................................ 1030
Relationship to Other Application Builder Classes ........................................................................................ 1030
StandardBehavior Source Files ..................................................................................................................... 1030
StandardBehavior Properties ........................................................................................................................ 1031
StandardBehavior Methods ........................................................................................................................... 1031
StandardBehavior Methods .................................................................................................................... 1031
Contents and Forward 29

Init(initialize the StandardBehavior object).............................................................................................. 1031

StandardErrorLogClass 1032
StandardErrorLogClass Overview ................................................................................................................. 1032
StandardErrorLogClass Source Files ............................................................................................................ 1032
ABC Template Implementation ...................................................................................................................... 1032
StandardErrorLogClass Properties................................................................................................................ 1033
StandardErrorLogClass Methods .................................................................................................................. 1033
Close (close standarderrorlog file) .......................................................................................................... 1033
Construct (initialize StandardErrorLogClass object) ............................................................................... 1033
Destruct (remove the StandardErrorLogClass object) ............................................................................ 1033
Open (open standarderrorlog file) ........................................................................................................... 1033
StepClass 1035
StepClass Overview ...................................................................................................................................... 1035
StepClass Properties ..................................................................................................................................... 1036
Controls (the StepClass sort sequence) ................................................................................................. 1036
StepClass Methods ....................................................................................................................................... 1037
GetPercentile (return a value's percentile:StepClass) ............................................................................ 1037
GetValue (return a percentile's value:StepClass) ................................................................................... 1038
Init (initialize the StepClass object) ......................................................................................................... 1039
Kill (shut down the StepClass object) ..................................................................................................... 1040
SetLimit (set smooth data distribution:StepClass) .................................................................................. 1041
SetLimitNeeded (return static/dynamic boundary flag:StepClass) ......................................................... 1042
StepCustomClass 1043
StepCustomClass Overview .......................................................................................................................... 1043
StepCustomClass Properties ........................................................................................................................ 1047
Entries (expected data distribution) ........................................................................................................ 1047
StepCustomClass Methods ........................................................................................................................... 1048
StepCustomClass Methods .................................................................................................................... 1048
AddItem (add a step marker) .................................................................................................................. 1048
GetPercentile (return a value's percentile:StepCustomClass) ................................................................ 1049
GetValue (return a percentile's value:StepCustomClass)....................................................................... 1050
Init (initialize the StepCustomClass object)............................................................................................. 1051
Kill (shut down the StepCustomClass object) ......................................................................................... 1052
StepLongClass 1053
StepLongClass Overview .............................................................................................................................. 1053
StepLongClass Properties ............................................................................................................................. 1056
Low (lower boundary:StepLongClass) .................................................................................................... 1056
High (upper boundary:StepLongClass)................................................................................................... 1056
StepLongClass Methods ............................................................................................................................... 1057
GetPercentile (return a value's percentile:StepLongClass) .................................................................... 1057
GetValue (return a percentile's value:StepLongClass) ........................................................................... 1058
SetLimit (set smooth data distribution:StepLongClass) .......................................................................... 1059
StepLocatorClass 1061
StepLocatorClass Overview .......................................................................................................................... 1061
StepLocatorClass Properties ......................................................................................................................... 1064
StepLocatorClass Methods ........................................................................................................................... 1065
StepLocatorClass Methods ..................................................................................................................... 1065
Set (restart the locator:StepLocatorClass) .............................................................................................. 1065
TakeKey (process an alerted keystroke:StepLocatorClass) ................................................................... 1066
StepRealClass 1067
StepRealClass Overview ............................................................................................................................... 1067
30 ABC Library Reference

StepRealClass Properties ............................................................................................................................. 1070

StepRealClass Properties ....................................................................................................................... 1070
Low (lower boundary:StepRealClass) ..................................................................................................... 1070
High (upper boundary:StepRealClass) ................................................................................................... 1070
StepRealClass Methods ................................................................................................................................ 1071
StepRealClass Methods.......................................................................................................................... 1071
GetPercentile (return a value's percentile:StepRealClass) ..................................................................... 1071
GetValue (return a percentile's value:StepRealClass)............................................................................ 1072
SetLimit (set smooth data distribution:StepRealClass) ........................................................................... 1073
StepStringClass 1075
StepStringClass Overview ............................................................................................................................. 1075
StepStringClass Properties ........................................................................................................................... 1079
LookupMode (expected data distribution) ............................................................................................... 1079
Root (the static portion of the step) ......................................................................................................... 1080
SortChars (valid sort characters) ............................................................................................................ 1080
TestLen (length of the static step portion)............................................................................................... 1081
StepStringClass Methods .............................................................................................................................. 1082
GetPercentile (return a value's percentile) .............................................................................................. 1082
GetValue (return a percentile's value) .................................................................................................... 1083
Init (initialize the StepStringClass object)................................................................................................ 1084
Kill (shut down the StepStringClass object) ............................................................................................ 1085
SetLimit (set smooth data distribution:StepStringClass) ......................................................................... 1086
SetLimitNeeded (return static/dynamic boundary flag:StepStringClass) ................................................ 1087
TagHTMLHelp Class 1089
TagHTMLHelpOverview ................................................................................................................................ 1089
TagHTMLHelp Class Concepts ..................................................................................................................... 1089
Relationship to Other Application Builder Classes ........................................................................................ 1089
TagHTMLHelp ABC Template Implementation ............................................................................................. 1089
TagHTMLHelp Source Files .......................................................................................................................... 1089
TagHTMLHelp Methods ................................................................................................................................ 1090
AlinkLookup (associative link lookup) ..................................................................................................... 1090
CloseHelp (close HTML help file) ........................................................................................................... 1091
GetHelpFile (get help file name) ............................................................................................................. 1091
GetTopic (get current topic name) .......................................................................................................... 1091
Init (initialize HTML Help object) ............................................................................................................. 1092
KeyWordLookup (lookup keyword) ......................................................................................................... 1093
Kill (shutdown the TagHTMLHelp object) ............................................................................................... 1093
SetHelpFile (set the current HTML Help file name) ................................................................................ 1094
SetTopic (set the current HTML Help file topic) ...................................................................................... 1095
ShowIndex (open the HTML Help index tab) .......................................................................................... 1095
ShowSearch (open the HTML Help search tab) ..................................................................................... 1096
ShowTOC (open the HTML Help contents tab) ...................................................................................... 1096
ShowTopic (display a help topic) ............................................................................................................ 1096
TextWindowClass 1097
TextWindowClass Overview .......................................................................................................................... 1097
TextWindowClass Concepts .......................................................................................................................... 1097
Relationship to Other Application Builder Classes ........................................................................................ 1097
ABC Template Implementation ...................................................................................................................... 1097
TextWindowClass Source Files ..................................................................................................................... 1097
TextWindowClass Properties ........................................................................................................................ 1098
SelE (ending edit position) ...................................................................................................................... 1098
SelS (starting edit position) ..................................................................................................................... 1098
Txt (field equate number) ........................................................................................................................ 1098
TextWindowClass Methods ........................................................................................................................... 1099
Init (initalize TextWindow object) ............................................................................................................ 1099
Kill (shutdown TextWindow object) ......................................................................................................... 1099
Contents and Forward 31

TakeAccepted (process window controls) .............................................................................................. 1099

ToolbarClass 1101
ToolbarClass Overview ................................................................................................................................. 1101
ToolbarClass Methods ................................................................................................................................... 1108
ToolbarClass Functional Organization--Expected Use ........................................................................... 1108
AddTarget (register toolbar driven entity) ............................................................................................... 1109
DisplayButtons (enable appropriate toolbar buttons:ToolbarClass) ....................................................... 1110
Init (initialize the ToolbarClass object) .................................................................................................... 1111
Kill (shut down the ToolbarClass object)................................................................................................. 1111
SetTarget (sets the active target) ............................................................................................................ 1112
TakeEvent (process toolbar event:ToolbarClass) ................................................................................... 1113
ToolbarListBoxClass 1114
ToolbarListBoxClass Overview...................................................................................................................... 1114
ToolbarListboxClass Properties..................................................................................................................... 1118
Browse (BrowseClass object) ................................................................................................................. 1118
ToolbarListboxClass Methods ....................................................................................................................... 1119
DisplayButtons (enable appropriate toolbar buttons:ToolbarListboxClass) ............................................ 1119
TakeEvent (convert toolbar events:ToolbarListboxClass ) ..................................................................... 1120
TakeToolbar (assume contol of the toolbar) ........................................................................................... 1121
TryTakeToolbar (return toolbar control indicator:ToolbarListBoxClass) ................................................. 1122
ToolbarReltreeClass 1124
ToolbarReltreeClass Overview ...................................................................................................................... 1124
ToolbarReltreeClass Properties .................................................................................................................... 1129
ToolbarReltreeClass Methods ....................................................................................................................... 1130
DisplayButtons (enable appropriate toolbar buttons:ToolbarReltreeClass) ............................................ 1130
TakeToolbar (assume control of the toolbar:ToolbarReltreeClass) ........................................................ 1131
ToolbarTargetClass 1133
ToolbarTarget Overview ................................................................................................................................ 1133
ToolbarTarget Properties ............................................................................................................................... 1135
ChangeButton (change control number) ................................................................................................. 1135
Control (window control) ......................................................................................................................... 1135
DeleteButton (delete control number) ..................................................................................................... 1136
HelpButton (help control number) ........................................................................................................... 1136
InsertButton (insert control number) ....................................................................................................... 1137
LocateButton(query control number) ...................................................................................................... 1137
SelectButton (select control number) ...................................................................................................... 1138
ToolbarTarget Methods ................................................................................................................................. 1139
ToolbarTarget Functional Organization--Expected Use ......................................................................... 1139
DisplayButtons (enable appropriate toolbar buttons:ToolbarTarget) ...................................................... 1140
TakeEvent (convert toolbar events:ToolbarTarget) ................................................................................ 1141
TakeToolbar (assume control of the toolbar:ToolbarTarget) .................................................................. 1142
TryTakeToolbar (return toolbar control indicator:ToolbarTarget)............................................................ 1142
ToolbarUpdateClass 1144
ToolbarUpdateClass Overview ...................................................................................................................... 1144
ToolbarUpdateClass Properties .................................................................................................................... 1151
Request (requested database operation) ............................................................................................... 1151
History (enable toolbar history button) .................................................................................................... 1152
ToolbarUpdateClass Methods ....................................................................................................................... 1153
DisplayButtons (enable appropriate toolbar buttons:ToolbarUpdateClass) ............................................ 1153
TakeEvent (convert toolbar events:ToolbarUpdateClass) ...................................................................... 1154
TakeToolbar (assume control of the toolbar:ToolbarUpdateClass) ........................................................ 1155
TryTakeToolbar (return toolbar control indicator:ToolbarUpdateClass) ................................................. 1156
32 ABC Library Reference

TransactionManagerClass 1157
Overview ........................................................................................................................................................ 1157
TransactionManager Concepts ..................................................................................................................... 1157
TransactionManager ABC Template Implementation ................................................................................... 1157
TransactionManager Relationship to Other Application Builder Classes ...................................................... 1158
TransactionManager Source Files................................................................................................................. 1158
TransactionManager Conceptual Example ................................................................................................... 1159
TransactionManager Properties .................................................................................................................... 1161
TransactionManager Methods ....................................................................................................................... 1161
AddItem (add a RelationManager to transaction list) .............................................................................. 1162
Finish (rollback or commit transaction) ................................................................................................... 1163
Process (a virtual to process transaction) ............................................................................................... 1164
Reset (remove all RelationManagers from transaction list) .................................................................... 1165
RestoreLogout (restore all RelationManagers in transaction list to previous logout status) ................... 1166
Run (initiates transaction sequence) ....................................................................................................... 1167
SetLogoutOff (turn off logout for all RelationManagers in transaction list) ............................................. 1168
SetTimeout (set timeout used in transaction) ......................................................................................... 1169
Start (start the transaction) ..................................................................................................................... 1170
TransactionCommit (commit the transaction) ......................................................................................... 1172
TransactionRollBack (rollback the transaction) ...................................................................................... 1173
TranslatorClass 1174
TranslatorClass Overview ............................................................................................................................. 1174
TranslatorClass Properties ............................................................................................................................ 1178
ExtractText (identify text to translate) ..................................................................................................... 1178
TranslatorClass Methods ............................................................................................................................... 1179
AddTranslation (add translation pairs) .................................................................................................... 1179
Init (initialize the TranslatorClass object) ................................................................................................ 1181
Kill (shut down the TranslatorClass object)............................................................................................. 1181
TranslateControl (translate text for a control) ......................................................................................... 1182
TranslateControls (translate text for range of controls) .......................................................................... 1183
TranslateString (translate text) ................................................................................................................ 1184
TranslateWindow (translate text for a window) ....................................................................................... 1185
ViewManager 1186
ViewManager Overview ................................................................................................................................. 1186
ViewManager Properties ............................................................................................................................... 1190
Order (sort, range-limit, and filter information) ........................................................................................ 1190
PagesAhead (buffered pages) ................................................................................................................ 1191
PagesBehind (buffered pages) ............................................................................................................... 1191
PageSize (buffer page size) ................................................................................................................... 1192
Primary (the primary file RelationManager ) ........................................................................................... 1192
SavedBuffers (saved record buffers) ...................................................................................................... 1193
TimeOut (buffered pages freshness) ...................................................................................................... 1194
View (the managed VIEW) ...................................................................................................................... 1194
ViewManager Methods .................................................................................................................................. 1195
ViewManager Functional Organization--Expected Use .......................................................................... 1195
AddRange (add a range limit) ................................................................................................................. 1197
AddSortOrder (add a sort order) ............................................................................................................. 1198
AppendOrder (refine a sort order) ........................................................................................................... 1199
ApplyFilter (range limit and filter the result set)....................................................................................... 1200
ApplyOrder (sort the result set) ............................................................................................................... 1201
ApplyRange (conditionally range limit and filter the result set) ............................................................... 1202
Close (close the view) ............................................................................................................................. 1203
GetFirstSortField (return first field of current sort) .................................................................................. 1203
GetFreeElementName (return free key element name) ......................................................................... 1204
GetFreeElementPosition (return free key element position) ................................................................... 1205
Init (initialize the ViewManager object) ................................................................................................... 1206
Contents and Forward 33

Kill (shut down the ViewManager object) ................................................................................................ 1207

Next (get the next element) ..................................................................................................................... 1207
Open (open the view) .............................................................................................................................. 1208
Previous (get the previous element) ....................................................................................................... 1209
PrimeRecord (prepare a record for adding:ViewManager) ..................................................................... 1210
Reset (reset the view position) ................................................................................................................ 1211
RestoreBuffers (restore VIEW file buffers).............................................................................................. 1212
SaveBuffers (save VIEW file buffers) ...................................................................................................... 1212
SetFilter (add, change, or remove active filter) ...................................................................................... 1213
SetOrder (replace a sort order) .............................................................................................................. 1214
SetSort (set the active sort order) ........................................................................................................... 1215
UseView (use LazyOpen files) ................................................................................................................ 1216
ValidateRecord (validate an element) ..................................................................................................... 1217
WindowComponent Interface 1218
WindowComponent Overview ....................................................................................................................... 1218
WindowComponent Concepts ....................................................................................................................... 1218
Relationship to Other Application Builder Classes ........................................................................................ 1218
WindowComponent Source Files .................................................................................................................. 1218
WindowComponent Methods ........................................................................................................................ 1219
WindowComponent Methods .................................................................................................................. 1219
Kill(shutdown the parent object) .............................................................................................................. 1219
PrimaryBufferRestored(confirm restore of primary buffer) ...................................................................... 1220
PrimaryBufferRestoreRequired(flag restore of primary buffer) ............................................................... 1220
PrimaryBufferSaved(confirm save of primary buffer) .............................................................................. 1221
PrimaryBufferSaveRequired(flag save of primary buffer) ....................................................................... 1221
Reset(reset object's data) ....................................................................................................................... 1222
ResetRequired(determine if screen refresh needed) .............................................................................. 1223
SetAlerts(alert keystrokes for window component) ................................................................................. 1224
TakeEvent(process the current ACCEPT loop event) ............................................................................ 1224
Update(get VIEW data for the selected item) ......................................................................................... 1225
UpdateWindow(update window controls)................................................................................................ 1225
WindowResizeClass 1226
WindowResizeClass Overview ...................................................................................................................... 1226
WindowResizeClass Properties .................................................................................................................... 1229
AutoTransparent (optimize redraw) ........................................................................................................ 1229
DeferMoves (optimize resize) ................................................................................................................. 1229
WindowResizeClass Methods ....................................................................................................................... 1230
WindowResizeClass Functional Organization--Expected Use ............................................................... 1230
GetParentControl (return parent control) ................................................................................................ 1231
GetPositionStrategy (return position strategy for a control type) ............................................................ 1232
GetResizeStrategy (return resize strategy for a control type)................................................................. 1233
Init (initialize the WindowResizeClass object)......................................................................................... 1234
Kill (shut down the WindowResizeClass object) ..................................................................................... 1236
Reset (resets the WindowResizeClass object) ....................................................................................... 1237
Resize (resize and reposition controls) ................................................................................................... 1238
RestoreWindow (restore window to initial size) ...................................................................................... 1239
SetParentControl (set parent control) ..................................................................................................... 1240
SetParentDefaults (set default parent controls) ...................................................................................... 1241
SetStrategy (set control resize strategy) ................................................................................................. 1242
WindowManager 1244
WindowManager Overview ............................................................................................................................ 1244
WindowManager Properties .......................................................................................................................... 1252
AutoRefresh (reset window as needed flag) ........................................................................................... 1252
AutoToolbar (set toolbar target on new tab selection) ............................................................................ 1252
34 ABC Library Reference

CancelAction (response to cancel request) ............................................................................................ 1253

ChangeAction (response to change request) ......................................................................................... 1254
Dead (shut down flag) ............................................................................................................................. 1254
DeleteAction (response to delete request).............................................................................................. 1255
Errors (ErrorClass object) ....................................................................................................................... 1256
FilesOpened(files opened by procedure) ................................................................................................ 1256
FirstField (first window control) ............................................................................................................... 1256
ForcedReset (force reset flag) ................................................................................................................ 1257
HistoryKey (restore field key) .................................................................................................................. 1257
InsertAction (response to insert request) ................................................................................................ 1258
LastInsertedPosition (hold position of last inserted record) .................................................................... 1258
MyWindow (the Managed WINDOW) ..................................................................................................... 1258
OKControl (window acceptance control--OK button) .............................................................................. 1259
Opened (window opened flag) ................................................................................................................ 1259
OriginalRequest (original database request) .......................................................................................... 1260
OwnerWindow (the Managed owner WINDOW) .................................................................................... 1260
Primary (RelationManager object) .......................................................................................................... 1260
Request (database request) ................................................................................................................... 1261
ResetOnGainFocus (gain focus reset flag) ............................................................................................. 1262
Resize (WindowResize object) ............................................................................................................... 1262
Response (response to database request) ............................................................................................. 1263
Saved (copy of primary file record buffer) ............................................................................................... 1263
Translator (TranslatorClass object:WindowManager) ............................................................................ 1264
VCRRequest (delayed scroll request) ..................................................................................................... 1264
WindowManager Methods ............................................................................................................................. 1265
WindowManager Functional Organization--Expected Use ..................................................................... 1265
AddHistoryField (add restorable control and field) .................................................................................. 1267
AddHistoryFile (add restorable history file) ............................................................................................. 1268
AddItem (program the WindowManager object) ..................................................................................... 1269
AddUpdateFile (register batch add files) ................................................................................................. 1270
Ask (display window and process its events:WindowManager) ............................................................. 1271
ChangeRecord(execute change record process) ................................................................................... 1272
DeleteRecord(execute delete record process) ....................................................................................... 1273
Init (initialize the WindowManager object) .............................................................................................. 1274
InsertRecord (execute insert record activity) .......................................................................................... 1276
Kill (shut down the WindowManager object) ........................................................................................... 1277
Open (open and initialize a window structure) ........................................................................................ 1278
PostCompleted (initiates final Window processing) ................................................................................ 1279
PrimeFields (a virtual to prime form fields) ............................................................................................. 1280
PrimeUpdate (update or prepare for update) .......................................................................................... 1281
RemoveItem(remove WindowComponent object) .................................................................................. 1282
Reset (reset the window for display) ....................................................................................................... 1283
RestoreField (restore field to last saved value) ...................................................................................... 1284
Run (run this procedure or a subordinate procedure) ............................................................................. 1285
SaveHistory (save history fields for later restoration) ............................................................................. 1287
SaveOnChangeAction(execute change record process and remain active) .......................................... 1288
SaveOnInsertAction(execute insert record activity and remain active) .................................................. 1289
SetAlerts (alert window control keystrokes) ............................................................................................ 1290
SetResponse (OK or Cancel the window) .............................................................................................. 1291
TakeAccepted (a virtual to process EVENT:Accepted--WindowManager) ............................................. 1292
TakeCloseEvent (a virtual to Cancel the window) ................................................................................. 1293
TakeCompleted (a virtual to complete an update form).......................................................................... 1294
TakeEvent (a virtual to process all events:WindowManager) ................................................................. 1295
TakeFieldEvent (a virtual to process field events:WindowManager) ...................................................... 1296
TakeNewSelection (a virtual to process EVENT:NewSelection) ............................................................ 1297
TakeNotify (a virtual to process EVENT:Notify) ...................................................................................... 1298
TakeRejected (a virtual to process EVENT:Rejected) ............................................................................ 1299
TakeRejected (a virtual to process EVENT:Rejected) ............................................................................ 1299
TakeSelected (a virtual to process EVENT:Selected) ............................................................................ 1300
Contents and Forward 35

TakeWindowEvent (a virtual to process non-field events:WindowManager)......................................... 1301

Update (prepare records for writing to disk) ........................................................................................... 1302
Index: 1303
36 ABC Library Reference

Foreword
Welcome
Welcome to the Application Builder Class Library Reference! This book is designed to be your every day
reference to the Classes that lie beneath the templates.

Once you‘ve become familiar with the Clarion development environment, through Getting Started, Learning
Clarion and the Online User’s Guide, you will refer to those books less and less frequently. However, in your day-
to-day work, we think you will continue to need information on the finer points of the various Application Builder
Class methods.

That‘s why we created this Application Builder Class Library Reference —for every Clarion developer who wants
a quick, ready reference to those Clarion components you use over and over again.

This book provides in-depth discussions of the ABC Library. It shows you how the ABC Templates use the
powerful ABC Library objects—and how you can use, reuse, and modify the classes with the ABC Templates or
within your hand-coded project.

These are the tools you‘ll continue to refer to regardless of your expertise with Clarion. The depths of information
on these tools and the consequent versatility you can achieve with them is virtually unlimited.
Contents and Forward 37

Documentation Conventions
Typeface Conventions

Italics Indicates what to type at the keyboard and variable information, such as Enter This or
filename.TXT. Also identifies the title information of dialog windows, like Procedure Properties.

CAPS Indicates keystrokes to enter at the keyboard such as ENTER or ESCAPE, and mouse
operations such as RIGHT-CLICK.

Boldface Indicates commands or options from a menu or text in a dialog window.

UPPERCASE Clarion language keywords such as MAX or USE.

Courier New Used for diagrams, source code listings, to annotate examples, and for examples of the usage of
source statements.

Keyboard Conventions
F1 Indicates a single keystroke. In this case, press and release the F1 key.

ALT+X Indicates a combination of keystrokes. In this case, hold down the ALT key and press the X key,
then release both keys.

Other Conventions

Special Tips, Notes, and Warnings—information that is not immediately evident from the topic explanation.
38 ABC Library Reference

ABC Library Overview

About This Book
This book describes the Application Builder Class (ABC) Library.

It provides an overview of each class or related group of classes. Then it provides specific information on the
public properties and methods of each class, plus examples for using them. It also shows you the source files for
each class and describes some of the relationships between the classes.

Application Builder Class (ABC) Library

Class Libraries Generally
The purpose of a class library in an Object Oriented system is to help programmers work more efficiently by
providing a safe, efficient way to reuse pieces of program code. In other words, a class library should relieve
programmers of having to write certain routines by letting them use already written generic routines to perform
common or repetitive program tasks.

In addition, a class library can reduce the amount of programming required to implement changes to an existing
class based program. By deriving classes that incrementally add to or subtract from the classes in the library,
programmers can accomplish substantial changes without having to rewrite the base classes or the programs that
rely on the base classes.

Application Builder Classes—The ABCs of Rapid Application Development

Typical Reusability and Maintenance Benefits

The Application Builder Classes (ABC Library) provide all the benefits of class libraries in general. Clarion‘s ABC
Templates automatically generate code that uses and reuses the robust, flexible, and solid (pre-tested) objects
defined by the ABC Library. Further, the templates are designed to help you easily derive your own classes based
on the ABC Library.

Of course, you need not use the templates to use the Application Builder Classes. However, the template
generated code certainly provides appropriate examples for using the ABC Library in hand coded programs.
Either way, the bottom line for you is more powerful programs with less coding.
ABC Library Overview 39

Database and Windows Program Orientation

The Application Builder Classes have a fairly specific focus or scope. That is, its objects are designed to process
databases within a Windows environment. Even more specifically, these objects are designed to support all the
standard functionality provided by prior versions of Clarion, plus a lot more.

As such, there are database related objects that open, read, write, view, search, sort, and print data files. There
are objects that enforce relational integrity between related data files.

In addition there are general purpose Windows related objects that display error messages, manage popup
menus, perform edit-in-place, manage file-loaded drop-down lists, perform language translation on windows,
resize windows and controls, process toolbars across execution threads, read and write INI files, and manage
selection and processing of DOS/Windows files.

The point is, the class library supports general purpose database Windows programs; it does not support, say,
real-time process control for oil refineries.

Core Classes

The Application Builder Classes may be logically divided into ―core‖ classes and ―peripheral‖ classes. The core
classes are central to the ABC Library—everything else is built from them or hangs off them. If you intend to study
the Application Builder Classes, you should begin with the core classes. Further, a thorough understanding of
these classes should give you an excellent foundation for understanding the ABC Template generated programs
and procedures that use these classes.

Even if you want to stay as far away from the ABC Library as possible, you should keep a couple of things in mind
with regard to the core classes:

• The core classes are ErrorClass, FieldPairsClass, FileManager, RelationManager, ViewManager,

WindowManager, and BrowseClass.

• Core classes are used repeatedly, so if you must modify them, try to keep them efficient.

• Core classes are almost certainly in any template based program, so additional references to them
generally won‘t affect the size of your executable.

There is a hierarchy within the core classes. The ErrorClass and the FieldPairsClass form the foundation upon
which the FileManager, RelationManager, and ViewManager rest. Finally, the BrowseClass, which is derived from
the ViewManager, tops off the core classes. The WindowManager is programmed to understand these core
classes and manages window procedures that use them.

WindowManager
BrowseClass
ViewManager
RelationManager
FileManager \
/ \
ErrorClass FieldPairsClass

To understand these core classes, we recommend you tackle the core classes first (ErrorClass and
FieldPairsClass), then work your way up to the WindowManager.
40 ABC Library Reference

ABC Library Source Files

The Application Builder Classes are installed by default to the Clarion \LIBSRC folder. The specific classes reside
in the following respective files. The core classes are shown in bold.

The class declarations reside in the .INC files, and their method definitions reside in the specified .CLW files.

ABASCII.INC
AsciiFileClass MODULE('ABASCII.CLW')
AsciiPrintClass MODULE('ABASCII.CLW')
AsciiSearchClass MODULE('ABASCII.CLW')
AsciiViewerClass MODULE('ABASCII.CLW')
ABBROWSE.INC
StepClass MODULE('ABBROWSE.CLW')
StepLongClass MODULE('ABBROWSE.CLW')
StepRealClass MODULE('ABBROWSE.CLW')
StepStringClass MODULE('ABBROWSE.CLW')
StepCustomClass MODULE('ABBROWSE.CLW')
LocatorClass MODULE('ABBROWSE.CLW')
StepLocatorClass MODULE('ABBROWSE.CLW')
EntryLocatorClass MODULE('ABBROWSE.CLW')
IncrementalLocatorClass MODULE('ABBROWSE.CLW')
ContractingLocatorClass MODULE('ABBROWSE.CLW')
EditClass MODULE('ABBROWSE.CLW')
BrowseClass MODULE('ABBROWSE.CLW')
ABDROPS.INC
FileDropClass MODULE('ABDROPS.CLW')
FileDropComboClass MODULE('ABDROPS.CLW')
ABC Library Overview 41

ABEIP.INC
EditClass MODULE('ABEIP.CLW')
EditCheckClass MODULE('ABEIP.CLW')
EditColorClass MODULE('ABEIP.CLW')
EditDropListClass MODULE('ABEIP.CLW')
EditEntryClass MODULE('ABEIP.CLW')
EditFileClass MODULE('ABEIP.CLW')
EditFontClass MODULE('ABEIP.CLW')
EditMultiSelectClass MODULE('ABEIP.CLW')
ABERROR.INC
ErrorClass MODULE('ABERROR.CLW')
ABFILE.INC
FileManager MODULE('ABFILE.CLW')
RelationUsage MODULE('ABFILE.CLW')
RelationManager MODULE('ABFILE.CLW')
ViewManager MODULE('ABFILE.CLW')
ABPOPUP.INC
PopupClass MODULE('ABPOPUP.CLW')
ABQUERY.INC
QueryClass MODULE('ABQUERY.CLW')
QueryVisualClass MODULE('ABQUERY.CLW')
QueryFormVisual MODULE('ABQUERY.CLW')
ABREPORT.INC
ProcessClass MODULE('ABREPORT.CLW')
PrintPreviewClass MODULE('ABREPORT.CLW')
ReportManager MODULE('ABREPORT.CLW')
ABRESIZE.INC
WindowResizeClass MODULE('ABRESIZE.CLW')
ABTOOLBA.INC
ToolbarTargetClass MODULE('ABTOOLBA.CLW')
ToolbarListboxClass MODULE('ABTOOLBA.CLW')
ToolbarReltreeClass MODULE('ABTOOLBA.CLW')
ToolbarUpdateClass MODULE('ABTOOLBA.CLW')
ToolbarClass MODULE('ABTOOLBA.CLW')
ABUTIL.INC
ConstantClass MODULE('ABUTIL.CLW')
FieldPairsClass MODULE('ABUTIL.CLW')
BufferedPairsClass MODULE('ABUTIL.CLW')
INIClass MODULE('ABUTIL.CLW')
DOSFileLookupClass MODULE('ABUTIL.CLW')
TranslatorClass MODULE('ABUTIL.CLW‘)
ABWINDOW.INC
WindowManager MODULE('ABWINDOW.CLW’)
42 ABC Library Reference

Including the right files in your data section

Many of the class declarations directly reference other classes. To resolve these references, each class header
(.INC file) INCLUDEs only the headers containing the directly referenced classes. This convention maximizes
encapsulation, minimizes compile times, and ensures that all necessary components are present for the make
process. We recommend you follow this convention too.

The Application Builder Classes source code is structured so that you can INCLUDE either the header or the
definition (.CLW file) in your program‘s data section. If you include the header, it references the required
definitions and vice versa.

A good rule of thumb is to INCLUDE as little as possible. The compiler will let you know if you have omitted
something.

ABC Library and the ABC Templates

The ABC Templates rely heavily on the ABC Library. However, the templates are highly configurable and are
designed to let you substitute your own class definitions if you wish. See Part I—Classes Tab Options (Global) for
more information on configuring the global level interaction between the ABC Templates and the ABC Library.
See Part I—Classes Tab Options (Local) for more information on configuring the local (module level) interaction
between the ABC Templates and the ABC Library.

Classes and Their Template Generated Objects

The ABC Templates instantiate objects from the ABC Library. The default template generated object names are
usually related to the corresponding class names, but they are not exactly the same. Your ABC applications‘
generated code may contain data declarations and executable statements similar to these:
GlobalErrors ErrorClass
Hide:Access:Customer CLASS(FileManager)
INIMgr INIClass
ThisWindow CLASS(ReportManager)
ThisWindow CLASS(WindowManager)
ThisReport CLASS(ProcessClass)
ThisProcess CLASS(ProcessClass)
BRW1 CLASS(BrowseClass)
EditInPlace::CUS:NAME EditClass
Resizer WindowResizeClass
Toolbar ToolbarClass
CODE
GlobalResponse = ThisWindow.Run()
BRW1.AddSortOrder(BRW1::Sort0:StepClass,ST:StKey)
BRW1.AddToolbarTarget(Toolbar)
GlobalErrors.Throw()
Resizer.AutoTransparent=True
Previewer.AllowUserZoom=True
ABC Library Overview 43

These data declarations instantiate objects from the ABC Library, and the executable statements reference the
instantiated objects. The various ABC classes and their template instantiations are listed below so you can
identify ABC objects in your applications‘ generated code and find the corresponding ABC Library documentation.

Template Generated Object Application Builder Class

Access:file FileManager
BRWn BrowseClass
BRWn::Sortn:Locator LocatorClass
BRWn::Sortn:StepClass StepClass
EditInPlace::field EditClass
FDBn FileDropClass
FDCBn FileDropComboClass
FileLookupN SelectFileClass
GlobalErrors ErrorClass
INIMgr INIClass
QBEn QueryClass
QBVn QueryVisualClass
Popup PopupClass
Previewer PrintPreviewClass
ProgressMgr StepClass
Relate:file RelationManager
RELn::Toolbar ToolbarReltreeClass
Resizer WindowResizeClass
ThisProcess ProcessClass
ThisReport ProcessClass
ThisWindow WindowManager, ReportManager
Toolbar ToolbarClass
ToolbarForm ToolbarUpdateClass
Translator TranslatorClass
ViewerN ASCIIViewerClass
44 ABC Library Reference

ABC Coding Conventions

The ABC Library uses several coding conventions. You may see instances of these code constructions in ABC
applications‘ generated code and in the ABC Library code. We recommend that you follow these conventions
within your embedded code.

Method Names
The following names have a specific meaning in the ABC Library. The names and their meanings are described
below.

AddItem
The object adds an item to its datastore. The item may be a field, a key, a sort order, a range limit, another object,
etc. The item may be anything the object needs to do its job.

Ask[Information]
The method interacts with the end user to get the Information.

Fetch
The method retrieves data from a file.

GetItem
The method returns the value of the named item.

Init
The method does whatever is required to initialize the object.

Kill
The method does whatever is required to shut down the object, including freeing any memory allocated during its
lifetime.

Reset[what or how]
The method resets the object and its controls. This includes reloading data, resetting sort orders, redrawing
window controls, etc.

SetItem
The method sets the value of the named item, or makes the named item active so that other object methods
operate on the active item.

TakeItem
The method ―takes‖ the item from another method or object and continues processing it. The item may be a
window event (Accepted, Rejected, OpenWindow, CloseWindow, Resize, etc.), a record, an error condition, etc.

Throw[Item]
The method ―throws‖ the item to another object or method for handling. The item is usually an error condition.
ABC Library Overview 45

TryAction
The method makes one attempt to carry out the action, then returns a value indicating success or failure. A return
value of zero (0 or Level:Benign) indicates success; any other value indicates failure.

Where to Initilize & Kill Objects

There are generally two factors to consider when initializing and killing objects:

• Generally, objects should live as short a life a possible

• Objects should always be Killed (to free any memory allocated during its lifetime)

Balancing these two (sometimes conflicting) factors dictates that objects Initialized with EVENT:OpenWindow are
usually Killed with EVENT:CloseWindow. Objects Initialized with ThisWindow.Init are usually Killed with
ThisWindow.Kill.

Return Values
Many ABC methods return a value indicating success or failure. A return value of zero (0 or Level:Benign)
indicates success. Any other return value indicates a problem whose severity may vary. Other return values and
their ABC severity EQUATEs (Level:User, Level:Cancel, Level:Notify, Level:Fatal, Level:Program) are
documented in the Error Class chapter and in the individual methods‘ documentation. This convention produces
code like the following:
IF ABCObject.Method()
!handle failure / error
ELSE

!continue normally
END

IF ~ABCObject.Method()
!continue normally
END

Event Processing Method Return Values

Some ABC methods process ACCEPT loop events. The names of these methods begin with ―Take‖ and usually
indicate the type of events they handle. These event processing methods execute within an ACCEPT loop (as
implemented by the WindowManager.Ask method) and return a value indicating how the ACCEPT loop should
proceed.

A return value of Level:Benign indicates processing of this event should continue normally. A return value of
Level:Notify indicates processing is completed for this event and the ACCEPT loop should CYCLE. A return value
of Level:Fatal indicates the event could not be processed and the ACCEPT loop should BREAK.

If you (or the ABC Templates) derive a class with any of these methods, you should use this return value
convention to control ACCEPT loop processing.

Following is the WindowManager.Ask method code that implements this convention. See WindowManager
Concepts for more information.
ACCEPT
CASE SELF.TakeEvent()
OF Level:Fatal
BREAK
OF Level:Notify
CYCLE
END
END
46 ABC Library Reference

Ending a Procedure

In your embedded code you may encounter a condition that requires the procedure to end immediately (that is, it
cannot wait for an EVENT:CloseWindow, or an EVENT:CloseWindow is not appropriate).

In some cases, a simple RETURN will not end your procedure (because a RETURN embedded within a derived
method ends the method, not the calling procedure), and even if it would, it might not be appropriate (because the
procedure may have allocated memory or started other tasks that should be ended in a controlled manner).

There are several ways you can initiate the normal shut down of your procedure, depending on where in the
procedure your code is embedded. Following are the conventional ways to shut down your procedure normally.
RETURN(Level:Fatal) !normal shutdown from ABC derived method

ReturnValue = Level:Fatal !normal shutdown at end of ABC derived method

ThisWindow.Kill !normal shutdown from Procedure Routine
ThisWindow.Kill;RETURN !normal shutdown from Procedure Routine
! called from within ACCEPT loop

PRIVATE (undocumented) Items

Some of the properties and methods in the ABC Library have the PRIVATE attribute. These PRIVATE items are
not documented. These items are PRIVATE because they are likely to change or disappear completely in future
ABC Library releases. Making some items PRIVATE, gives TopSpeed the flexibility to change and improve these
areas without affecting applications developed with the ABC Library. We strongly recommend that you do not
remove the PRIVATE attributes on ABC Library items.
ABC Library Overview 47

PROTECTED, VIRTUAL, DERIVED, and PROC Attributes

Some of the ABC Library properties and methods have special attributes that enhance their functionality, usability,
and maintainability. Each property and method topic shows any applicable attributes in the syntax diagram (gray
box). The purpose and effect of these attributes are documented here and in the Language Reference, but not in
individual property and method topics.

PROTECTED Attribute

The PROTECTED attribute specifies that the property or method on which it is placed is visible only to the
methods of the same CLASS or of derived CLASSes. This simply suggests that the property or method is
important to the correct functioning of the CLASS, and that any changes to these items should be done with care.
See PROTECTED in the Language Reference.

VIRTUAL Attribute

The VIRTUAL attribute allows methods in a parent CLASS to call methods in a derived CLASS. This has two
primary benefits. First, it allows parent CLASSes to delegate the implementation of certain actions to derived
classes; and second, it makes it easy for derived classes to override these same parent class actions. See
VIRTUAL in the Language Reference.

Virtual methods let you insert custom code into an existing class, without copying or duplicating the existing code.
Furthermore, the existing class calls the virtual methods (containing the custom code) as part of its normal
operation, so you don‘t have to explicitly call them. When TopSpeed updates the existing class, the updates are
automatically integrated into your application simply by recompiling. The existing class continues to call the virtual
methods containing the custom code as part of its normal operation. This approach gives you many opportunities
to customize your ABC applications while minimizing maintenance issues.

DERIVED Attribute

The DERIVED attribute is similar to the VIRTUAL attribute, except that it must have a matching prototype in the
parent class.

PROC Attribute

The PROC attribute may be placed on a method prototyped with a return value, so you can call the method and
ignore the return value without compiler warnings. See PROC in the Language Reference.
48 ABC Library Reference

Documentation Conventions
Reference Item and Syntax Diagram
The documentation formats for Properties and Methods are illustrated in the following syntax diagrams.

Property (short description of intended use)

Property Datatype [, PROTECTED ]

A complete description of the Property and its uses.

Datatype shows the datatype of the property such as LONG or &BrowseClass.

Implementation: A discussion of specific implementation issues. The implementation may change with each release /
version of Internet Connect.
ComplexDataType STRUCTURE !actual structure declaration

END

See Also: Related Methods and Properties

Method (short description of what the method does)

Method( | parameter1 | [, parameter2 ] ) [, PROTECTED ] [, VIRTUAL ] [, PROC ]

| alternate |
| parameters |

Method A brief statement of what the method does.

parameter1 A complete description of parameter1, along with how it relates to parameter2 and the Method.

parameter2 A complete description of parameter2, along with how it relates to parameter1 and the Method.
Brackets [ ] indicate optional parameters.

A concise description of what the Method does.

Implementation: A description of how the method currently accomplishes its objective. The implementation may change
with each release / version of Clarion.

Return Data Type: The data type returned if applicable.

Example:

FieldOne = FieldTwo + FieldThree !This is a source code example

FieldThree = Method(FieldOne,FieldTwo) !Comments follow the ―!‖ character

See Also: Related Methods and Properties

ABC Library Overview 49

Conceptual Example
A description of the type of example to be illustrated. Examples show the concept of how a specific class is
implemented in source code. The demands of brevity and concision often force the removal of structures which
are not essential in illustrating the class.

PROGRAM

MAP
END

! Data structures

CODE
! Code Statements
50 ABC Library Reference

ASCIIFileClass
ASCIIFileClass Overview
The ASCIIFileClass identifies, opens (read-only), indexes, and page-loads a file's contents into a QUEUE. The indexing
function speeds any additional access of records and supports page-loading, which in turn allows browsing of very large
files.

ASCIIFileClass Relationship to Other Application Builder Classes

There are several related classes whose collective purpose is to provide reusable, read-only, viewing, scrolling,
searching, and printing capability for files, including variable length files. Although these classes are primarily designed for
ASCII text and they anticipate using the Clarion ASCII Driver to access the files, they also work with binary files and with
other database drivers. These classes can be used to build other components and functionality as well.

The classes that provide this read-only functionality and their respective roles are:

ASCIIViewerClass ASCIIFileClass plus user interface

ASCIIFileClass Open, read, filter, and index the file
ASCIIPrintClass Print one or more lines
ASCIISearchClass Locate and scroll to text

The ASCIIViewerClass is derived from the ASCIIFileClass. See ASCIIViewerClass for more information.

ASCIIFileClass ABC Template Implementation

The ASCIIFileClass serves as the foundation to the Viewer procedure template; however, the ABC Templates do not
instantiate the ASCIIFileClass independently of the ASCIIViewerClass.

The ASCIIViewerClass is derived from the ASCIIFileClass, and the Viewer Procedure Template instantiates the derived
ASCIIViewerClass.

ASCIIFileClass Source Files

The ASCIIFileClass source code is installed by default to the Clarion \LIBSRC folder. The ASCIIFileClass source code are
contained in:

ABASCII.INC ASCIIFileClass declarations

ABASCII.CLW ASCIIFileClass method definitions
ASCIIFileClass 51

ASCIIFileClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
ASCIIFileClass object and related objects.

This example lets the end user select a file, then display it's pathname, total line count, and the text at a given percentage
point within the file.
PROGRAM
MAP
END
INCLUDE('ABASCII.INC') !declare ASCIIFileClass

Percentile BYTE(50) !a value between 1 & 100

GlobalErrors ErrorClass !declare GlobalErrors object
AFile AsciiFileClass,THREAD !declare AFile object
FileActive BYTE(False),THREAD !AFile initialized flag
Filename STRING(255),THREAD !FileName variable

AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1),THREAD
RECORD RECORD,PRE()
Line STRING(255)
END
END

window WINDOW('View a text file'),AT(3,7,203,63),SYSTEM,GRAY,DOUBLE

PROMPT('Show Line at Percentile'),AT(5,4),USE(?Prompt:Pct)
SPIN(@s3),AT(84,3,25,),USE(Percentile),RANGE(1,100)
BUTTON('New File'),AT(113,2),USE(?NewFileButton)
BUTTON('File Size'),AT(157,2),USE(?FileSizeButton)
PROMPT('Line:'),AT(4,26),USE(?Prompt:Line)
PROMPT(' '),AT(26,26,172,32),USE(?Line)
END
CODE
GlobalErrors.Init !initialize GlobalErrors object
OPEN(window) !Initialize AFile with:
FileActive=AFile.Init( AsciiFile, | ! file label,
A1:line, | !file field to display
Filename, | !variable file NAME attribute
GlobalErrors) !GlobalErrors object
IF FileActive
window{PROP:Text}=AFile.GetFileName()
ELSE
window{PROP:Text}='no file selected'
END

ACCEPT
CASE FIELD()
OF ?NewFileButton !on New File button
IF EVENT() = EVENT:Accepted
CLEAR(FileName)
FileActive=AFile.Reset(FileName) !reset AFile to a new file
IF FileActive
window{PROP:Text}=AFile.GetFileName() !show filename in titlebar
ELSE
window{PROP:Text}='no file selected'
END
END
52 ABC Library Reference

OF ?Percentile !on Percentile SPIN

CASE EVENT()
OF EVENT:Accepted OROF EVENT:NewSelection
IF FileActive !calculate lineno and get the line
?Line{PROP:Text}=AFile.GetLine(Percentile/100*AFile.GetLastLineNo())
ELSE
?Line{PROP:Text}='no file selected'
END
END
OF ?FileSizeButton !on File Size button
IF EVENT() = EVENT:Accepted
IF FileActive !display total line count
?FileSizeButton{PROP:Text}=AFile.GetLastLineNo()&' Lines'
ELSE
?FileSizeButton{PROP:Text}='0 Lines'
END
END
END
END
IF FileActive THEN AFile.Kill. !shut down AFile object
GlobalErrors.Kill
ASCIIFileClass 53

AsciiFileClass Properties

ASCIIFile (the ASCII file)

ASCIIFile &FILE
The File property is a reference to the managed file. The File property simply identifies the managed file for the various
ASCIIFileClass methods.

Implementation: The Init method initializes the File property.

See Also: Init

ErrorMgr (ErrorClass object)

ErrorMgr &ErrorClass, PROTECTED

The ErrorMgr property is a reference to the ErrorClass object for this ASCIIFileClass object. The ASCIIFileClass uses the
ErrorMgr to handle various errors and conditions it encounters when processing the file.

Implementation: The Init method initializes the ErrorMgr property.

See Also: Init

OpenMode (file access/sharing mode)

OpenMode BYTE
The OpenMode property contains a value that determines the level of access granted to both the user opening the file
and other users in a multi-user system.

Implementation: The Init method sets the OpenMode property to a hexadecimal value of 42h (ReadWrite/DenyNone). The
ABC Templates override this default with the appropriate value from the application generator.

The Open method uses the OpenMode property when it OPENs the file for processing. See the
Language Reference for more information on OPEN.

See Also: Init

54 ABC Library Reference

AsciiFileClass Methods
ASCIIFileClass Functional Organization--Expected Use
As an aid to understanding the ASCIIFileClass, it is useful to organize its methods into two large categories according to
their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the ASCIIFileClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

Init initialize the ASCIIFileClass object
Kill shut down the ASCIIFileClass object

Mainstream Use:
GetLastLineNo return last line number
GetLine return line of text
GetPercentile convert file position to percentage
SetPercentile convert percentage to file position

Occasional Use:
GetFilename return the filename
Reset reset the ASCIIFileClass object

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

GetDOSFilename prompt end user to select a file

FormatLine a virtual to format text
SetLine position to specific line
ValidateLine a virtual to implement a filter
ASCIIFileClass 55

FormatLine (a virtual to format text)

FormatLine( line [, line number ] ), PROTECTED, VIRTUAL

FormatLine A virtual placeholder method to format text.

line The label of the STRING variable containing the text to reformat.
line number An integer constant, variable, EQUATE or expression that contains the offset or position of the line of text
being formatted. If omitted, FormatLine operates on the current line.
The FormatLine method is a virtual placeholder method to reformat text prior to display at runtime.

Implementation: The FormatLine method is a placeholder for derived classes. It provides an easy way for you to reformat
the text prior to display. The GetLine method calls the FormatLine method.

Example:
INCLUDE('ABASCII.INC') !declare ASCIIViewerClass
MyViewer CLASS(AsciiViewerClass),TYPE !derive MyViewer class
FormatLine PROCEDURE(*STRING),VIRTUAL !prototype virtual FormatLine
END
Viewer MyViewer,THREAD !declare Viewer object
AsciiFile FILE,DRIVER('ASCII'),NAME('MyText'),PRE(A1),THREAD
RECORD RECORD,PRE()
Line STRING(255)
END
END
CODE
!program code

MyViewer.FormatLine PROCEDURE(*STRING line) !called by ASCIIViewerClass

CODE
line = line[1:5]' '&line[5:55] !reformat the text

See Also: GetLine

56 ABC Library Reference

GetDOSFilename (let end user select file)

GetDOSFilename( filename ), VIRTUAL

GetDOSFilename Prompts the end user to select the file to process.

filename The label of the ASCIIFile property's NAME attribute variable which receives the selected filename.
The GetDOSFilename method prompts the end user to select the file to process and returns a value indicating whether
the end user selected a file or did not select a file. A return value of one (1) indicates a file was selected and filename
contains its pathname; a retun value of zero (0) indicates no file was selected and filename is empty.

Implementation: The GetDOSFileName method uses a SelectFileClass object to get the filename from the end user.

Return Data Type: BYTE

Example:
MyAsciiFileClass.Reset FUNCTION(*STRING FName)
RVal BYTE(True)
SavePath CSTRING(FILE:MaxFilePath+1),AUTO
CODE
CLOSE(SELF.AsciiFile)
SavePath=PATH()
LOOP
IF ~FName AND ~SELF.GetDOSFilename(FName)
RVal=False
BREAK
END
OPEN(SELF.AsciiFile,ReadOnly+DenyNone)
IF ERRORCODE()
MESSAGE('Can't open ' & FName)
RVal=False
ELSE
BREAK
END
END
IF RVal
SELF.FileSize=BYTES(SELF.AsciiFile)
END
SETPATH(SavePath)
RETURN RVal

See Also: ASCIIFile, SelectFileClass

ASCIIFileClass 57

GetFilename (return the filename)

GetFilename
The GetFilename method returns the name of the ASCII file.

Implementation: The GetFileName method uses the NAME function. See the Language Reference for more information.

Return Data Type: STRING

Example:
INCLUDE('ABASCII.INC') !declare ASCIIViewerClass
Viewer AsciiViewerClass,THREAD !declare Viewer object
Filename STRING(255),THREAD !declare filename variable
AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1),THREAD
RECORD RECORD,PRE()
Line STRING(255)
END
END
CODE
!program code
MESSAGE('Filename:'&Viewer.GetFilename()) !get the ASCII filename
58 ABC Library Reference

GetLastLineNo (return last line number)

GetLastLineNo, PROC
The GetLastLineNo method returns the number of the last line in the file, and indexes the entire file.

Return Data Type: LONG

Example:
MyViewer.TakeScroll PROCEDURE(UNSIGNED EventNo)
LineNo LONG
CODE
IF FIELD()=SELF.ListBox
IF EVENT() = EVENT:ScrollBottom !on scroll bottom
LineNo = SELF.GetLastLineNo() !index to end of file
SELF.DisplayPage(LineNo-SELF.ListBoxItems+1) !display last page
SELECT(SELF.ListBox,SELF.ListBoxItems) !highlight last row
END
END
ASCIIFileClass 59

GetLine (return line of text)

GetLine( line number ), PROC

GetLine Returns a line of text.

line number An integer constant, variable, EQUATE or expresssion that contains the offset or position of the line of
text to return.
The GetLine method returns the line of text specifiedby line number.

Implementation: The GetLine method gets a line at position line number from the ASCII file, extending the index queue if
needed. If the index queue already contains the requested line number then the file is read using the
existing offset, otherwise the index is extended. If the requested line number does not exist in the file, the
text line is cleared and ERRORCODE() set.

Return Data Type: STRING

Example:
MyViewer.DisplayPage PROCEDURE(LONG LineNo)
LineOffset USHORT,AUTO
CODE
IF LineNo > 0 !line specified?
SELF.ListBoxItems=SELF.ListBox{PROP:Items} !note size of list box
FREE(SELF.DisplayQueue) !free the display queue
SELF.GetLine(LineNo+SELF.ListBoxItems-1) !index to end of page
LOOP LineOffset=0 TO SELF.ListBoxItems-1 !for each listbox line
SELF.DisplayQueue.Line=SELF.GetLine(LineNo+LineOffset) !read ASCII file record
IF ERRORCODE() !on end of file
BREAK ! stop reading
END
ADD(SELF.DisplayQueue) !add to display queue
END
SELF.TopLine=LineNo !note 1st line displayed
DISPLAY(SELF.ListBox) !redraw the list box
END

See Also: GetLine

60 ABC Library Reference

GetPercentile (convert file position to percentage:ASCIIFileClass)

GetPercentile( line number )

GetPercentile Returns the specified position in the file as a percentage.

line number An integer constant, variable, EQUATE or expresssion that contains the offset or position to convert to a
percentage.
The GetPercentile method returns the specified position in the file as an approximate percentage which can be used to
position a vertical scroll bar thumb.

Return Data Type: USHORT

Example:
SetThumb ROUTINE
!current line is what % thru the file?
PctPos=MyASCIIFile.GetPercentile(MyASCIIFile.TopLine+CHOICE(?ASCIIBox) -1)
?ASCIIBox{PROP:VScrollPos}=PctPos !set thumb to corresponding % position
ASCIIFileClass 61

Init (initialize the ASCIIFileClass object)

Init( file, field [,filename], error handler )

Init Initializes the ASCIIFileClass object.

file The label of the file to display.
field The fully qualified label of the file field to display.
filename The label of the file's NAME attribute variable. If omitted, the file has a constant NAME attribute. If null (''), the
ASCIIFileClass prompts the end user to select a file.
error handler The label of the ErrorClass object to handle errors encountered by this ASCIIFileClass object.
The Init method initializes the ASCIIFileClass object and returns a value indicating whether it successfully accessed the
file and is ready to proceed.

Implementation: The Init method returns one (1) if it accessed the file and is ready to proceed; it returns zero (0) and calls
the Kill method if unable to access the file and cannot proceed. If the Init method returns zero (0), the
ASCIIFileClass object is not initialized and you should not call its methods.

Return Data Type: BYTE

Example:
Filename STRING(255),THREAD !declare filename variable
FileActive BYTE !declare success/fail switch
AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1)
RECORD RECORD,PRE()
Line STRING(255)
END
END
CODE !init ASCIIFileClass object with:
FileActive=ASCIIFile.Init(AsciiFile, | ! file label
A1:Line, | ! file field to display
Filename, | ! NAME attribute variable
GlobalErrors) ! ErrorClass object
IF ~FileActive THEN RETURN. !If init failed, don't proceed
ACCEPT !If init succeeded, proceed
IF EVENT() = EVENT:CloseWindow
IF FileActive THEN ASCIIFile.Kill. !If init succeeded, shut down
END !program code
END

See Also: Kill

62 ABC Library Reference

Kill (shut down the ASCIIFileClass object)

Kill
The Kill method frees any memory allocated during the life of the object and performs any other required termination
code.

Example:
Filename STRING(255),THREAD !declare filename variable
FileActive BYTE !declare success/fail switch
AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1)
RECORD RECORD,PRE()
Line STRING(255)
END
END
CODE !init ASCIIFileClass object with:
FileActive=ASCIIFile.Init(AsciiFile,| ! file label
A1:Line, | ! file field to display
Filename, | ! NAME attribute variable
GlobalErrors) ! ErrorClass object
IF ~FileActive THEN RETURN. !If init failed, don't proceed
ACCEPT !If init succeeded, proceed
IF EVENT() = EVENT:CloseWindow
IF FileActive THEN ASCIIFile.Kill. !If init succeeded, shut down
END
!program code
END
ASCIIFileClass 63

Reset (reset the ASCIIFileClass object)

Reset( filename )

Reset Resets the ASCIIFileClass object.

filename The label of the ASCIIFile property's NAME attribute variable.
The Reset method resets the ASCIIFileClass object and returns a value indicating whether the end user selected a file or
did not select a file. A return value of one (1) indicates a file was selected and filename contains its pathname; a retun
value of zero (0) indicates no file was selected and filename is empty.

Implementation: The Reset method calls the GetDOSFileName method to get the filename from the end user. Reset
opens the file and resets any statistics and flags associated with the selected file.

Return Data Type: BYTE

Example:
AsciiViewerClass.Reset FUNCTION(*STRING Filename)
CODE
FREE(SELF.DisplayQueue)
DISPLAY(SELF.ListBox)
IF ~PARENT.Reset(Filename) THEN RETURN False.
SELF.TopLine=1
SELF.DisplayPage
SELECT(SELF.ListBox,1)
RETURN True

See Also: ASCIIFile, GetDOSFilename

64 ABC Library Reference

SetLine (a virtual to position the file)

SetLine( line number ), PROTECTED, VIRTUAL

SetLine A virtual placeholder method to position the file.

line number The offset or position of the line in the file.
The SetLine method is a virtual placeholder method to position the file.

Implementation: The SetLine method is a placeholder for derived classes. The SetPercentile, the
ASCIIViewerClass.AskGotoLine, and the ASCIISearchClass.Ask methods call the SetLine method.

Example:
MyViewerClass.SetLine PROCEDURE(LONG LineNo) !synchronize LIST with line number
CODE
SELF.DisplayPage(LineNo) !scroll list to LineNo
!highlight the LineNo line
SELECT(SELF.ListBox,CHOOSE(SELF.TopLine=LineNo,1,LineNo-SELF.TopLine+1))

See Also: SetPercentile, ASCIIViewerClass.AskGoToLine, ASCIISearchClass.Ask

ASCIIFileClass 65

SetPercentile (set file to relative position)

SetPercentile( percentile )

SetPercentile Positions the file to the record nearest to

file size * percentile / 100.
percentile A value between 0 and 100 that indicates a relative position within the file. This value may be set by a
vertical scrollbar thumb position.
The SetPercentile method positions the file to the record nearest to
file size * percentile / 100. You may use SetPercentile to position the file based on the end user's vertical scrollbar thumb
setting.

Implementation: The SetPercentile method positions the file based on a given percentage (usually determined by the
vertical thumb position). SetPercentile extends the index as required and calls the virtual SetLine method
to postion the file.

SetPercentile calculates the position by dividing percentile by 100 then multiplying the resulting
percentage times the file size.

Example:
MyViewerClass.TakeDrag PROCEDURE(UNSIGNED EventNo)
CODE
IF FIELD()=SELF.ListBox
IF EventNo = EVENT:ScrollDrag
SELF.SetPercentile(SELF.ListBox{PROP:VScrollPos}) !reposition based on thumb
END
END

See Also: SetLine

66 ABC Library Reference

ValidateLine (a virtual to implement a filter)

ValidateLine( line ), PROTECTED, VIRTUAL

ValidateLine A virtual placeholder method to implement a filter.

line The offset or position of the line of text to evaluate.
The ValidateLine method is a virtual placeholder method to implement a filter. ValidateLine returns one (1) to include the
line and zero (0) to exclude the line.

Implementation: The ValidateLine method is a placeholder method for derived classes. The ASCIIFileClass calls the
ValidateLine method when it initially reads a record.

Return Data Type: BYTE

Example:
MyFileClass.ValidateLine FUNCTION(STRING LineToTest)

CODE
IF LineToTest[1] = '!' !check for ! in column 1
RETURN False !exclude lines with !
ELSE
RETURN True !include all other lines
END
ASCIIFileClass 67
68 ABC Library Reference

ASCIIPrintClass
ASCIIPrintClass Overview
The ASCIIPrintClass provides the user interface--a simple Print Options dialog--to print one or more lines from a text file.
The ASCIIPrintClass interface lets the end user specify a range of lines to print, then optionally previews the lines before
printing them. The ASCIIPrintClass interface also provides access to the standard Windows Print Setup dialog.

ASCIIPrintClass Relationship to Other Application Builder Classes

The ASCIIPrintClass relies on the ASCIIFileClass to read and index the file that it prints. It also relies on the
PrintPreviewClass to provide the on-line preview. It also uses the TranslatorClass to translate its Print Options dialog text
if needed.

The ASCIIViewerClass uses the ASCIIPrintClass to provide the end user with a Print Options dialog to print one or more
lines from the viewed file.

There are several related classes whose collective purpose is to provide reusable, read-only, viewing, scrolling,
searching, and printing capability for files, including variable length files. Although these classes are primarily designed for
ASCII text and they anticipate using the Clarion ASCII Driver to access the files, they also work with binary files and with
other database drivers. These classes can be used to build other components and functionality as well.

The classes that provide this read-only functionality are:

ASCIIViewerClass ASCIIFileClass plus user interface

ASCIIFileClass Open, read, filter, and index the file
ASCIIPrintClass Print one or more lines
ASCIISearchClass Locate and scroll to text

ASCIIPrintClass ABC Template Implementation

Both the Viewer procedure template and the ASCIIPrintButton control template generate code to instantiate an
ASCIIPrintClass object. The Viewer template accomplishes this by adding a parameter to the ASCIIViewerClass.Init
method. The ASCIIPrintButton template accomplishes this by declaring an ASCIIPrintClass object and calling the
ASCIIViewerClass.AddItem method to register the ASCIIPrintClass object with the ASCIIViewerClass object.
ASCIIPrintClass 69

ASCIIPrintClass Source Files

The ASCIIPrintClass source code is installed by default to the Clarion \LIBSRC folder. The specific ASCIIPrintClass
source code and their respective components are contained in:

ABASCII.INC ASCIIPrintClass declarations

ABASCII.CLW ASCIIPrintClass method definitions

ASCIIPrintClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate an
ASCIIPrintClass object and related objects.

This example lets the end user select a file, then search and print from it.
MEMBER('viewer.clw')

INCLUDE('ABASCII.INC')
INCLUDE('ABWINDOW.INC')

MAP
MODULE('VIEWE002.CLW')
BrowseFiles PROCEDURE
END
END

BrowseFiles PROCEDURE

FilesOpened BYTE
ViewerActive BYTE(False)
Filename STRING(FILE:MaxFilePath),AUTO,STATIC,THREAD
AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1),THREAD
RECORD RECORD,PRE()
Line STRING(255)
END
END
ViewWindow WINDOW('View an ASCII File'),AT(3,7,296,136),SYSTEM,GRAY
LIST,AT(5,5,285,110),USE(?AsciiBox),IMM,FROM('')
BUTTON('&Print...'),AT(7,119),USE(?Print)
BUTTON('&Search...'),AT(44,119),USE(?Search)
END
ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
TakeAccepted PROCEDURE(),BYTE,PROC,VIRTUAL
END

Viewer AsciiViewerClass !declare Viewer object

Searcher AsciiSearchClass !declare Searcher object
Printer AsciiPrintClass !declare Printer object

CODE
GlobalResponse = ThisWindow.Run()

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Init()
IF ReturnValue THEN RETURN ReturnValue.
70 ABC Library Reference

SELF.FirstField = ?AsciiBox
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
OPEN(ViewWindow)
SELF.Opened=True
CLEAR(Filename)
ViewerActive=Viewer.Init(AsciiFile,A1:Line,Filename,?AsciiBox,GlobalErrors)
IF ~ViewerActive THEN RETURN Level:Fatal.
Viewer.AddItem(Searcher) !register Searcher with Viewer
Viewer.AddItem(Printer) !register Printer with Viewer
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.TakeAccepted PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.TakeAccepted()
CASE ACCEPTED()
OF ?Print
ThisWindow.Update
IF ViewerActive THEN Viewer.Printer.Ask. !display Print Options dialog
OF ?Search
ThisWindow.Update
IF ViewerActive
IF CHOICE(?AsciiBox)>0 !search from current line
Viewer.Searcher.Ask(Viewer.TopLine+CHOICE(?AsciiBox)-1)
ELSE
Viewer.Searcher.Ask(1) !search from line 1
END
END
END
RETURN ReturnValue
ASCIIPrintClass 71

AsciiPrintClass Properties
FileMgr (AsciiFileClass object:AsciiPrintClass)
FileMgr &AsciiFileClass, PROTECTED
The FileMgr property is a reference to the AsciiFileClass object that manages the file to print. The AsciiPrintClass object
uses the FileMgr to read the file, manage print range line numbers and to handle error conditions and messages.

Implementation: The Init method initializes the FileMgr property.

See Also: Init

PrintPreview (print preview switch)

PrintPreview BYTE
The PrintPreview property contains the print preview setting for the AsciiPrintClass object. A value of one (1 or True)
initially "checks" the print preview box (default is preview); a value of zero (0 or False) "clears" the print preview box
(default is no preview).

Implementation: The Init method sets the PrintPreview property to false. The PrintLines method implements the action
specified by the PrintPreview property.

See Also: Init, PrintLines

Translator (TranslatorClass object:AsciiPrintClass)

Translator &TranslatorClass, PROTECTED
The Translator property is a reference to the TranslatorClass object for the AsciiPrintClass object. The AsciiPrintClass
object uses this property to translate text in the object's Print Options dialog to the appropriate language.

Implementation: The AsciiPrintClass does not initialize the Translator property. The AsciiPrintClass only invokes the
Translator if the Translator property is not null. You can use the AsciiViewerClass.SetTranslator method
or a reference assignment statement to set the Translator property.

See Also: AsciiViewerClass.SetTranslator

72 ABC Library Reference

AsciiPrintClass Methods
Ask (solicit print specifications)

Ask, VIRTUAL
The Ask method displays a Print Options dialog that prompts the end user for print specifications, then prints the selected
lines subject to those specifications (printer destination, paper orientation, etc.).

Implementation: The Ask method prompts the end user for print specifications (including the Windows standard Print
Setup dialog), print preview, plus a range of lines to print. If the user CLICKS the Print button, the Ask
method prints the requested lines to the printer specified by the end user.

Example:
ACCEPT
CASE FIELD()
OF ?PrintButton !on "Print" button
IF EVENT() = EVENT:Accepted !call the Printer.Ask method
IF ViewerActive THEN Viewer.Printer.Ask. !to gather specs and print lines
END
END
END
ASCIIPrintClass 73

Init (initialize the ASCIIPrintClass object)

Init( ASCIIFileMgr ), VIRTUAL

Init Initializes the ASCIIPrintClass object.

ASCIIFileMgr The label of the ASCIIFileClass object that manages the file to print. The ASCIIPrintClass object uses the
ASCIIFileMgr to read from the file and handle line numbers and error conditions.
The Init method initializes the ASCIIPrintClass object.

Example:
MyViewerClass.Init FUNCTION(FILE AsciiFile,*STRING FileLine,*STRING Filename,|
UNSIGNED ListBox,ErrorClass ErrHandler,BYTE Enables)
CODE
!program code
IF BAND(Enables,EnableSearch) !if Search flag is on
SELF.Searcher &= NEW AsciiSearchClass !instantiate Searcher object
SELF.Searcher.Init(SELF) !initialize Searcher object
END
IF BAND(Enables,EnablePrint) !if Print flag is on
SELF.Printer &= NEW AsciiPrintClass !instantiate Printer object
SELF.Printer.Init(SELF) !initialize Printer object
END
74 ABC Library Reference

PrintLines (print or preview specified lines)

PrintLines( first, last ), VIRTUAL

PrintLines Prints or previews the specified lines.

first An integer constant, variable, EQUATE, or expression containing the number of the first line of the range
of lines to print.
last An integer constant, variable, EQUATE, or expression containing the number of the last line of the range
of lines to print.
If the PrintPreview property is True, the PrintLines method previews the specified lines, then prints the lines or not,
depending on the end user's response to the preview.

If the PrintPreview property is False, the PrintLines method prints the specified lines to the selected printer.

Example:
IF EVENT() = EVENT:Accepted
IF ACCEPTED() = ?PrintButton
FirstLine=1
LastLine=HighestLine
SELF.PrintLines(FirstLine,LastLine)
POST(EVENT:CloseWindow)
END
END

See Also: PrintPreview

ASCIIPrintClass 75
76 ABC Library Reference

ASCIISearchClass
ASCIISearchClass Overview
The ASCIISearchClass provides the user interface--a persistent non-MDI Find dialog--to locate specific text within the
browsed file. The ASCIISearchClass interface lets the end user specify the direction and case sensitivity of the search,
and it allows repeating searches ("find next").

ASCIISearchClass Relationship to Other Application Builder Classes

The ASCIISearchClass relies on the ASCIIFileClass to read and index the file that it searches. It also uses the
TranslatorClass to translate its Find dialog text if needed.

The ASCIIViewerClass uses the ASCIISearchClass to provide the end user with a Find dialog to locate text in the viewed
file.

There are several related classes whose collective purpose is to provide reusable, read-only, viewing, scrolling,
searching, and printing capability for files, including variable length files. Although these classes are primarily designed for
ASCII text and they anticipate using the Clarion ASCII Driver to access the files, they also work with binary files and with
other database drivers. These classes can be used to build other components and functionality as well.

The classes that provide this read-only functionality and their respective roles are:

ASCIIViewerClass ASCIIFileClass plus user interface

ASCIIFileClass Open, read, filter, and index the file
ASCIISearchClass Print one or more lines
ASCIISearchClass Locate and scroll to text

ASCIISearchClass ABC Template Implementation

Both the Viewer procedure template and the ASCIISearchButton control template generate code to instantiate an
ASCIISearchClass object. The Viewer template accomplishes this by adding a parameter to the ASCIIViewerClass.Init
method. The ASCIISearchButton template accomplishes this by declaring an ASCIISearchClass object and calling the
ASCIIViewerClass.AddItem method to register the ASCIISearchClass object with the ASCIIViewerClass object.

ASCIISearchClass Source Files

The ASCIISearchClass source code is installed by default to the Clarion \LIBSRC folder. The specific ASCIISearchClass
source code and their respective components are contained in:

ABASCII.INC ASCIISearchClass declarations

ABASCII.CLW ASCIISearchClass method definitions

ASCIISearchClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate an
ASCIISearchClass object and related objects.

This example lets the end user select a file, then search and print from it.
MEMBER('viewer.clw')

INCLUDE('ABASCII.INC')
INCLUDE('ABWINDOW.INC')

MAP
MODULE('VIEWE002.CLW')
BrowseFiles PROCEDURE
ASCIISearchClass 77

END
END

BrowseFiles PROCEDURE

FilesOpened BYTE
ViewerActive BYTE(False)
Filename STRING(FILE:MaxFilePath),AUTO,STATIC,THREAD
AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1),THREAD
RECORD RECORD,PRE()
Line STRING(255)
END
END

ViewWindow WINDOW('View an ASCII File'),AT(3,7,296,136),SYSTEM,GRAY

LIST,AT(5,5,285,110),USE(?AsciiBox),IMM,FROM('')
BUTTON('&Print...'),AT(7,119),USE(?Print)
BUTTON('&Search...'),AT(44,119),USE(?Search)
END
ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
TakeAccepted PROCEDURE(),BYTE,PROC,VIRTUAL
END

Viewer AsciiViewerClass !declare Viewer object

Searcher AsciiSearchClass !declare Searcher object
Printer AsciiPrintClass !declare Printer object

CODE
GlobalResponse = ThisWindow.Run()

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Init()
IF ReturnValue THEN RETURN ReturnValue.
SELF.FirstField = ?AsciiBox
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
OPEN(ViewWindow)
SELF.Opened=True
CLEAR(Filename)
ViewerActive=Viewer.Init(AsciiFile,A1:Line,Filename,?AsciiBox,GlobalErro rs)
IF ~ViewerActive THEN RETURN Level:Fatal.
Viewer.AddItem(Searcher) !register Searcher with Viewer
Viewer.AddItem(Printer) !register Printer with Viewer
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.TakeAccepted PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.TakeAccepted()
CASE ACCEPTED()
OF ?Print
ThisWindow.Update
IF ViewerActive THEN Viewer.Printer.Ask. !display Print Options dialog
OF ?Search
ThisWindow.Update
78 ABC Library Reference

IF ViewerActive
IF CHOICE(?AsciiBox)>0 !search from current line
Viewer.Searcher.Ask(Viewer.TopLine+CHOICE(?AsciiBox)-1)
ELSE
Viewer.Searcher.Ask(1) !search from line 1
END
END
END
RETURN ReturnValue
ASCIISearchClass 79

AsciiSearchClass Properties
Find (search constraints)

Find FindGroup, PROTECTED

The Find property contains the current search criteria or specification.

Implementation: The search specification includes the text to search for, the direction in which to search, and whether or
not the search is case sensitive.

The Ask method sets the values of the Find property based on end user input to the Find dialog. The
Setup method sets the values of the Find property for use without the Ask method. The Next method
implements the seach specified by the Find property.

The FindGroup data type is declared in ABASCII.INC as follows:

FindGroup GROUP,TYPE
What PSTRING(64) !text to look for
MatchCase BYTE !case sensitive?
Direction STRING(4) !either 'Up ' or 'Down'
END

See Also: Ask, Next, Setup

80 ABC Library Reference

FileMgr (AsciiFileClass object:AsciiSearchClass)

FileMgr &AsciiFileClass, PROTECTED
The FileMgr property is a reference to the AsciiFileClass object tyhat manages the file to search. The AsciiSearchClass
object uses the FileMgr to read the file, and to handle error conditions and messages.

Implementation: The Init method initializes the FileMgr property.

See Also: Init

LineCounter (current line number)

LineCounter LONG, PROTECTED
The LineCounter property contains the current line number of the searched file.

Implementation: The ASCIISearchClass object uses the LineCounter property to implement "find next" searches--searches
that continue from the current line.

Translator (TranslatorClass object:ASCIISearchClass)

Translator &TranslatorClass, PROTECTED
The Translator property is a reference to the TranslatorClass object for the ASCIISearchClass object. The
ASCIISearchClass object uses this property to translate window text to the appropriate language.

Implementation: The ASCIISearchClass does not initialize the Translator property. The ASCIISearchClass only invokes
the Translator if the Translator property is not null. You can use the AsciiViewerClass.SetTranslator
method to set the Translator property.

See Also: AsciiViewerClass.SetTranslator

ASCIISearchClass 81

AsciiSearchClass Methods
Ask (solicit search specifications)

Ask( [startline] ), VIRTUAL

Ask Prompts the end user for search specifications then positions to the specified search value.
startline The offset or position of the line at which to begin the search, typically the current line position. If omitted,
startline defaults to one (1).
The Ask method prompts the end user for search specifications then positions the file to the next line subject to the
search specifications, or issues an appropriate message if the search value is not found.

Implementation: The Ask method prompts the end user for search specifications including a value to search for, the
direction of the search, and whether the search is case sensitive. If the user invokes the search (doesn't
cancel), the Ask method positions the file to the next line containing the search value, or issues an
appropriate message if the search value is not found.

Example:
ACCEPT
CASE FIELD()
OF ?PrintButton
IF EVENT() = EVENT:Accepted
IF ViewerActive THEN Viewer.Printer.Ask.
END
OF ?Search !on "search" button
IF EVENT() = EVENT:Accepted
IF ViewerActive !call Searcher.Ask method
StartSearch=CHOOSE(CHOICE(?AsciiBox)>0, | ! passing the currently
Viewer.TopLine+CHOICE(?AsciiBox)-1,1) ! selected line as the
Viewer.Searcher.Ask(StartSearch) ! search's starting point
END
END
END
END
82 ABC Library Reference

Init (initialize the ASCIISearchClass object)

Init( ASCIIFileMgr ), VIRTUAL

Init Initializes the ASCIISearchClass object.

ASCIIFileMgr The label of the ASCIIFileClass object that manages the file to search. The ASCIISearchClass object
uses the ASCIIFileMgr to read from the file.
The Init method initializes the ASCIISearchClass object.

Example:
MyViewerClass.Init FUNCTION(FILE AsciiFile,*STRING FileLine,*STRING Filename,|
UNSIGNED ListBox,ErrorClass ErrHandler,BYTE Enables)
CODE
!program code
IF BAND(Enables,EnableSearch) !if Search flag is on
SELF.Searcher &= NEW AsciiSearchClass !instantiate Searcher object
SELF.Searcher.Init(SELF) !initialize Searcher object
END
IF BAND(Enables,EnablePrint) !if Print flag is on
SELF.Printer &= NEW AsciiPrintClass !instantiate Printer object
SELF.Printer.Init(SELF) !initialize Printer object
END
ASCIISearchClass 83

Next (find next line containing search text)

Next, VIRTUAL
The Next method returns the line number of the next line containing the search value specified by the Ask method.

Implementation: The Ask method calls the Next method. The Next method searches for the search value and in the
direction set by the Ask method. Alternatively, you can use the Setup method to set the search
constraints.

Return Data Type: LONG

Example:
MyAsciiSearchClass.Ask PROCEDURE
CODE
!procedure code
CASE EVENT()
OF EVENT:Accepted
CASE FIELD()
OF ?NextButton
SELF.LineCounter=SELF.Next()
IF SELF.LineCounter
SELF.FileMgr.SetLine(SELF.LineCounter)
END
!procedure code

See Also: Ask, Setup

84 ABC Library Reference

Setup (set search constraints)

Setup( constraints [, startline] )

Setup Sets the search constraints.

constraints The label of a structure containing the search constraints. The structure must have the same structure as
the FindGroup GROUP declared in ABASCII.INC.
startline The offset or position of the line at which to begin the search, typically the current line position. If omitted,
startline defaults to one (1).
The Setup method sets the search constraints. The AsciiSearchClass object applies the constraints when searching the
text file.

Implementation: The ABC Library does not call the Setup method. The Setup method is provided so you can do custom
searches outside the normal AsciiViewerClass process (without using the Ask method).

The Next method applies the search constraints set by the Setup method. The constraints include the text
to search for, the direction in which to search, and whether or not the search is case sensitive.

The FindGroup GROUP is declared in ABASCII.INC as follows:

FindGroup GROUP,TYPE
What PSTRING(64) !text to look for
MatchCase BYTE !case sensitive?
Direction STRING(4) !either 'Up ' or 'Down'
END

Example:
MyAsciiSearchClass.Ask PROCEDURE
Constraints LIKE(FindGroup)
CODE
Constraints.MatchCase = False !never case sensitive
Constraints.Direction = 'Down' !always search downward
!prompt end user for search value
SELF.Setup(Constraints,StartLine) !set search constraints
SELF.LineCounter=SELF.Next() !execute search
IF SELF.LineCounter
SELF.FileMgr.SetLine(SELF.LineCounter) !set to next line containing search value
ELSE
MESSAGE(''''&CLIP(SELF.Constraints.What)&''' not found.')
END

See Also: Ask, Next

ASCIIViewerClass 85
86 ABC Library Reference

ASCIIViewerClass
ASCIIViewerClass Overview
There are several related classes whose collective purpose is to provide reusable, read-only, viewing, scrolling,
searching, and printing capability for files, including variable length files. Although these classes are primarily designed for
ASCII text and they anticipate using the Clarion ASCII Driver to access the files, they also work with binary files and with
other database drivers. These classes can be used to build other components and functionality as well.

The classes that provide this read-only functionality are the ASCII Viewer classes. The ASCII Viewer classes and their
respective roles are:

ASCIIViewerClass Supervisor class

ASCIIFileClass Open, read, filter, and index the file
ASCIIPrintClass Print one or more lines
ASCIISearchClass Locate and scroll to text

These classes are fully documented in the remainder of this chapter.

ASCIIViewerClass

The ASCIIViewerClass uses the ASCIIFileClass, the ASCIIPrintClass, and the ASCIISearchClass to create a single full
featured ASCII file viewer object. This object uses a LIST control to display, scroll, search, and print the contents of the
file. Typically, you instantiate only the ASCIIViewerClass in your program which, in turn, instantiates the other classes as
needed.

ASCIIFileClass

The ASCIIFileClass identifies, opens (read-only), indexes, and page-loads a file's contents into a QUEUE. The indexing
function speeds any reaccess of records and supports page-loading, which in turn allows browsing of very large files.

ASCIIPrintClass

The ASCIIPrintClass lets the end user specify a range of lines to print, then prints them. It also provides access to the
standard Windows Print Setup dialog.

ASCIISearchClass

The ASCIISearchClass lets the end user specify a search value, case sensitivity, and a search direction, then scrolls to
the next instance of the search value within the file.
ASCIIViewerClass 87

ASCIIViewerClass Relationship to Other Application Builder Classes

The ASCIIViewerClass is derived from the ASCIIFileClass, plus it relies on the ASCIIPrintClass, ASCIISearchClass,
ErrorClass, and PopupClass to accomplish some user interface tasks. Therefore, if your program instantiates the
ASCIIViewerClass, it must also instantiate these other classes. Much of this is automatic when you INCLUDE the
ASCIIViewerClass header (ABASCII.INC) in your program's data section. See the Conceptual Example.

ASCIIViewerClass ABC Template Implementation

The ABC Templates declare a local ASCIIViewer class and object for each instance of the ASCIIViewControl template.
The ABC Templates automatically include all the classes necessary to support the functionality specified in the
ASCIIViewControl template.

The templates derive a class from the ASCIIViewerClass for each ASCIIViewerClass in the application. The derived class
is called procedure:Viewer# where procedure is the procedure name and # is the instance number of the
ASCIIViewControl template. The templates provide the derived class so you can use the ASCIIViewControl template
Classes tab to easily modify the viewer's behavior on an instance-by-instance basis.

The object is named Viewer# where # is the instance number of the control template. The derived ASCIIViewerClass is
local to the procedure, is specific to a single ASCIIViewerClass and relies on the global ErrorClass object.

ASCIIViewerClass Source Files

The ASCIIViewerClass source code is installed by default to the Clarion \LIBSRC folder. The specific ASCIIViewerClass
source code and their respective components are contained in:

ABASCII.INC ASCIIViewerClass declarations

ABASCII.CLW ASCIIViewerClass method definitions

88 ABC Library Reference

ASCIIViewerClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate an
ASCIIViewerClass object and related objects.

This example lets the end user select a file, then browse, scroll, search, and print from it.
PROGRAM
MAP
END

INCLUDE('ABASCII.INC') !declare ASCIIViewer Class

ViewWindow WINDOW('View a text file'),AT(3,7,296,136),SYSTEM,GRAY

LIST,AT(5,5,285,110),USE(?AsciiBox),IMM
BUTTON('&Print'),AT(5,120),USE(?Print)
BUTTON('&Search'),AT(45,120),USE(?Search)
BUTTON('&Close'),AT(255,120),USE(?Close)
END
GlobalErrors ErrorClass !declare GlobalErrors object
Viewer AsciiViewerClass,THREAD !declare Viewer object

ViewerActive BYTE(False),THREAD !Viewer initialized flag

Filename STRING(255),THREAD !FileName variable
StartSearch LONG !hold selected line number

AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1),THREAD
RECORD RECORD,PRE()
Line STRING(255)
END
END
CODE

GlobalErrors.Init !initialize GlobalErrors object

OPEN(ViewWindow) !open the window
!Initialize Viewer with:
ViewerActive=Viewer.Init( AsciiFile, | ! file label,
A1:line, | ! file field to display
Filename, | ! variable file NAME attribute
?AsciiBox, | ! LIST control number
GlobalErrors, | ! ErrorClass object
EnableSearch+EnablePrint) ! features to implement flag
IF ~ViewerActive THEN RETURN. !if init unsuccessful, don't
! call other Viewer methods
ASCIIViewerClass 89

AsciiViewerClass Properties
Popup (PopupClass object)
Popup &PopupClass
The Popup property is a reference to the PopupClass object for this ASCIIViewerClass object. The ASCIIViewerClass
object uses the Popup property to define and manage its popup menus.

Implementation: The Init method initializes the Popup property.

See Also: Init

Printer (ASCIIPrintClass object)

Printer &ASCIIPrintClass
The Printer property is a reference to the ASCIIPrintClass object for this ASCIIViewerClass object. The
ASCIIViewerClass object uses the Printer property to solicit print ranges and specifications from the end user, then print
from the file subject to the specifications.

Implementation: The AddItem and Init methods initialize the Printer property.

The Printer property is added to the AsciiViewer by calling the AddItem method. The AsciiViewer does not take
ownership of these objects, it just uses them if supplied. It is up to the owner of the objects to destroy them when they are
no longer required.

Since these objects are generated by the templates in local procedure scope, they will be destroyed when the enclosing
generated procedure dies. If these objects are created by hand coding, then they should be destroyed by whoever
creates them.

The exception to this is when the EnablePrint parameter is set on the Init call. In this case the AsciiViewer may create it's
own "internal" printer and viewer. In this case, they are destroyed in the Kill method of the AsciiViewer.

See Also: AddItem, Init

90 ABC Library Reference

Searcher (ASCIISearchClass object)

Searcher &ASCIISearchClass
The Searcher property is a reference to the ASCIISearchClass object for this ASCIIViewerClass object. The
ASCIIViewerClass object uses the Searcher property to solicit search values from the end user, then locate the values
within the browsed file.

Implementation: The AddItem and Init methods initialize the Searcher property.

The Searcher property is added to the AsciiViewer by calling the AddItem method. The AsciiViewer does not take
ownership of these objects, it just uses them if supplied. It is up to the owner of the objects to destroy them when they are
no longer required.

Since these objects are generated by the templates in local procedure scope, they will be destroyed when the enclosing
generated procedure dies. If these objects are created by hand coding, then they should be destroyed by whoever
creates them.
The exception to this is when the EnableSearch parameter is set on the Init call. In this case the AsciiViewer may create
it's own "internal" viewer. In this case, they are destroyed in the Kill method of the AsciiViewer.
See Also: AddItem, Init

TopLine (first line currently displayed)

TopLine UNSIGNED
The TopLine property contains the offset or position of the first line currently displayed by the ASCIIViewerClass object.
The ASCIIViewerClass object uses the TopLine property to manage scrolling and scrollbar thumb positioning.
ASCIIViewerClass 91

AsciiViewerClass Methods
AsciiViewerClass Functional Organization--Expected Use
As an aid to understanding the ASCIIViewerClass, it is useful to organize the its methods into two large categories
according to their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is
typical use of the ASCIIViewerClass methods.

Non-Virtual Methods

The Non-Virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

Init initialize the ASCIIViewerClass object
Kill shut down the ASCIIViewerClass object

Mainstream Use:
AskGotoLine go to user specified line
DisplayPage display new page
PageDown scroll down one page
PageUp scroll up one page
TakeEvent process ACCEPT loop event

Occasional Use:
AddItem add printer or searcher object
GetFilenameI return the filename
GetLastLineNoI return last line number
GetLineI return line of text
GetPercentileI convert file position to percentage
Reset reset the ASCIIViewerClass object
SetPercentileI convert percentage to file position
SetLineV position to specific line
SetLineRelative move N lines

I These methods are inherited from the ASCIIFileClass.

V These methods are also virtual.

92 ABC Library Reference

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

FormatLineI format text

SetLine position to specific line
ValidateLineI implement a filter

I These methods are inherited from the ASCIIFileClass.

ASCIIViewerClass 93

AddItem (program the AsciiViewer object)

AddItem( | printer |)

| searcher |

AddItem Adds specific functionality to the AsciiViewer object.

printer The label of an AsciiPrintClass object.
searcher The label of an AsciiSearchClass object.
The AddItem method adds specific functionality to the AsciiViewer object. This method provides an alternative to the Init
method for adding or changing the print and search capability of the AsciiViewer object.

Implementation: The AddItem method sets the value of the Printer or Searcher property, initializes the printer or searcher,
then enables the corresponding popup menu item.

Example:
MyPrinter CLASS(AsciiPrintClass) !declare custom printer object
NewMethod PROCEDURE
END
MySearcher CLASS(AsciiSearchClass) !declare custom searcher object
NewMethod PROCEDURE
END

CODE
Viewer.Init(AsciiFile,A1:line,Filename,?AsciiBox,GlobalErrors)
Viewer.AddItem(MyPrinter) !add print functionality
Viewer.AddItem(MySearcher) !add search functionality

See Also: Init, Printer, Searcher

94 ABC Library Reference

AskGotoLine (go to user specified line)

AskGotoLine
The AskGotoLine method prompts the end user for a specific line number to display, then positions the file to the line
nearest the one specified.

Implementation: The ASCIIViewerClass invokes the AskGotoLine method from a RIGHT-CLICK popup menu. The
AskGotoLine method calls the SetLine method to position to the requested record.

Example:
MyViewerClass.TakeEvent PROCEDURE(UNSIGNED EventNo)
CODE
CASE EventNo
OF EVENT:AlertKey
IF KEYCODE()=MouseRight
CASE SELF.Popup.Ask()
OF 'Print'
SELF.Printer.Ask
OF 'Goto'
SELF.AskGotoLine
END
END
END

See Also: SetLine

ASCIIViewerClass 95

DisplayPage (display new page)

DisplayPage( [line number] )

DisplayPage Displays a new page from the file.

line number An integer constant, variable, EQUATE or expresssion that contains the offset or position of the line of
text to include in the display. If omitted, line number defaults to the value of the TopLine property.
The DisplayPage method displays a new page from the file. The display includes the line at line number, or the line
specified by the TopLine property, if line number is omitted.

Example:
MyViewerClass.Reset PROCEDURE(*STRING Filename)
CODE
FREE(SELF.DisplayQueue)
DISPLAY(SELF.ListBox)
PARENT.Reset(Filename)
SELF.TopLine=1
SELF.DisplayPage
SELECT(SELF.ListBox,1)

See Also: TopLine

96 ABC Library Reference

Init (initialize the ASCIIViewerClass object)

Init( file, field, [filename], list control, error handler [, features] )

Init Initializes the ASCIIViewerClass object.

file The label of the file to display.
field The fully qualified label of the file field to display.
filename The label of the file's NAME attribute variable. If omitted, the file has a constant NAME attribute. If null (''),
the Init method prompts the end user to select a file.
list control An integer constant, variable, EQUATE, or expression containing the control number of the LIST that
displays the file contents.
error handler The label of the ErrorClass object to handle errors encountered by this ASCIIViewerClass object.
features An integer constant, variable, EQUATE, or expression that tells the ASCIIViewerClass object which
features to implement; for example, printing (EnablePrint), searching (EnableSearch), or both. If omitted,
no additional features are implemented.
The Init method initializes the ASCIIViewerClass object and returns a value indicating whether it successfully accessed
the file and is ready to proceed.

Implementation: The Init method returns one (1) if it accessed the file and is ready to proceed; it returns zero (0) and calls
the Kill method if unable to access the file and cannot proceed. If the Init method returns zero (0), the
ASCIIViewerClass object is not initialized and you should not call its methods.

You can set the features value with the following EQUATEs declared in ASCII.INC. Pass either EQUATE
to implement its feature (search or print), or add the EQUATEs together to implement both features.
EnableSearch BYTE(001b)
EnablePrint BYTE(010b)

Return Data Type: BYTE

ASCIIViewerClass 97

Example:
PROGRAM
MAP
END

INCLUDE('ABASCII.INC') !declare ASCIIViewer Class

ViewWindow WINDOW('View an ASCII File'),AT(3,7,296,136),SYSTEM,GRAY

LIST,AT(5,5,285,110),USE(?AsciiBox),IMM
BUTTON('&Print'),AT(5,120),USE(?Print)
BUTTON('&Search'),AT(45,120),USE(?Search)
BUTTON('&Close'),AT(255,120),USE(?Close)
END

GlobalErrors ErrorClass !declare GlobalErrors object

Viewer AsciiViewerClass,THREAD !declare Viewer object

ViewerActive BYTE(False),THREAD !Viewer initialized flag

Filename STRING(255),THREAD !FileName variable

AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1),THREAD
RECORD RECORD,PRE()
Line STRING(255)
END
END
CODE

GlobalErrors.Init !initialize GlobalErrors object

OPEN(ViewWindow) !open the window
!Initialize Viewer with:
ViewerActive=Viewer.Init( AsciiFile, | ! file label,
A1:line, | ! file field to display
Filename, | ! variable file NAME attribute
?AsciiBox, | ! LIST control number
GlobalErrors, | ! ErrorClass object
EnableSearch+EnablePrint) ! features to implement flag
IF ~ViewerActive THEN RETURN. !if init unsuccessful, don't
! call other Viewer methods
ACCEPT !If init succeeded, proceed
IF EVENT() = EVENT:CloseWindow
IF ViewerActive THEN Viewer.Kill. !If init succeeded, shut down
END
!program code
END

See Also: Kill

98 ABC Library Reference

Kill (shut down the ASCIIViewerClass object)

Kill
The Kill method frees any memory allocated during the life of the object and performs any other required termination
code.

Example:
PROGRAM
MAP
END

INCLUDE('ABASCII.INC') !declare ASCIIViewer Class

ViewWindow WINDOW('View an ASCII File'),AT(3,7,296,136),SYSTEM,GRAY

LIST,AT(5,5,285,110),USE(?AsciiBox),IMM
BUTTON('&Print'),AT(5,120),USE(?Print)
BUTTON('&Search'),AT(45,120),USE(?Search)
BUTTON('&Close'),AT(255,120),USE(?Close)
END

GlobalErrors ErrorClass !declare GlobalErrors object

Viewer AsciiViewerClass,THREAD !declare Viewer object

ViewerActive BYTE(False),THREAD !Viewer initialized flag

Filename STRING(255),THREAD !FileName variable

AsciiFile FILE,DRIVER('ASCII'),NAME(Filename),PRE(A1),THREAD
RECORD RECORD,PRE()
Line STRING(255)
END
END
CODE

GlobalErrors.Init !initialize GlobalErrors object

OPEN(ViewWindow) !open the window
!Initialize Viewer with:
ViewerActive=Viewer.Init( AsciiFile, | ! file label,
A1:line, | ! file field to display
Filename, | ! variable file NAME attribute
?AsciiBox, | ! LIST control number
GlobalErrors, | ! ErrorClass object
EnableSearch+EnablePrint) ! features to implement flag
IF ~ViewerActive THEN RETURN. !if init unsuccessful, don't
! call other Viewer methods
ACCEPT !If init succeeded, proceed
IF EVENT() = EVENT:CloseWindow
IF ViewerActive THEN Viewer.Kill. !If init succeeded, shut down
END
!program code
END
ASCIIViewerClass 99

PageDown (scroll down one page)

PageDown, PROTECTED
The PageDown method scrolls the display down one "page." A page is the number of lines displayed in the
ASCIIViewerClass object's LIST control.

Example:
MyViewerClass.TakeEvent PROCEDURE(UNSIGNED EventNo)
CODE
IF FIELD()=SELF.ListBox
CASE EventNo
OF EVENT:Scrollup
SELF.SetLineRelative(-1)
OF EVENT:ScrollDown
SELF.SetLineRelative(1)
OF EVENT:PageUp
SELF.PageUp
OF EVENT:PageDown
SELF.PageDown
END
END
100 ABC Library Reference

PageUp (scroll up one page)

PageUp, PROTECTED
The PageUp method scrolls the display up one "page." A page is the number of lines displayed in the ASCIIViewerClass
object's LIST control.

Example:
MyViewerClass.TakeEvent PROCEDURE(UNSIGNED EventNo)
CODE
IF FIELD()=SELF.ListBox
CASE EventNo
OF EVENT:Scrollup
SELF.SetLineRelative(-1)
OF EVENT:ScrollDown
SELF.SetLineRelative(1)
OF EVENT:PageUp
SELF.PageUp
OF EVENT:PageDown
SELF.PageDown
END
END
ASCIIViewerClass 101

Reset (reset the ASCIIViewerClass object)

Reset( filename )

Reset Resets the ASCIIViewerClass object.

filename The label of the ASCIIFile property's NAME attribute variable.
The Reset method resets the ASCIIViewerClass object and returns a value indicating whether the end user selected a file
or did not select a file. A return value of one (1) indicates a file was selected and filename contains its pathname; a retun
value of zero (0) indicates no file was selected and filename is empty.

Implementation: The Reset method frees the display QUEUE and calls the ASCIIFileClass.Reset method to get a new
filename from the end user. Reset refills the display QUEUE and redisplays the list box if a new file was
selected.

Return Data Type: BYTE

Example:
AsciiFileClass.Init FUNCTION |
(FILE AsciiFile,*STRING FileLine,*STRING FName,ErrorClass ErrorHandler)

CODE
SELF.AsciiFile&=AsciiFile
SELF.Line&=FileLine
SELF.ErrorMgr&=ErrorHandler
SELF.IndexQueue&=NEW(IndexQueue)
IF ~SELF.Reset(FName)
SELF.Kill
RETURN False
END
RETURN True

See Also: ASCIIFile, ASCIIFileClass.Reset

102 ABC Library Reference

SetLine (position to specific line)

SetLine( line number ), PROTECTED, VIRTUAL

SetLine Positions the ASCIIViewerClass object to a specific line.

line number An integer constant, variable, EQUATE or expresssion that contains the offset or position of the line of
text to position to.
The SetLine method positions the ASCIIViewerClass object to a specific line within the browsed file.

Implementation: The AskGotoLine method, the ASCIIFileClass.SetPercentile method, and the ASCIISearchClass.Ask
method all use the SetLine method to position to the required text line.

Example:
MyViewerClass.AskGotoLine PROCEDURE
LineNo LONG,STATIC
OKGo BOOL(False)
GotoDialog WINDOW('Goto'),AT(,,96,38),GRAY,DOUBLE
SPIN(@n_5),AT(36,4,56,13),USE(LineNo),RANGE(1,99999)
PROMPT('&Line No:'),AT(4,9,32,10),USE(?Prompt1)
BUTTON('&Go'),AT(8,22,40,14),USE(?GoButton)
BUTTON('&Cancel'),AT(52,22,40,14),USE(?CancelButton)
END
CODE
OPEN(GotoDialog)
ACCEPT
CASE EVENT()
OF EVENT:Accepted
CASE ACCEPTED()
OF ?GoButton
OKGo=True
POST(EVENT:CloseWindow)
OF ?CancelButton
POST(EVENT:CloseWindow)
END
END
END
CLOSE(GotoDialog)
IF OKGo THEN SELF.SetLine(LineNo).

See Also: AskGoToLine, ASCIIFileClass.SetPercentile, ASCIISearchClass.Ask

ASCIIViewerClass 103

SetLineRelative (move n lines)

SetLineRelative( lines ), PROTECTED

SetLineRelative Positions the ASCIIViewerClass object to a relative line.

lines An integer constant, variable, EQUATE or expresssion containing the number of lines to move from the
current position. A positive value moves downward; a negative value moves upward.
The SetLineRelative method repositions the ASCIIViewerClass object lines lines from the current position.

Example:
MyViewerClass.TakeScrollOne PROCEDURE(UNSIGNED EventNo)
CODE
IF FIELD()=SELF.ListBox
CASE EventNo
OF EVENT:Scrollup
SELF.SetLineRelative(-1)
OF EVENT:ScrollDown
SELF.SetLineRelative(1)
END
END
104 ABC Library Reference

SetTranslator (set run-time translator:ASCIIViewerClass)

SetTranslator( translator )

SetTranslator Sets the TranslatorClass object for the AsciiViewerClass object.

translator The label of the TranslatorClass object for this AsciiViewerClass object.
The SetTranslator method sets the TranslatorClass object for the AsciiViewerClass object. By specifying a
TranslatorClass object for the AsciiViewerClass object, you automatically translate any window or popup menu text
displayed by the viewer.

Implementation: The SetTranslator method sets the TranslatorClass object for the PopupClass, AsciiPrintClass, and
AsciiSearchClass objects.

Example:
Viewer AsciiViewerClass !declare Viewer object
Translator TranslatorClass !declare Translator object
CODE
Translator.Init !initialize Translator object
ViewerActive=Viewer.Init( AsciiFile, | ! file label,
A1:line, | ! file field to display
Filename, | ! variable file NAME attribute
?AsciiBox, | ! LIST control number
GlobalErrors, | ! ErrorClass object
EnableSearch+EnablePrint) ! features to implement flag
IF ~ViewerActive THEN RETURN. !if init unsuccessful, don't
! call other Viewer methods
Viewer.SetTranslator(Translator) !enable text translation
!program code
ASCIIViewerClass 105

TakeEvent (process ACCEPT loop event:ASCIIViewerClass)

TakeEvent( event ), PROC

TakeEvent Processes an ACCEPT loop event.

event An integer constant, variable, EQUATE or expresssion containing the event number.
The TakeEvent method processes an ACCEPT loop event on behalf of the ASCIIViewerClass object and returns a value
indicating whether a CYCLE to the top of the ACCEPT loop is required to properly refresh the display.

Implementation: The TakeEvent method handles resizing, RIGHT-CLICKS, LEFT-CLICKS, and scrolling events.

A return value of zero (0) indicates no CYCLE is needed; any other return value requires a CYCLE.

Return Data Type: BYTE

Example:
ACCEPT
CASE FIELD()
OF ?AsciiBox
IF ViewerActive
IF Viewer.TakeEvent(EVENT())
CYCLE
END
END
END
END
106 ABC Library Reference

BreakManagerClass
BreakManagerClass - Overview
The BreakManagerClass handles embedded break events for a target report. Each break can perform totaling
based on a data element‘s contents changing. Breaks can be nested, allowing the contents of one break result to
determine another break result. Conditional headers and footers can be printed by any break. Each break is
totally customizable through available embed points defined in virtual methods.

BreakManagerClass - Concepts
Each embedded break generated by BreakManager is controlled by a template interface in the Report Propeties
dialog and through a set of embed points generated. Embedded breaks are designed to give the developer more
control ―behind the scenes‖. The BreakManager is not related to the traditional Break logic supported by the
structure of the report.

Each break inherits a set of methods and properties defined by an internal LevelManager. An internal break
queue stores a unique break and level id which triggers the appropriate break logic.

BreakManagerClass - Relationship to Other Application Builder Classes

ReportManagerClass

The BreakManager class is derived from the ReportManager class.

LevelManagerClass

Each ReportManagerClass utilizing embedded breaks declares a LevelManagerClass to manage the nesting
and execution of the embedded break logic.

BreakManagerClass - ABC Template Implementation

The Report template declares a BreakManager when a break is added through the Break tab located in the
Report Properties dialog.

BreakManagerClass - Source Files

The BreakManagerClass source code is installed by default to the Clarion \LIBSRC folder. The specific
BreakManagerClass source code and their respective components are contained in:

ABBreak.INC EditClass declarations

ABBreak.CLW EditClass method definitions
BreakManagerClass 107

BreakManagerClass - Conceptual Example

The following example shows a sequence of statements to declare, and instantiate a BreakManager object.
MEMBER('people.clw') ! This is a MEMBER module

INCLUDE('ABBREAK.INC'),ONCE
INCLUDE('ABBROWSE.INC'),ONCE
INCLUDE('ABREPORT.INC'),ONCE

MAP
INCLUDE('PEOPL005.INC'),ONCE !procedure decl
END

PrintPEO:KeyLastName PROCEDURE ! Generated from procedure template - Report

Progress:Thermometer BYTE !
FilesOpened BYTE !
TestCount LONG !
Process:View VIEW(people)
PROJECT(PEO:FirstName)
PROJECT(PEO:Gender)
PROJECT(PEO:Id)
PROJECT(PEO:LastName)
END
LocMyFocusControlExT SHORT(0) !Used by the ENTER Instead of Tab template
LocEnableEnterByTab BYTE(1) !Used by the ENTER Instead of Tab template
ProgressWindow WINDOW('Progress...'),AT(,,142,59),CENTER,TIMER(1),GRAY,DOUBLE
PROGRESS,USE(Progress:Thermometer),AT(15,15,111,12),RANGE(0,100)
STRING(''),AT(0,3,141,10),USE(?Progress:UserString),CENTER
STRING(''),AT(0,30,141,10),USE(?Progress:PctText),CENTER
BUTTON('Cancel'),AT(45,42,50,15),USE(?Progress:Cancel)
END
report REPORT,AT(1000,1540,6000,7458),PRE(RPT),FONT('Arial',10,,),THOUS
HEADER,AT(1000,1000,6000,542)
STRING('People by Last Name‘),AT(0,20,6000,220),CENTER,FONT(,,,FONT:bold)
BOX,AT(0,260,6000,280),COLOR(COLOR:Black),FILL(COLOR:Silver)
LINE,AT(1500,260,0,280),COLOR(COLOR:Black)
LINE,AT(3000,260,0,280),COLOR(COLOR:Black)
LINE,AT(4500,260,0,280),COLOR(COLOR:Black)
STRING('Id'),AT(50,310,1400,170),TRN
STRING('First Name'),AT(1550,310,1400,170),TRN
STRING('Last Name'),AT(3050,310,1400,170),TRN
STRING('Gender'),AT(4550,310,1400,170),TRN
END
detail DETAIL,AT(,,6000,281),USE(?unnamed)
LINE,AT(1500,0,0,280),COLOR(COLOR:Black)
LINE,AT(3000,0,0,280),COLOR(COLOR:Black)
LINE,AT(4500,0,0,280),COLOR(COLOR:Black)
STRING(@S10),AT(50,50,1400,170),USE(PEO:Id),RIGHT(1)
STRING(@S30),AT(1550,50,1400,170),USE(PEO:FirstName)
STRING(@S30),AT(3050,50,1400,170),USE(PEO:LastName)
STRING(@S1),AT(4552,52,240,167),USE(PEO:Gender)
STRING(@n_4),AT(5208,42),USE(TestCount),RIGHT(1)
LINE,AT(50,280,5900,0),COLOR(COLOR:Black)
END
FOOTER,AT(1000,9000,6000,219)
STRING(@pPage <<<#p),AT(5250,30,700,135),PAGENO,USE(?PageCount)
END
END
108 ABC Library Reference

ThisWindow CLASS(ReportManager)
Init PROCEDURE(),BYTE,PROC,DERIVED! Method added to host embed code
Kill PROCEDURE(),BYTE,PROC,DERIVED! Method added to host embed code
OpenReport PROCEDURE(),BYTE,PROC,DERIVED! Method added to host embed code
SetAlerts PROCEDURE(),DERIVED ! Method added to host embed code
TakeWindowEvent PROCEDURE(),BYTE,PROC,DERIVED! Method added to host embed code
END

ThisReport CLASS(ProcessClass) ! Process Manager

TakeRecord PROCEDURE(),BYTE,PROC,DERIVED! Method added to host embed code
END

ProgressMgr StepStringClass ! Progress Manager

Previewer PrintPreviewClass ! Print Previewer
BreakMgr BreakManagerClass ! Break Manager

CODE
GlobalResponse = ThisWindow.Run() !Opens the window and starts an Accept Loop

!---------------------------------------------------------------------------
DefineListboxStyle ROUTINE
!|
!| This routine create all the styles to be shared in this window
!| It's called after the window open
!|
!---------------------------------------------------------------------------

ThisWindow.Init PROCEDURE

ReturnValue BYTE,AUTO

CODE
GlobalErrors.SetProcedureName('PrintPEO:KeyLastName')
SELF.Request = GlobalRequest ! Store the incoming request
ReturnValue = PARENT.Init()
IF ReturnValue THEN RETURN ReturnValue.
SELF.FirstField = ?Progress:Thermometer
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
CLEAR(GlobalRequest)
CLEAR(GlobalResponse)
SELF.AddItem(Translator)
Relate:people.Open
! File people used by this procedure, so make sure it's RelationManager is open
SELF.FilesOpened = True
BreakMgr.Init() !Initialize the BreakManager object
BreakMgr.AddBreak() !A break exists
BreakMgr.AddLevel() !People Count is the name of the brteak
BreakMgr.AddResetField(PEO:Gender)!resets when gender changes
BreakMgr.AddTotal(TestCount,1) !Performs a count when break occurs
SELF.AddItem(BreakMgr)

OPEN(ProgressWindow) ! Open window

BreakManagerClass 109

BreakManagerClass - Properties
The BreakManagerClass contains no public properties.

BreakManagerClass - Methods
The BreakManagerClass contains the following methods:

AddBreak (add a Break)

AddBreak( )

AddBreak Identifies to the corresponding report that an embedded break object is active.
The AddBreak method identifies that an embedded break object is active for a corresponding report. An internal BreakID
number is assigned for each break object created. This BreakID is incremented when a subsequent AddBreak method is
executed.

Implementation: The AddBreak method is called for each break object that is active for a report. Each object is instantiated
from the LevelManagerClass. An AddLevel method follows each AddBreak method.

Example:
BreakMgr.AddBreak() !First Break
BreakMgr.AddLevel() !Auto assign level 1
BreakMgr.AddResetField(PEO:Gender)
BreakMgr.AddTotal(TestCount,1)
BreakMgr.AddBreak() !Second Break
BreakMgr.AddLevel() !Break2

See Also: Add Level

110 ABC Library Reference

AddLevel (add a Level to the BreakId Break)

AddLevel( | breakid | )

AddLevel Assign a level number to the active break.

breakid An integer that identifies which internal break to assign this level to.
The AddLevel method identifies the order of break execution that is assigned to a corresponding report. This is used
when nested breaks are assigned, and controls which break is executed first.

Implementation: The AddLevel method is called after each break is added, directly following the AddBreak method.

Example:
BreakMgr.AddBreak() !First Break
BreakMgr.AddLevel() !Auto assign level 1
BreakMgr.AddResetField(PEO:Gender)
BreakMgr.AddTotal(TestCount,1)
BreakMgr.AddBreak() !Second Break
BreakMgr.AddLevel() !Break2

See Also: Add Break

BreakManagerClass 111

AddResetField (add a reset field to the last Level added)

AddResetField( fieldlabel )

AddResetField Identify a field to reset on the active break.

fieldlabel The label of a field that the break will reset

The AddResetField method identifies the field whose contents will be reset when a break is executed.

Implementation: The AddResetField method is called after each break and level is added, directly following the AddLevel
method. In the template interface, it is only active when the Reset on Break option is set to TRUE.

Example:
BreakMgr.AddBreak() !First Break
BreakMgr.AddLevel() !Auto assign level 1
BreakMgr.AddResetField(PEO:Gender) !Reset on break is active
BreakMgr.AddTotal(TestCount,1)
BreakMgr.AddBreak() !Second Break
BreakMgr.AddLevel() !Break2

See Also: Add Break

112 ABC Library Reference

AddTotal (add a total field to the last Level added)

AddTotal (target, source, type, reset )
(target, source, type, reset, condition)
(target, reset )
(target, reset, condition )

AddTotal Identify the break total type and optional source/target fields and condition.

target The label of a field that the total result will be stored into.

source The label of a field that the total result will be calculated from.

type A byte that identifies the total type defined for the break.
A count type = 1, average type = 2, sum type = 3.

reset A byte that specifies whether or not the target variable is reset on each break detected. A value of
1 specifies a reset, zero will not reset the target value.

condition A valid expression that will force a reset when evaluated to TRUE.

The AddTotal method is an overloaded method that caluculates three types of conditional or unconditional totaling.

Implementation: The AddTotal method is called after each break and level is added, directly following the AddResetField
method. In the template interface, it is only active when totaling is added to the break.
Example:

BreakMgr.Init()
BreakMgr.AddBreak()
BreakMgr.AddLevel() !Count Break
BreakMgr.AddResetField(PEO:Gender)
BreakMgr.AddTotal(CountValue,1)
BreakMgr.AddBreak()
BreakMgr.AddLevel() !SumBreak
BreakMgr.AddResetField(PEO:Gender)
BreakMgr.AddTotal(SumValue,SourceToTotal,eBreakTotalSum,1)
BreakMgr.AddBreak()
BreakMgr.AddLevel() !ConditionalAverage
BreakMgr.AddResetField(PEO:Gender)
BreakMgr.AddTotal(AverageValue,SourceToAverage,eBreakTotalAve,0,'PEO:Gender = ''M''')
BreakManagerClass 113

Construct (automatic initialization of the BreakManager object)

Construct
The Construct method performs the necessary code to initialize the BreakManager object.
Implementation: The Construct method is automatically called when the object is instantiated. The internal break queue is
created, and the Break Id is reset to zero.

Destruct (automatic destroy of the Breakmanager object)

Destruct
The Destruct method performs the necessary code to destroy the BreakManager object.
Implementation: The Destruct method is automatically called when the object is instantiated. Each break object
instantiated in the Init method is cleared from memory.

Init (initialize the BreakManager object)

Init( )

Init Initialize the BreakManager object.

The Init method initializes the BreakManager by clearing any prior entries in the internal Break Queue, which holds any
breaks defined. Normally, the Destruct method also performs a similar function, but the Init method ensures that the
Break Queue is clean before calling the report.
Implementation: The Init method is called prior to the first AddBreak method.

Example:
CODE
GlobalErrors.SetProcedureName('PrintPEO:KeyLastName')
SELF.Request = GlobalRequest ! Store the incoming request
ReturnValue = PARENT.Init()
IF ReturnValue THEN RETURN ReturnValue.
SELF.FirstField = ?Progress:Thermometer
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
CLEAR(GlobalRequest) ! Clear GlobalRequest after storing locally
CLEAR(GlobalResponse)
SELF.AddItem(Translator)
Relate:people.Open
SELF.FilesOpened = True
BreakMgr.Init()
BreakMgr.AddBreak()
114 ABC Library Reference

TakeEnd (Break closed)

TakeEnd ( )

TakeEnd A virtual method called prior to closing an active break.

The TakeEnd method is a virtual method that performs any necessary code action prior to the close of the active break.
Implementation: The TakeEnd method is used by the ABC templates to print a custom footer detail for the active break.
There are embed points available if you need to prime any variables prior to its printing.

Example:
BreakMgr.TakeEnd PROCEDURE(SHORT BreakId,SHORT LevelId)

CODE
CASE BreakId
END
OF 2
CASE LevelId
OF 1 !SumBreak
PRINT(RPT:sumdetail)
END
OF 3
CASE LevelId
OF 1 !ConditionalAverage
PRINT(RPT:AverageDetail)
END
END
PARENT.TakeEnd(BreakId,LevelId)
BreakManagerClass 115

TakeStart (Break opened)

TakeStart ( )

TakeStart A virtual method called prior to the start of an active break.

The TakeStart method is a virtual method that performs any necessary code action prior to the start of the active break.
Implementation: The TakeStart method is used by the ABC templates to print a custom header detail for the active break.
There are embed points available if you need to prime any variables prior to its printing.

Example:
BreakMgr.TakeStart PROCEDURE(SHORT BreakId,SHORT LevelId)

CODE
CASE BreakId
OF 1
CASE LevelId
OF 1 !Count Break
PRINT(RPT:CountDetail)
END
OF 3
CASE LevelId
OF 1 !ConditionalAverage
PRINT(RPT:AverageDetail)
END
END
PARENT.TakeStart(BreakId,LevelId)
116 ABC Library Reference

UpdateTotal (Calculate Break totaling)

UpdateTotal( )

UpdateTotal A virtual method called prior to the start and ending of any break totaling.

The UpdateTotal method is a virtual method that performs any necessary code action prior to the start and finish of any
totaling defined in an active break.

Implementation:

The UpdateTotal method is used by the ABC templates to allow any modifications or extra cleanup of any totaling
performed for an active break. The virtual method embeds provide a ―Before Totaling‖ and ―After Totaling‖ embed point for
every total defined in each break.
BreakManagerClass 117
118 ABC Library Reference

BrowseEIPManagerClass
BrowseEIPManagerClass--Overview
The BrowseEIPManagerClass is an EIPManager that displays an Edit-in-place dialog, and handles events for that dialog.
Each BrowseClass utilizing Edit-in-place declares a BrowseEIPManagerClass to manage the events and processes that
are used by each Edit-in-place field in the browse.

See Also:

BrowseEIPManagerClass Concepts

BrowseEIPManagerClass--Relationship to Other Application Builder Classes

BrowseEIPManagerClass--ABC Template Implementation

BrowseEIPManagerClass Source Files

BrowseEIPManagerClass--Conceptual Example
BrowseClass 119

BrowseEIPManagerClass Concepts
Each Edit-in-place control is a window created on top of the browse from which it is called. The EIPManager dynamically
creates an Edit-in-place object and control upon request (Insert, Change, or Delete) by the end user. When the end user
accepts the edited record the EIPManager destroys the edit-in-place object and control.

See Also:

BrowseEIPManagerClass--Relationship to Other Application Builder Classes

BrowseEIPManagerClass--ABC Template Implementation

BrowseEIPManagerClass Source Files

BrowseEIPManagerClass--Conceptual Example
120 ABC Library Reference

BrowseEIPManagerClass--Relationship to Other Application Builder Classes

EIPManagerClass

The BrowseEIPManager class is derived from the EIPManager class.

BrowseClass

Each BrowseClass utilizing edit-in-place declares a BrowseEIPManagerClass to manage the events and processes that
are used by each edit-in-place field in the browse.

The BrowseClass.AskRecord method is the calling method for edit-in-place functionality when edit-in-place is enabled.

EditClass

The BrowseEIPManager provides the basic or "under the hood" interface between the Edit classes and the Browse class.
All fields in the browse utilizing customized edit-in-place controls are kept track of by the BrowseEIPManager via the
BrowseEditQueue.

BrowseEIPManagerClass--ABC Template Implementation

The Browse template declares a BrowseEIPManager when the BrowseUpdateButtons control template enables default
edit-in-place support for the BrowseBox.

See Control Templates--BrowseBox, and BrowseUpdateButtons for more information.

BrowseEIPManagerClass Source Files

The BrowseEIPManagerClass source code is installed by default to the Clarion \LIBSRC folder. The specific
BrowseEIPManagerClass source code and their respective components are contained in:

ABBrowse.INC EditClass declarations

ABBrowse.CLW EditClass method definitions
ABBrowse.TRN EditClass translation strings
BrowseClass 121

BrowseEIPManagerClass--Conceptual Example
The following example shows a sequence of statements to declare, and instantiate a BrowseEIPManager object. The
example page-loads a LIST of actions and associated priorities, then edits the list items via edit-in-place. Note that the
BrowseClass object declares a BrowseEIPManager which is a refrence to the EIPManager as declared in ABBrowse.INC.
PROGRAM

_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)

INCLUDE('ABBROWSE.INC'),ONCE
INCLUDE('ABEIP.INC'),ONCE
INCLUDE('ABWINDOW.INC'),ONCE
MAP
END

Actions FILE,DRIVER('TOPSPEED'),PRE(ACT),CREATE,BINDABLE,THREAD
KeyAction KEY(ACT:Action),NOCASE,OPT
Record RECORD,PRE()
Action STRING(20)
Priority DECIMAL(2)
Completed DECIMAL(1)
END
END

Access:Actions &FileManager
Relate:Actions &RelationManager
GlobalErrors ErrorClass
GlobalRequest BYTE(0),THREAD
ActionsView VIEW(Actions)
END

Queue:Browse QUEUE
ACT:Action LIKE(ACT:Action)
ACT:Priority LIKE(ACT:Priority)
ViewPosition STRING(1024)
END
BrowseWindow WINDOW('Browse Records'),AT(0,0,247,140),SYSTEM,GRAY
LIST,AT(5,5,235,100),USE(?List),IMM,HVSCROLL,MSG('Browsing Records'),|
FORMAT('80L~Action~@S20@8R~Priority~L@N2@'),FROM(Queue:Browse)
BUTTON('&Insert'),AT(5,110,40,12),USE(?Insert),KEY(InsertKey)
BUTTON('&Change'),AT(50,110,40,12),USE(?Change),KEY(CtrlEnter),DEFAULT
BUTTON('&Delete'),AT(95,110,40,12),USE(?Delete),KEY(DeleteKey)
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,DERIVED
Kill PROCEDURE(),BYTE,PROC,DERIVED
END

BRW1 CLASS(BrowseClass)
Q &Queue:Browse
Init PROCEDURE|
(SIGNED ListBox,*STRING Posit,VIEW V,QUEUE Q,RelationManager RM,WindowManager WM)
END

BRW1::EIPManager BrowseEIPManager
122 ABC Library Reference
BrowseClass 123

CODE
GlobalErrors.Init
Relate:Actions.Init
GlobalResponse = ThisWindow.Run()
Relate:Actions.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE

ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue =PARENT.Init()
IF ReturnValue THEN RETURN ReturnValue.
SELF.FirstField = ?List
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
SELF.AddItem(Toolbar)
CLEAR(GlobalRequest)
CLEAR(GlobalResponse)
Relate:Actions.Open
FilesOpened = True
BRW1.Init|
(?List,Queue:Browse.ViewPosition,BRW1::View:Browse,Queue:Browse,Relate:Actions,SELF)
OPEN(BrowseWindow)
SELF.Opened=True
BRW1.Q &= Queue:Browse
BRW1.AddSortOrder(,ACT:KeyAction)
BRW1.AddLocator(BRW1::Sort0:Locator)
BRW1::Sort0:Locator.Init(,ACT:Action,1,BRW1)
BRW1.AddField(ACT:Action,BRW1.Q.ACT:Action)
BRW1.AddField(ACT:Priority,BRW1.Q.ACT:Priority)
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
BRW1.AddToolbarTarget(Toolbar)
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE

ReturnValue BYTE,AUTO
CODE
ReturnValue =PARENT.Kill()
IF ReturnValue THEN RETURN ReturnValue.
IF FilesOpened
Relate:Actions.Close
END
RETURN ReturnValue

BRW1.Init PROCEDURE(SIGNED ListBox,*STRING Posit,VIEW V,QUEUE Q,RelationManager|

RM,WindowManager WM)

CODE
PARENT.Init(ListBox,Posit,V,Q,RM,WM)
124 ABC Library Reference

SELF.EIP &= BRW1::EIPManager

BrowseEIPManagerClass Properties
BrowseEIPManagerClass Properties
The BrowseEIPManagerClass contains the following property and inherits all the properties of the EIPManagerClass.

BC (browse class)

BC &BrowseClass, PROTECTED
The BC property is a reference to the calling BrowseClass object.
BrowseClass 125

BrowseEIPManagerClass Methods
BrowseEIPManagerClass--Functional Organization--Expected Use
As an aid to understanding the EIPManagerClass, it is useful to organize its methods into two large categories according
to their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EIPManagerClass methods.

Non-Virtual Methods

The Non-Virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

Init D initialize the BrowseEditClass object
Kill D shut down the BrowseEditClass object

Mainstream Use:
TakeNewSelectionD handle Event:NewSelections

Occasional Use:
ClearColumnD reset column property values TakeCompletedD
process completion of edit

D These methods are also Derived

Derived Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are derived, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

Init D initialize the BrowseEditClass object

Kill D shut down the BrowseEditClass object TakeNewSelectionD
handle Event:NewSelections
ClearColumnD reset column property values TakeCompletedD
process completion of edit
126 ABC Library Reference

ClearColumn (reset column property values)

ClearColumn, DERIVED
The ClearColumn method checks for a value in the LastColumn property and conditionally sets the column values to 0.

The TakeCompleted method calls the ClearColumn method.

Example:
BrowseEIPManager.TakeCompleted PROCEDURE(BYTE Force)
SaveAns UNSIGNED,AUTO
Id USHORT,AUTO
CODE
SELF.Again = 0
SELF.ClearColumn
SaveAns = CHOOSE(Force = 0,Button:Yes,Force)
IF SELF.Fields.Equal()
SaveAns = Button:No
ELSE
IF ~Force
SaveAns = SELF.Errors.Message(Msg:SaveRecord,|
Button:Yes+Button:No+Button:Cancel,Button:Yes)
END
END
! code to handle user input from SaveRecord message

See Also: Column

BrowseClass 127

Init (initialize the BrowseEIPManagerClass object)

Init, DERIVED, PROC

The Init method initializes the BrowseEIPManagerClass object.

Implementation: The Init method primes variables and calls the InitControls method which then initializes the appropriate
edit-in-place controls. It is indirectly called by the BrowseClass.AskRecord method via a call to an
inherited Run method.

Return Data Type: BYTE

Example:
WindowManager.Run PROCEDURE
CODE
IF ~SELF.Init()
SELF.Ask
END
SELF.Kill
RETURN CHOOSE(SELF.Response=0,RequestCancelled,SELF.Response)

See Also: BrowseClass.ResetFromAsk

128 ABC Library Reference

Kill (shut down the BrowseEIPManagerClass object)

Kill, DERIVED, PROC

The Kill method frees any memory allocated during the life of the object and performs any other required termination
code. The Kill method must leave the object in a state in which it can be initialized.

Implementation: The Kill method calls the BrowseClass.ResetFromAsk method.

Return Data Type: BYTE

Example:
WindowManager.Run PROCEDURE
CODE
IF ~SELF.Init()
SELF.Ask
END
SELF.Kill
RETURN CHOOSE(SELF.Response=0,RequestCancelled,SELF.Response)

See Also: BrowseClass.ResetFromAsk

BrowseClass 129

TakeCompleted (process completion of edit)

TakeCompleted( force ), DERIVED

TakeCompleted Determines the edit-in-place dialog's action after either a loss of focus or an end user action.
force An integer constant, variable, EQUATE, or expression that indicates the record being edited should be
saved without prompting the end user.
The TakeCompleted method either saves the record being edited and end the edit-in-place process, or prompts the end
user to save the record and end the edit-in-place process, cancel the changes and end the edit-in-place process, or
remain editing.

Implementation: The EIPManager.TakeFocusLoss and EIPManager.TakeAction methods call the TakeCompleted

method.

Note: TakeCompleted does not override the WindowManager.TakeCompleted method.

Example:
EIPManager.TakeFocusLoss PROCEDURE
CODE
CASE CHOOSE(SELF.FocusLoss&=NULL,EIPAction:Default,BAND(SELF.FocusLoss,EIPAction:Save))
OF EIPAction:Always OROF EIPAction:Default
SELF.TakeCompleted(Button:Yes)
OF EIPAction:Never
SELF.TakeCompleted(Button:No)
ELSE
SELF.TakeCompleted(0)
END

See Also: EIPManager.TakeFocusLoss, EIPManager.TakeAction

130 ABC Library Reference

TakeNewSelection (reset edit-in-place column)

TakeNewSelection, DERIVED, PROC

The TakeNewSelection method resets the edit-in-place column selected by the end user.

Implementation: TakeNewSelection calls ResetColumn, and returns a Level:Benign.

Return Data Type: BYTE

Example:
WindowManager.TakeEvent PROCEDURE
RVal BYTE(Level:Benign)
I USHORT,AUTO
CODE
IF ~FIELD()
RVal = SELF.TakeWindowEvent()
IF RVal THEN RETURN RVal.
END
CASE EVENT()
OF EVENT:Accepted
RVal = SELF.TakeAccepted()
OF EVENT:Rejected
RVal = SELF.TakeRejected()
OF EVENT:Selected
RVal = SELF.TakeSelected()
OF EVENT:NewSelection
RVal = SELF.TakeNewSelection()
OF EVENT:AlertKey
IF SELF.HistoryKey AND KEYCODE() = SELF.HistoryKey
SELF.RestoreField(FOCUS())
END
END
IF RVal THEN RETURN RVal.

See Also: ResetColumn

BrowseClass 131

BrowseClass
BrowseClass Overview
The BrowseClass is a ViewManager with a user interface for navigating through the result set of the underlying VIEW.

BrowseClass Concepts

The BrowseClass uses several related classes to provide standard browse functionality--that is, file-loaded or page-
loaded lists with automatic scrolling, searching, ranging, filtering, resets, conditional colors, conditional icons, etc. These
classes can be used to build other components and functionality as well.

Added to this standard functionality, is Edit-In-Place--that is, you can update the VIEW's primary file by typing directly into
the browse list. No separate update procedure is required, and the updates are appropriately autoincremented,
referentially constrained, and field validated.

Following are the classes that provide this browse functionality. The classes and their respective roles are:

BrowseClass Browse list "supervisor" class

StepClass Scrollbar/Progress Bar base class
LongStepClass Numeric Runtime distribution
RealStepClass Numeric Runtime distribution
StringStepClass Alpha/Lastname distribution
CustomStepClass Custom distribution
LocatorClass Locator base class
StepLocatorClass Step Locator
EntryLocatorClass Entry Locator
IncrementalLocatorClass Incremental Locator
FilterLocatorClass Filter Locator
EditClass Edit-In-Place

The BrowseClass is fully documented in the remainder of this chapter. Each related class is documented in its own
chapter.

BrowseClass Relationship to Other Application Builder Classes

The BrowseClass is closely integrated with several other ABC Library objects--in particular the WindowManager and
ToolbarClass objects. These objects register their presence with each other, set each other's properties, and call each
other's methods as needed to accomplish their respective tasks.

The BrowseClass is derived from the ViewManager, plus it relies on many of the other Application Builder Classes
(RelationManager, FieldPairsClass, ToolbarClass, PopupClass, etc.) to accomplish its tasks. Therefore, if your program
instantiates the BrowseClass, it must also instantiate these other classes. Much of this is automatic when you INCLUDE
the BrowseClass header (ABBROWSE.INC) in your program's data section. See the Conceptual Example.

BrowseClass ABC Template Implementation

The ABC Templates automatically include all the classes and generate all the code necessary to support the functionality
specified in your application's Browse Procedure and BrowseBox Control templates.

The templates derive a class from the BrowseClass for each BrowseBox in the application. By default, the derived class is
called BRW# where # is the BrowseBox control template instance number. This derived class object supports all the
functionality specified in the BrowseBox template.
132 ABC Library Reference

The derived BrowseClass is local to the procedure, is specific to a single BrowseBox and relies on the global file-specific
RelationManager and FileManager objects for the browsed files. The templates provide the derived class so you can
customize the BrowseBox behavior on a per-instance basis. See Control Templates--BrowseBox for more information.

BrowseClass Source Files

The BrowseClass source code is installed by default to the Clarion \LIBSRC folder. The specific BrowseClass source
code and their respective components are contained in:

ABBROWSE.INC BrowseClass declarations

ABBROWSE.CLW BrowseClass method definitions
ABBROWSE.TRN BrowseClass translation strings

BrowseClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a
BrowseClass object and related objects. The example initializes and page-loads a LIST, then handles a number of
associated events, including searching, scrolling, and updating. When they are initialized properly, the BrowseClass and
WindowManager objects do most of the work (default event handling) internally.
PROGRAM
INCLUDE('ABWINDOW.INC') !declare WindowManager class
INCLUDE('ABBROWSE.INC') !declare BrowseClass
MAP
END

State FILE,DRIVER('TOPSPEED'),PRE(ST),THREAD
StateCodeKey KEY(ST:STATECODE),NOCASE,OPT
Record RECORD,PRE()
STATECODE STRING(2)
STATENAME STRING(20)
END
END

StView VIEW(State) !declare VIEW for BrowseSt

END

StateQ QUEUE !declare Q for LIST

ST:STATECODE LIKE(ST:STATECODE)
ST:STATENAME LIKE(ST:STATENAME)
ViewPosition STRING(512)
END

GlobalErrors ErrorClass !declare GlobalErrors object

Access:State CLASS(FileManager) !declare Access:State object
Init PROCEDURE
END
Relate:State CLASS(RelationManager) !declare Relate:State object
Init PROCEDURE
END
VCRRequest LONG(0),THREAD

ThisWindow CLASS(WindowManager) !declare ThisWindow object

Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END
BrowseSt CLASS(BrowseClass) !declare BrowseSt object
Q &StateQ
END

StLocator StepLocatorClass !declare StLocator object

BrowseClass 133

StStep StepStringClass !declare StStep object

134 ABC Library Reference

StWindow WINDOW('Browse States'),AT(,,123,152),IMM,SYSTEM,GRAY

LIST,AT(8,5,108,124),USE(?StList),IMM,HVSCROLL,FROM(StateQ),|
FORMAT('27L(2)|M~CODE~@s2@80L(2)|M~STATENAME~@s20@')
BUTTON('&Insert'),AT(8,133),USE(?Insert)
BUTTON('&Change'),AT(43,133),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(83,133),USE(?Delete)
END
CODE
ThisWindow.Run() !run the window procedure

ThisWindow.Init PROCEDURE() !initialize things

ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Init() !call base class init
IF ReturnValue THEN RETURN ReturnValue.
GlobalErrors.Init !initialize GlobalErrors object
Relate:State.Init !initialize Relate:State object
SELF.FirstField = ?StList !set FirstField for ThisWindow
SELF.VCRRequest &= VCRRequest !VCRRequest not used
SELF.Errors &= GlobalErrors !set error handler for ThisWindow
Relate:State.Open !open State and related files
!Init BrowseSt object by naming its LIST,VIEW,Q,RelationManager & WindowManager
BrowseSt.Init(?StList,StateQ.ViewPosition,StView,StateQ,Relate:State,SELF)
OPEN(StWindow)
SELF.Opened=True
BrowseSt.Q &= StateQ !reference the browse QUEUE
!initialize the StStep object
StStep.Init(+ScrollSort:AllowAlpha,ScrollBy:Runtime)
!set the browse sort order
BrowseSt.AddSortOrder(StStep,ST:StateCodeKey)
BrowseSt.AddLocator(StLocator) !plug in the browse locator
StLocator.Init(,ST:STATECODE,1,BrowseSt) !initialize the locator
BrowseSt.AddField(ST:STATECODE,BrowseSt.Q.ST:STATECODE) !set a column to browse
BrowseSt.AddField(ST:STATENAME,BrowseSt.Q.ST:STATENAME) !set a column to browse
BrowseSt.InsertControl=?Insert !set the control to add records
BrowseSt.ChangeControl=?Change !set the control to change records
BrowseSt.DeleteControl=?Delete !set the control to delete records
SELF.SetAlerts() !alert any keys for ThisWindow
RETURN ReturnValue

ThisWindow.Kill PROCEDURE() !shut down things

ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill() !call base class shut down
IF ReturnValue THEN RETURN ReturnValue.
Relate:State.Close !close State and related files
Relate:State.Kill !shut down Relate:State object
GlobalErrors.Kill !shut down GlobalErrors object
RETURN ReturnValue

Access:State.Init PROCEDURE
CODE
PARENT.Init(State,GlobalErrors)
SELF.FileNameValue = 'State'
SELF.Buffer &= ST:Record
SELF.AddKey(ST:StateCodeKey,'ST:StateCodeKey',0)

Relate:State.Init PROCEDURE
CODE
Access:State.Init
PARENT.Init(Access:State,1)
BrowseClass 135

BrowseClass Properties
BrowseClass Properties
The BrowseClass inherits all the properties of the ViewManager from which it is derived. See ViewManager Properties for
more information.

In addition to the inherited properties, the BrowseClass contains the following properties:

ActiveInvisible (obscured browse list action)

ActiveInvisible BYTE
The ActiveInvisible property indicates whether to fill or refill the browse queue when the browse LIST is "invisible"
because it is on a non-selected TAB or is otherwise hidden. A value of one (1) refills the queue when the LIST is invisible;
a value of zero (0) suppresses the refill.

Setting ActiveInvisible to zero (0) improves performance for procedures with "invisible" browse lists; however, buffer
contents for the invisible browse list are not current and should not be relied upon.

Implementation: The ResetQueue method implements the behavior specified by the ActiveInvisible property.

See Also: ResetQueue

136 ABC Library Reference

AllowUnfilled (display filled list)

AllowUnfilled BYTE
The AllowUnfilled property indicates whether to always display a "full" list, or to allow a partially filled list when the result
set "ends" in mid-list. A value of one (1) displays a partially filled list and improves performance by suppressing any
additional reads needed to fill the list; a value of zero (0) always displays a filled list.

Setting AllowUnfilled to one (1) improves performance for browse lists, especially for those using SQL data.

Implementation: The ResetQueue method implements the behavior specified by the AllowUnfilled property.

See Also: ResetQueue

BrowseClass 137

ArrowAction (edit-in-place action on arrow key)

ArrowAction BYTE
The ArrowAction property indicates the action to take when the end user presses the up or down arrow key during an
edit-in-place process. There are three types of actions that ArrowAction controls:

what to do with any changes (default, save, abandon, or prompt),

what mode to use next (continue editing or revert to non-edit mode),
what column to edit next (current column or first editable column).

The specified actions are implemented by the Ask method. Set the actions by assigning, adding, or subtracting the
following EQUATEd values to ArrowAction. The following EQUATEs are in ABBROWSE.INC:
ITEMIZE,PRE(EIPAction)
Default EQUATE(0) !save according to the Ask method
Always EQUATE(1) !always save the changes
Never EQUATE(2) !never save the changes
Prompted EQUATE(4) !ask whether to save the changes
Remain EQUATE(8) !continue editing
RetainColumn EQUATE(16) !maintain column position in new row
END

Example:
BRW1.ArrowAction = EIPAction:Prompted !ask to save changes
BRW1.ArrowAction = EIPAction:Prompted+EIPAction:Remain !ask to save, keep editing
!1st editable column
BRW1.ArrowAction = EIPAction:Remain+EIPAction:RetainColumn!default save, keep editing
!same column

See Also: Ask

138 ABC Library Reference

AskProcedure (update procedure)

AskProcedure USHORT
The AskProcedure property identifies the procedure to update a browse item. A value of zero (0) uses the BrowseClass
object's own AskRecord method to do updates. Any other value uses a separate procedure registered with the
WindowManager object.

Implementation: Typically, the WindowManager object (Init method) sets the value of the AskProcedure property when a
separate update procedure is needed. The Ask method passes the AskProcedure value to the
WindowManager.Run method to indicate which procedure to execute.

See Also: Ask, AskRecord, WindowManager.Run

ChangeControl (browse change/update control number)

ChangeControl SIGNED
The ChangeControl property contains the number of the browse's change/update control. This is typically the value of
the Change BUTTON's field equate. The BrowseClass methods use this value to enable and disable the control when
appropriate, to post events to the control, to map change behavior to corresponding popup menu choices, etc.

Implementation: The BrowseClass.Init method does not initialize the ChangeControl property. You should initialize the
ChangeControl property after the BrowseClass.Init method is called. See the Conceptual Example.

See Also: UpdateToolbarButtons

BrowseClass 139

CurrentChoice (current LIST control entry number)

CurrentChoice LONG, PROTECTED
The CurrentChoice property represents the entry number of the highlighted record in a LIST control.

Implementation: The CurrentChoice property is updated as the scroll bar for the LIST control is moved within the Listbox.

DeleteAction (edit-in-place action on delete key)

DeleteAction BYTE
The DeleteAction property indicates the action to take when the end user presses the DELETE key during an edit-in-
place process. DeleteAction controls what mode to use next (continue editing or revert to non-edit mode).

The specified actions are implemented by the Ask method. Set the actions by assigning, adding, or subtracting the
following EQUATEd values to ArrowAction. The following EQUATEs are in ABBROWSE.INC:
ITEMIZE,PRE(EIPAction)
Default EQUATE(0) !save according to the Ask method
Always EQUATE(1) !always save the changes
Never EQUATE(2) !never save the changes
Prompted EQUATE(4) !ask whether to save the changes
Remain EQUATE(8) !continue editing
END

DeleteControl (browse delete control number)

DeleteControl SIGNED
The DeleteControl property contains the number of the browse's delete control. This is typically the value of the Delete
BUTTON's field equate. The BrowseClass methods use this value to enable and disable the control when appropriate, to
post events to the control, to map delete behavior to corresponding popup menu choices, etc.

Implementation: The BrowseClass.Init method does not initialize the DeleteControl property. You should initialize the
DeleteControl property after the BrowseClass.Init method is called. See the Conceptual Example.

See Also: UpdateToolbarButtons

140 ABC Library Reference

EditList (list of edit-in-place controls)

EditList &BrowseEditQueue, PROTECTED

The EditList property is a reference to a structure containing a list of edit-in-place classes for use with specific browse list
columns.

The AddEditControl method adds new edit-in-place classes and their associated browse list columns to the EditList
property.

Implementation: You do not need to initialize this property to implement the default edit-in-place controls. The EditList
property supports custom edit-in-place controls.

The EditList property is a reference to a QUEUE declared in ABBROWSE.INC as follows:

BrowseEditQueue QUEUE,TYPE
Field UNSIGNED
FreeUp BYTE
Control &EditClass
END

See Also: AddEditControl

EIP (edit-in-place manager)

EIP &BrowseEIPManager
The EIP property is a reference to the BrowseEIPManager class used by this BrowseClass object.

See Also: Init

BrowseClass 141

EnterAction (edit-in-place action on enter key)

EnterAction BYTE
The EnterAction property indicates the action to take when the end user presses the ENTER key during an edit-in-place
process.There are two types of actions that EnterAction controls:

what to do with any changes (default, save, abandon, or prompt),

what mode to use next (continue editing or revert to non-edit mode).

The specified actions are implemented by the Ask method. Set the actions by assigning, adding, or subtracting the
following EQUATEd values to ArrowAction. The following EQUATEs are in ABBROWSE.INC:
ITEMIZE,PRE(EIPAction)
Default EQUATE(0) !save according to the Ask method
Always EQUATE(1) !always save the changes
Never EQUATE(2) !never save the changes
Prompted EQUATE(4) !ask whether to save the changes
Remain EQUATE(8) !continue editing
END

Example:
BRW1.EnterAction = EIPAction:Prompted !ask to save changes
BRW1.EnterAction = EIPAction:Prompted+EIPAction:Remain !ask to save, keep editing

See Also: Ask

142 ABC Library Reference

FocusLossAction (edit-in-place action on lose focus)

FocusLossAction BYTE
The FocusLossAction property indicates the action to take with regard to pending changes when the edit control loses
focus during an edit-in-place process.

The specified action is implemented by the Ask method. Set the action by assigning, adding, or subtracting one of the
following EQUATEd values to FocusLossAction. The following EQUATEs are in ABBROWSE.INC:
ITEMIZE,PRE(EIPAction)
Default EQUATE(0) !save according to the Ask method
Always EQUATE(1) !always save the changes
Never EQUATE(2) !never save the changes
Prompted EQUATE(4) !ask whether to save the changes
END

Example:
BRW1.FocusLossAction = EIPAction:Prompted !ask to save changes

See Also: Ask

BrowseClass 143

HasThumb (vertical scroll bar flag)

HasThumb BYTE
The HasThumb property indicates whether BrowseClass object's LIST control has a vertical scroll bar. A value of one (1)
indicates a scroll bar; a value of zero (0) indicates no scroll bar.

Implementation: The SetAlerts method sets the value of the HasThumb property. The UpdateThumb method uses the
HasThumb property to implement correct thumb and scroll bar behavior.

See Also: ListControl, SetAlerts, UpdateThumb

HideSelect (hide select button)

HideSelect BYTE
The HideSelect property indicates whether to HIDE the Select button (as indicated by the SelectControl property) when
the browse is called for update purposes (as indicated by the Selecting property). A value of one (1) hides the select
button; a value of zero (0) always displays the select button.

Implementation: The ResetQueue method implements the behavior specified by the HideSelect property.

See Also: ResetQueue, SelectControl, Selecting

ILC(reference to IListControl interface)

ILC &IListControl
The ILC property is a reference to the IListControl interface which is passed to the Init method. The IListControl interface
is used to implement standard behaviors for a listbox. See the IListControl interface section for more information.

Implementation: The Init method creates an instance of ILC for the list control. The Kill method disposes of that interface
instance.

See Also: BrowseClass.Init, BrowseClass.Kill

144 ABC Library Reference

InsertControl (browse insert control number)

InsertControl SIGNED
The InsertControl property contains the number of the browse's insert control. This is typically the value of the Insert
BUTTON's field equate. The BrowseClass methods use this value to enable and disable the control when appropriate, to
post events to the control, to map Insert behavior to corresponding popup menu choices, etc.

Implementation: The BrowseClass.Init method does not initialize the InsertControl property. You should initialize the
InsertControl property after the BrowseClass.Init method is called. See the Conceptual Example.

See Also: UpdateToolbarButtons

ListQueue (browse data queue reference)

ListQueue &BrowseQueue, PROTECTED
The ListQueue property is a reference to a structure that is the source of the data elements displayed in the browse LIST.

The BrowseClass.Init method initializes the ListQueue property. See the Conceptual Example.

See Also: Init

Loaded (browse queue loaded flag)

Loaded BYTE, PROTECTED

The Loaded property contains a value that indicates whether or not the BrowseClass object has tried to load the browse
list queue. The BrowseClass uses this property to ensure the browse queue gets loaded and to avoid redundant reloads.
BrowseClass 145

Popup (browse popup menu reference)

Popup &PopupClass
The Popup property is a reference to the PopupClass class used by this BrowseClass object.

Implementation: Because it directly references the PopupClass, the BrowseClass header INCLUDEs the PopupClass
header. That is, the BrowseClass's implementation of the PopupClass is automatic. You need take no
action.

The BrowseClass.Init method instantiates the PopupClass object referenced by the Popup property. See the Conceptual
Example.

See Also: Init

PrevChoice (prior LIST control entry number)

PrevChoice LONG, PROTECTED
The PrevChoice property represents the entry number of the previously selected record in a LIST control.

Implementation: The PrevChoice property is updated as the scroll bar for the LIST control is moved within the Listbox.

PrintControl (browse print control number)

PrintControl SIGNED
The PrintControl property contains the number of the browse's print control. This is typically the value of the Print
BUTTON's field equate. The BrowseClass methods use this value to enable and disable the control when appropriate, to
post events to the control, to map Print behavior to corresponding popup menu choices, etc.

Implementation: The BrowseClass.Init method does not initialize the PrintControl property. You should initialize the
PrintControl property after the BrowseClass.Init method is called. See the Conceptual Example.

See Also: UpdateToolbarButtons

146 ABC Library Reference

PrintProcedure (print procedure)

PrintProcedure USHORT
The PrintProcedure property identifies the procedure to execute when the Browse Print action is called. The procedure
name is registered with the WindowManager object.

Implementation: Typically, the WindowManager object (Init method) sets the value of the PrintProcedure property when a
Browse Print is called. The Ask method passes the AskProcedure value to the WindowManager.Run
method to indicate which procedure to execute.

See Also: Ask

AskRecord
WindowManager.Run

Processors (reference to ProcessorQueue)

ListQueue &QUEUE, PROTECTED
The Processors property is a reference to the ProcessorQueue queue which contains references to the RecordProcessor
interface and manages several processes.

See Also: BrowseClass.Init, BrowseClass.Kill

Query (reference to QueryClass)

Query &QueryClass
The Query property is a reference to the QueryClass which manages Query-by-Example processes for the BrowseClass.

See Also: BrowseClass.Init

BrowseClass.Kill
BrowseClass 147

QueryControl (browse query control number)

QueryControl SIGNED
The QueryControl property contains the number of the browse's query (QBE) control. This is typically the value of the
QBE BUTTON's field equate. The BrowseClass methods use this value to enable and disable the control when
appropriate, to post events to the control, to map QBE behavior to corresponding popup menu choices, etc.

Implementation: The BrowseClass.Init method does not initialize the QueryControl property. You should initialize the
QueryControl property after the BrowseClass.Init method is called. See the Conceptual Example.

See Also: UpdateToolbarButtons

QueryShared (share query with multiple sorts)

QueryShared BYTE
The QueryShared property contains a value that tells the BrowseClass whether or not to keep queries active when
changing different sort orders. An example of this is when switching from one tab control to another in the active browse.

A value of zero (0) disables sharing (the query is only active for the tab in which it is set); a value of 1 enables sharing.

Implementation: The QueryShared property is ser by the Query Button template interface when the Auto-share between
tabs option is checked.
148 ABC Library Reference

QuickScan (buffered reads flag)

QuickScan BYTE
The QuickScan property contains a value that tells the BrowseClass whether or not to quickscan when page-loading the
browse list queue. Quick scanning only affects file systems that use multi-record buffers. See Database Drivers for more
information.

A value of zero (0) disables quick scanning; a non-zero value enables quick scanning. Quick scanning is the normal way
to read records for browsing. However, rereading the buffer may provide slightly improved data integrity in some multi-
user circumstances at the cost of substantially slower reads.

Implementation: TheBrowseClass.Fetch method implements the faster reads only during the page-loading process, and
only if the QuickScan property is not zero. The BrowseClass.Fetch method SENDs the
'QUICKSCAN=ON' driver string to the applicable files' database drivers with the
RelationManager.SetQuickScan method.

Note: The RelationManager.SetQuickScan method does not set the BrowseClass.QuickScan property. However
if you set the BrowseClass.QuickScan property to 1, the BrowseClass uses the
RelationManager.SetQuickScan method to SEND the QUICKSCAN driver string to the appropriate files.

See Also: Fetch, RelationManager.SetQuickScan.

BrowseClass 149

RetainRow (highlight bar refresh behavior)

RetainRow BYTE
The RetainRow property indicates whether the BrowseClass object tries to maintain the highlight bar in the same list row
following a change in sort order, an update, or other browse refresh action. A value of one (1) maintains the current
highlight bar row; a value of zero (0) lets the highlight bar move to the first row.

Setting RetainRow to one (1) can cause a performance penalty in applications using TopSpeed's pre-Accelerator ODBC
driver.

Implementation: The Init method sets the RetainRow property to one (1). The ResetQueue method implements the
behavior specified by the RetainRow property.

See Also: Init, ResetQueue

SelectControl (browse select control number)

SelectControl SIGNED
The SelectControl property contains the number of the browse's select control. This is typically the value of the Select
BUTTON's field equate. The BrowseClass methods use this value to enable and disable the control when appropriate, to
post events to the control, to map Select behavior to corresponding popup menu choices, etc.

Implementation: The BrowseClass.Init method does not initialize the SelectControl property. You should initialize the
SelectControl property after the BrowseClass.Init method is called. See the Conceptual Example.

See Also: UpdateToolbarButtons

150 ABC Library Reference

Selecting (select mode only flag)

Selecting BYTE
The Selecting property indicates whether the BrowseClass object selects a browse item or updates browse items. A
value of zero (0) sets update mode; a value of one (1) sets select only mode.

The HideSelect property is only effective when the Selecting property indicates update mode.

Implementation: In select mode, a DOUBLE-CLICK or ENTER selects the item; otherwise, a DOUBLE-CLICK or ENTER
updates the item.

See Also: HideSelect

SelectWholeRecord (select entire record flag)

SelectWholeRecord BYTE
The SelectWholeRecord property indicates whether an UpdateViewRecord should be called in the TakeEvent method.
A value of one (1) will get the whole record from the view; a value of zero (0), the default, gets the record from the buffer.

See Also: UpdateViewRecord, TakeEvent

BrowseClass 151

Sort (browse sort information)

Sort &BrowseSortOrder
The Sort property is a reference to a structure containing all the sort information for this BrowseClass object. The
BrowseClass methods use this property to implement multiple sort orders, range limits, filters, and locators for a single
browse list.

Implementation: The BrowseClass.Sort property mimics or shadows the inherited ViewManager.Order property. The Sort
property is a reference to a QUEUE declared in ABBROWSE.INC as follows:
BrowseSortOrder QUEUE(SortOrder),TYPE !browse sort information
Locator &LocatorControl !locator for this sort order
Resets &FieldPairsClass !reset fields for this sort order
Thumb &ThumbClass !ThumbClass for this sort order
END

Notice this BrowseSortOrder queue contains all the fields in the SortOrder queue declared in ABFILE.INC
as follows:
SortOrder QUEUE,TYPE !VIEW sort information
Filter &FilterQueue !ANDed filter expressions
FreeElement ANY !The Free key element
LimitType BYTE !Range limit type flag
MainKey &KEY !The KEY
Order &STRING !ORDER expression (equal to KEY)
RangeList &FieldPairsClass !fields in the range limit
END

And the SortOrder queue contains a reference to the FilterQueue declared in ABFILE.INC as follows:
FilterQueue QUEUE,TYPE !VIEW filter information
ID STRING(30) !filter ID
Filter &STRING !filter expression
END

So, the BrowseSortOrder queue is, among other things, a queue of queues.

The AddSortOrder method defines sort orders for the browse. The SetSort method applies or activates a
sort order for the browse. Only one sort order is active at a time.

See Also: AddSortOrder, SetSort

152 ABC Library Reference

StartAtCurrent (initial browse position)

StartAtCurrent BYTE
The StartAtCurrent property indicates whether the BrowseClass object initially positions to the first item in the sort order
or positions to the item specified by the contents of the Browse's view buffer. A value of zero (0 or False) positions to the
first item; a value of one (1 or True) positions to the item specified by the contents of the view buffer.

Implementation: The SetSort method implements the StartAtCurrent initial position. The SetSort method positions the
browse list based on the contents of the fields in the active sort order, including the free element field.

Example:
BRW1.StartAtCurrent = True
ST:StateCode = 'K' !set key component value
BrowseSt.Init(?StList,StateQ.ViewPosition,StView,StateQ,Relate:State,SELF)

See Also: SetSort

BrowseClass 153

TabAction (edit-in-place action on tab key)

TabAction BYTE
The TabAction property indicates the action to take when the end user presses the TAB key during an edit-in-place
process. There are two types of actions that TabAction controls:

what to do with pending changes (default, save, abandon, or prompt),

what mode to use next (continue editing or revert to non-edit mode).

The specified actions are implemented by the Ask method. Set the actions by assigning, adding, or subtracting the
following EQUATEd values to TabAction. The following EQUATEs are in ABBROWSE.INC:
ITEMIZE,PRE(EIPAction)
Default EQUATE(0) !save according to the Ask method
Always EQUATE(1) !always save the changes
Never EQUATE(2) !never save the changes
Prompted EQUATE(4) !ask whether to save the changes
Remain EQUATE(8) !continue editing
END

Example:
BRW1.TabAction = EIPAction:Prompted !ask to save changes
BRW1.TabAction = EIPAction:Prompted+EIPAction:Remain !ask to save, keep editing

See Also: Ask

154 ABC Library Reference

Toolbar (browse Toolbar object)

Toolbar &ToolbarClass
The Toolbar property is a reference to the ToolbarClass for this BrowseClass object. The ToolbarClass object collects
toolbar events and passes them on to the active ToolbarTarget object for processing.

The AddToolbarTarget method registers a ToolbarTarget, such as a ToolbarListBoxClass object, as a potential target of a
ToolbarClass object.

The ToolbarClass.SetTarget method sets the active target for a ToolbarClass object.

Implementation: The ToolbarClass object for a browse is the object that detects toolbar events, such as scroll down or
page down, and passes them on to the active ToolbarListBoxClass (ToolbarTarget) object. In the
standard template implementation, there is a single global toolbar, and a ToolbarClass object per
procedure that may drive several different browses and forms, each of which is a ToolbarTarget. Only
one ToolbarTarget is active at a time.

See Also: ToolbarItem, AddToolbarTarget, ToolbarClass.SetTarget

BrowseClass 155

ToolbarItem (browse ToolbarTarget object)

ToolbarItem &ToolbarListBoxClass
The ToolbarItem property is a reference to the ToolbarListBoxClass for this BrowseClass object. The
ToolbarListBoxClass (ToolbarTarget) object receives toolbar events (from a ToolbarClass object) and processes them.

The AddToolbarTarget method registers a ToolbarTarget, such as a ToolbarListBoxClass object, as a potential target of a
ToolbarClass object.

The ToolbarClass.SetTarget method sets the active target for a ToolbarClass object.

Implementation: The ToolbarClass object for a browse is the object that detects toolbar events, such as scroll down or
page down, and passes them on to the active ToolbarListBoxClass (ToolbarTarget) object. In the
standard template implementation, there is a single global toolbar, and a ToolbarClass object per
procedure that may drive several different browses and forms, each of which is a ToolbarTarget. Only
one ToolbarTarget is active at a time.

See Also: Toolbar, AddToolbarTarget, ToolbarClass.SetTarget

156 ABC Library Reference

ToolControl (browse toolbox control number)

ToolControl SIGNED
The ToolControl property contains the number of the browse's toolbox control. This is typically the value of the Toolbox
BUTTON's field equate. The BrowseClass methods use this value to enable and disable the control when appropriate, to
post events to the control, to map Toolbox behavior to corresponding popup menu choices, etc.

Implementation: The BrowseClass.Init method does not initialize the ToolControl property. You should initialize the
ToolControl property after the BrowseClass.Init method is called. See the Conceptual Example.

See Also: UpdateToolbarButtons

ViewControl (view button)

ViewControl SIGNED
The ViewControl property contains the number (field equate) of the browse's view button control.

Window (WindowManager object)

Window &WindowManager
The Window property is a reference to the WindowManager object for this BrowseClass object. The WindowManager
object forwards events to the active BrowseClass object for processing.

The WindowManager.AddItem method registers the BrowseClass object with the WindowManager object, so the
WindowManager object can forward events.

The Init method sets the value of the Window property.

Implementation: The WindowManager object calls the BrowseClass.TakeEvent method so the BrowseClass object can
handle the events as needed.

See Also: Init, WindowManager.AddItem

BrowseClass 157

BrowseClass Methods
BrowseClass Methods
The BrowseClass inherits all the methods of the ViewManager from which it is derived. See ViewManager Methods for
more information.

BrowseClass Functional Organization--Expected Use

As an aid to understanding the BrowseClass, it is useful to organize its various methods into two large categories
according to their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is
typical use of the BrowseClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

Init initialize the BrowseClass object
AddEditControl specify custom edit-in-place for a browse field
AddField identify corresponding FILE and QUEUE fields
AddLocator associate a locator with its sort order
AddResetField specify a field that refreshes the browse list
AddSortOrder add a sort order to the browse list
AddToolbarTarget associate the browse list with a toolbar object
SetAlertsV alert keys for list, locator, and edit controls
Kill V shut down the BrowseClass object
Mainstream Use:
NextV get the next view record in sequence
PreviousV get the previous view record in sequence
Ask update the selected item
TakeEventV process the current ACCEPT loop event
TakeNewSelectionV process a new browse list item selection

V These methods are also Virtual.

Occasional Use:
ApplyRange refresh browse list to specified range limit
AskRecord edit-in-place the selected item
PostNewSelection post an EVENT:NewSelection to the browse list
Records return the number of records in the browse list
ResetResets snapshot the current value of the Reset fields
ResetThumbLimits reset thumb limits to match the result set
TakeAcceptedLocator apply an entered locator value
UpdateResets copy reset fields to file buffer
UpdateThumb position the scrollbar thumb
UpdateThumbFixed position the scrollbar fixed thumb
UpdateWindow V apply pending scroll, locator, range, etc.
158 ABC Library Reference

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.
ApplyRange conditionally range limit and filter the records
Fetch loads a page of items into the browse list
Kill shut down the BrowseClass object
Next get the next record from the browse view
Previous get the previous record from the browse view
ResetI reset the view position
ResetFromAsk reset browse object after update
ResetFromBuffer refill queue based on current record buffer
ResetFromFile refill queue based on FILE POSITION
ResetFromView reset browse object to its result set
ResetQueue fill or refill the browse queue
ScrollEnd scroll to the first or last item
ScrollOne scroll up or down one item
ScrollPage scroll up or down one page of items
SetAlerts alert keys for list, locator, and edit controls
SetQueueRecord copy data from file buffer to queue buffer
SetSort apply sort order to browse
ResetSort apply sort order to browse
TakeKey process an alerted keystroke
TakeEvent process the current ACCEPT loop event
TakeNewSelection process a new browse list item selection
TakeScroll process a scroll event
TakeVCRScroll process a VCR scroll event
UpdateBuffer copy data from queue buffer to file buffer
UpdateViewRecord copy selected item to corresponding file buffers
UpdateWindow apply pending scroll, locator, range, etc.

Use ResetSort followed by UpdateWindow to refresh and redisplay your ABC BrowseBoxes. Or, use the
WindowManager.Reset method.
BrowseClass 159

AddEditControl (specify custom edit-in-place class)

AddEditControl( [editclass], column [, autofree] )

AddEditControl Specifies a custom edit-in-place class for a browse field.

editclass The label of the EditClass. If omitted, the specified column is not editable.
column An integer constant, variable, EQUATE, or expression that indicates the browse list column to edit with
the specified editclass object. A value of one (1) indicates the first column; a two (2) indicates the second
column, etc.
autofree A numeric constant, variable, EQUATE, or expression that indicates whether the BrowseClass.Kill
method DISPOSEs of the editclass object. A zero (0) value leaves the object intact. A non-zero value
DISPOSEs the object. If omitted, autofree defaults to zero (0).
The AddEditControl method specifies the editclass that defines the edit-in-place control for the browse column. Use
autofree with caution; you should only DISPOSE of memory allocated with a NEW statement. See the Language
Reference for more information on NEW and DISPOSE.

Implementation: You do not need to call this method to use the default editclass. If you do not call the AddEditControl
method for a browse list column, the BrowseClass automatically instantiates the EditClass declared in
ABBROWSE.INC for that column.

The autofree parameter defaults to zero (0). The BrowseClass.Kill method DISPOSEs the editclass
objects only if autofree contains a non-zero value.

The BrowseClass.Ask method instantiates the editclass objects as needed, then creates and deletes the
edit-in-place control upon the end user's insert or change request.

Example:
INCLUDE('ABBROWSE.INC') !declare browse & related classes
INCLUDE('MYCOMBO.INC') !declare custom Edit-in-place control class
!other browse class declarations
CODE
MyBrowse.AddEditControl(,1) !column 1 not editable
MyBrowse.AddEditControl(ComboClass,2) !edit column 2 with combo control

See Also: Ask

160 ABC Library Reference

AddField (specify a FILE/QUEUE field pair)

AddField( filefield, queuefield )

AddField Identifies the corresponding FILE and QUEUE fields for a browse list column.
filefield The fully qualified label of the FILE field or memory variable. The filefield is the original source of the
browse LIST's data.
queuefield The fully qualified label of the corresponding QUEUE field. The queuefield is loaded from the filefield, and
is the immediate source of the browse LIST's data.
The AddField method identifies the corresponding FILE and QUEUE fields for a browse list column. You must call
AddField for each column displayed in the browse list.

You may also use the AddField method to pair memory variables with QUEUE fields by specifying a variable label as the
filefield parameter.

Implementation: For browses with edit-in-place, you must add fields (call the AddField method) in the same sequence that
you declare the browse QUEUE fields.

Example:
INCLUDE('ABBROWSE.INC') !declare browse & related classes
States FILE,DRIVER('TOPSPEED'),PRE(StFile) !declare States file
ByCode KEY(StFile:Code),NOCASE,OPT
Record RECORD,PRE()
Code STRING(2)
Name STRING(20)
END
END
StQType QUEUE,TYPE !declare the St QUEUE type
Code LIKE(StFile:Code)
Name LIKE(StFile:Name)
Position STRING(512)
END
BrowseStClass CLASS(BrowseClass),TYPE !declare the BrowseSt CLASS
Q &StQType
END
StQ StQType !declare the (real) StQ QUEUE
BrowseSt BrowseStClass !declare the BrowseSt object
CODE
BrowseSt.AddField(StFile:Code,BrowseSt.Q.Code) !pair up fields in
BrowseSt.AddField(StFile:Name,BrowseSt.Q.Name) !FILE & QUEUE
BrowseClass 161

AddItem(program the BrowseClass object)

AddItem(RecordProcessor)

AddItem Adds specific functionality to the BrowseClass object.

RecordProcessor The label of a RecordProcessor interface.

The AddItem method registers an ABC Library interface with the BrowseClass object and adds the interface's specific
functionality to the BrowseClass.
See Also: BrowseClass.Kill

AddLocator (specify a locator)

AddLocator( locator )

AddLocator Specifies a locator object for a specific sort order.

locator The label of the locator object.
The AddLocator method specifies a locator object for the sort order defined by the preceding call to the AddSortOrder or
SetSort method. Typically, you call the AddLocator method immediately after the AddSortOrder method.

Implementation: The specified locator is sort order specific--it is enabled only when the associated sort order is active. The
SetSort method applies or activates a sort order for the browse. Only one sort order is active at a time.

Example:
BrowseSt.AddSortOrder(BrowseSt:Step,StFile:ByCode) !add sort order and
BrowseSt.AddLocator(BrowseSt:Locator) !associated locator
BrowseSt:Locator.Init(?Loc,StFile:StCode,1,BrowseSt)!init locator object

See Also: AddSortOrder, LocatorClass, SetSort

162 ABC Library Reference

AddResetField (set a field to monitor for changes)

AddResetField( resetfield)

AddResetField Specifies a field that resets the browse list when the contents of the field changes.
resetfield The label of the field to monitor for changes.
For the active sort order (defined by the preceding call to the AddSortOrder or SetSort method), the AddResetField
method specifies a field that the browse object monitors for changes, then, when the contents of the field changes,
refreshes the browse list. Typically, you call the AddResetField method immediately after the AddSortOrder method.

You may call AddResetField multiple times to establish multiple reset fields for a sort order.

Implementation: The specified resetfield is sort order specific--it is enabled only when the associated sort order is active.
The SetSort method sets the active sort order for the browse. SetSort also calls ApplyRange to monitor
the reset fields for changes and SetSort resets the browse when a change occurs.

The WindowManager.Reset method also initiates an evaluation of the reset fields and a subsequent
browse reset if needed for any browse objects registered with the WindowManager.

Example:
BrowseSt.AddSortOrder(BrowseSt:Step,StFile:ByCode) !add sort order
BrowseSt.AddLocator(BrowseSt:Locator) !and associated locator
BrowseSt.AddResetField(Local:StFilter) !and associated reset field

See Also: AddSortOrder, SetSort, WindowManager.Reset

BrowseClass 163

AddSortOrder (specify a browse sort order)

AddSortOrder( [thumbstep] [, key ]), PROC

AddSortOrder Specifies an additional sort order for the browse list.

thumbstep The label of the StepClass object that controls vertical scroll bar and thumb behavior. If omitted, the
vertical scroll bar exhibits Fixed Thumb behavior. See Control Templates--BrowseBox for more
information on thumb behavior.
key The label of the KEY to sort by. If omitted, the browse list is not sorted--the items appear in physical
order, or in the order specified by the inherited AppendOrder method.
The AddSortOrder method specifies an additional sort order for the browse list and returns the sort order's sequence
number for use with the SetSort method. You must call the AddSortOrder method for each different sort order applied to
the browse list.

The AddLocator method adds an associated locator for the sort order defined by the preceding call to AddSortOrder.

The AddResetField method adds an associated reset field for the sort order defined by the preceding call to
AddSortOrder. You may add multiple reset fields for each sort order with multiple calls to AddResetField.

The inherited AddRange method adds an associated range limit for the sort order defined by the preceding call to
AddSortOrder.

Implementation: The AddSortOrder method adds an entry at a time to the Sort property.

Return Data Type: BYTE

Example:
BrowseSt.AddSortOrder(BrowseSt:Step,StFile:ByCode) !add sort order
BrowseSt.AddLocator(BrowseSt:Locator) !and associated locator
BrowseSt.AddResetField(Local:StFilter) !and associated reset field

See Also: AddLocator, AddResetField, Sort, StepClass, SetSort, ViewManager.AddRange,

ViewManager.AppendOrder
164 ABC Library Reference

AddToolbarTarget (set the browse toolbar)

AddToolbarTarget( toolbar )

AddToolbarTarget Registers the browse list as a potential target of the specified toolbar.
toolbar The label of the ToolbarClass object that directs toolbar events to this BrowseClass object.
The AddToolbarTarget method registers the BrowseClass object as a potential target of the specified toolbar.

The ToolbarClass.SetTarget method sets the active target for a ToolbarClass object.

Implementation: The Toolbar object for a browse is the object that detects toolbar events, such as scroll down or page
down, and passes them on to the active ToolbarTarget object. In the standard template implementation,
there is a single global toolbar, and a Toolbar object per procedure that may drive several different
browses and forms, each of which is a ToolbarTarget. Only one ToolbarTarget is active at a time.

Example:
BrowseSt.AddToolbarTarget(Browse:Toolbar) !tie BrowseSt object to Toolbar object
BrowseZIP.AddToolbarTarget(Browse:Toolbar) !tie BrowseZIP object to Toolbar object
!program code
Browse:Toolbar.SetTarget(?StList) !state list is current toolbar target
!program code
Browse:Toolbar.SetTarget(?ZIPList) !ZIP list is current toolbar target

See Also: Toolbar, ToolbarItem, ToolbarClass.SetTarget

BrowseClass 165

ApplyRange (refresh browse based on resets and range limits)

ApplyRange, VIRTUAL, PROC

The ApplyRange method checks the current status of reset fields and range limits and refreshes the browse list if
necessary. Then it returns a value indicating whether a screen redraw is required.

The inherited AddRange method adds an associated range limit for each sort order. The AddResetField method
establishes reset fields for each browse sort order.

Implementation: The ApplyRange method returns one (1) if a screen redraw is required or zero (0) if no redraw is required.

Return Data Type: BYTE

Example:
IF BrowseSt.ApplyRange() !refresh browse queue if things changed
DISPLAY(?StList) !redraw LIST if queue refreshed
END

See Also: AddResetField, ViewManager.AddRange

166 ABC Library Reference

Ask (update selected browse item)

Ask( request ), VIRTUAL, PROC

Ask Updates the selected browse record.

request A numeric constant, variable, EQUATE, or expression that indicates the requested update action. Valid
actions are Insert, Change, and Delete.
The Ask method updates the selected browse record and returns a value indicating whether the requested update was
completed or cancelled.
Implementation: Depending on the value of the AskProcedure property, the Ask method either calls the
WindowManager.Run method to execute a specific update procedure, or it calls the AskRecord method to
do an edit-in-place update.

The TakeEvent method calls the Ask method. The Ask method assumes the UpdateViewRecord method
has been called to ensure correct record buffer contents.
Return value EQUATEs are declared in \LIBSRC\TPLEQU.CLW:
RequestCompleted EQUATE (1) !Update Completed
RequestCancelled EQUATE (2) !Update Aborted

EQUATEs for request are declared in \LIBSRC\TPLEQU.CLW:

InsertRecord EQUATE (1) !Add a record to table
ChangeRecord EQUATE (2) !Change the current record
DeleteRecord EQUATE (3) !Delete the current record

Return Data Type: BYTE

Example:
BrowseClass.TakeEvent PROCEDURE
!procedure data
CODE
!procedure code
CASE ACCEPTED()
OF SELF.DeleteControl
SELF.Window.Update()
SELF.Ask(DeleteRecord) !delete a browse item
OF SELF.ChangeControl
SELF.Window.Update()
SELF.Ask(ChangeRecord) !change a browse item
OF SELF.InsertControl
SELF.Window.Update()
SELF.Ask(InsertRecord) !insert a browse item
OF SELF.SelectControl
SELF.Window.Response = RequestCompleted
POST(EVENT:CloseWindow)
ELSE
SELF.TakeAcceptedLocator
END

See Also: AskProcedure, AskRecord, TakeEvent

BrowseClass 167

AskRecord (edit-in-place selected browse item)

AskRecord( request ), VIRTUAL, PROC

AskRecord Does edit-in-place update of the selected browse record.

request A numeric constant, variable, EQUATE, or expression that indicates the requested edit-in-place action.
Valid edit-in-place actions are Insert, Change, and Delete.
The AskRecord method does edit-in-place updates for the selected browse row and column, then returns a value
indicating whether the requested edit was completed or cancelled. The AddEditControl method specifies a custom
EditClass for a specific browse column.
Implementation: The AskRecord method assumes the UpdateViewRecord method has been called to ensure correct
record buffer contents. AskRecord should be followed by the ResetFromAsk method. The Ask
method calls the AskRecord method.
Return value EQUATEs are declared in \LIBSRC\TPLEQU.CLW:
RequestCompleted EQUATE (1) !Update Completed
RequestCancelled EQUATE (2) !Update Aborted

EQUATEs for request are declared in \LIBSRC\TPLEQU.CLW:

InsertRecord EQUATE (1) !Add a record to table
ChangeRecord EQUATE (2) !Change the current record
DeleteRecord EQUATE (3) !Delete the current record

Return Data Type: BYTE

Example:
BrowseClass.Ask PROCEDURE(BYTE Req)
Response BYTE
CODE
LOOP
SELF.Window.VCRRequest = VCR:None
IF Req=InsertRecord THEN
SELF.PrimeRecord
END
IF SELF.AskProcedure
Response = SELF.Window.Run(SELF.AskProcedure,Req) !do edit-in-place update
SELF.ResetFromAsk(Req,Response)
ELSE
Response = SELF.AskRecord(Req)
END
UNTIL SELF.Window.VCRRequest = VCR:None
RETURN Response

See Also: AddEditControl, Ask, ResetFromAsk

168 ABC Library Reference

Fetch (get a page of browse items)

Fetch( direction ), VIRTUAL, PROTECTED

Fetch Loads a page of items into the browse list queue.

direction A numeric constant, variable, EQUATE, or expression that indicates whether to get the next set of items
or the previous set of items.
The Fetch method loads the next or previous page of items into the browse list queue.

Implementation: Fetch is called by the ResetQueue, ScrollOne, ScrollPage, and ScrollEnd methods. A page of items is as
many items as fits in the LIST control.

BrowseClass.Fetch direction value EQUATEs are declared in ABBROWSE.INC as follows:

FillBackward EQUATE(1)
FillForward EQUATE(2)

Example:
ScrollOne PROCEDURE(SIGNED Event)
CODE
IF Event = Event:ScrollUp AND CurrentChoice > 1
CurrentChoice -= 1
ELSIF Event = Event:ScrollDown AND CurrentChoice < RECORDS(ListQueue)
CurrentChoice += 1
ELSE
ItemsToFill = 1
MyBrowse.Fetch( CHOOSE( Event = EVENT:ScrollUp, FillForward, FillBackward ))
END

See Also: ResetQueue, ScrollOne, ScrollPage, ScrollEnd

BrowseClass 169

Init(initialize the BrowseClass object)

Init(|listcontrol, viewposition, view, listqueue, relationmanager, windowmanager |)

|ilistcontrol, view, browsequeue, relationmanager, windowmanager |

Init Initializes the BrowseClass object.

listcontrol A numeric constant, variable, EQUATE, or expression containing the control number of the browse's LIST
control.
ilistcontrol A reference to an IListControl interface.
viewposition The label of a string field within the listqueue containing the POSITION of the view.
view The label of the browse's underlying VIEW.
listqueue The label of the listcontrol's data source QUEUE.
browsequeue A reference to a BrowseQueue interface.
relationmanager
The label of the browse's primary file RelationManager object. See Relation Manager for more
information.
windowmanager
The label of the browse's WindowManager object. See Window Manager for more information.

The Init method initializes the BrowseClass object.

Init(listcontrol, viewposition, view, listqueue, relationmanager, windowmanager)

Initializes the BrowseClass object using the Standard Behaviour interface. For more
information see the StandardBehaviour section.
Init(ilistcontrol, view, browsequeue, relationmanager, windowmanager)
Initializes the BrowseClass object without the Standard Behaviour interface. The Init
method calls the PARENT.Init (ViewManager.Init) method to initialize the browse's
ViewManager object. See View Manager for more information. The Init method
instantiates a PopupClass object for the browse. The Init method calls the
WindowManager.AddItem method to register its presence with the WindowManager.

Example:
CODE !Setup the BrowseClass object:
BrowseState.Init(?StateList,| ! identify its LIST control,
StateQ.Position, | ! its VIEW position string,
StateView, | ! its source/target VIEW,
StateQ, | ! the LIST's source QUEUE,
Relate:State | ! the primary file RelationManager
ThisWindow) ! the WindowManager

See Also: ViewManager.Init, PopupClass, WindowManager.AddItem, StandardBehavior Interface

170 ABC Library Reference

InitSort (initialize locator values)

InitSort (neworder), VIRTUAL

The InitSort method initializes locator values when a new sort order is applied to a browse list.

See Also: SetSort

Kill (shut down the BrowseClass object)

Kill, VIRTUAL
The Kill method shuts down the BrowseClass object.

Implementation: Among other things, the BrowseClass.Kill method calls the PARENT.Kill (ViewManager.Kill) method to
shut down the browse's ViewManager object. See View Manager for more information.

Example:
CODE !Setup the BrowseClass object:
BrowseState.Init(?StateList,| ! identify its LIST control,
StateQ.Position, | ! its VIEW position string,
StateView, | ! its source/target VIEW,
StateQ, | ! the LIST's source QUEUE,
Relate:State | ! the primary file RelationManager
ThisWindow) ! the WindowManager

!program code

BrowseState.Kill !shut down the BrowseClass object

See Also: ViewManager.Kill

BrowseClass 171

Next (get the next browse item)

Next, VIRTUAL
The Next method gets the next record from the browse view and returns a value indicating its success or failure.

Next returns Level:Benign if successful, Level:Notify if it reached the end of the file, and Level:Fatal if it encountered a
fatal error.

Implementation: Corresponding return value EQUATEs are declared in ABERROR.INC. See Error Class for more
information on these severity level EQUATEs.
Level:Benign EQUATE(0)
Level:User EQUATE(1)
Level:Program EQUATE(2)
Level:Fatal EQUATE(3)
Level:Cancel EQUATE(4)
Level:Notify EQUATE(5)

The Next method is called by the Fetch and ResetThumbLimits(PRIVATE) methods. Among other things,
Next calls the PARENT.Next (ViewManager.Next) method. See ViewManager for more information.

Return Data Type: BYTE

Example:
CASE MyBrowse.Next() !get next record
OF Level:Benign !if successful, continue
OF Level:Fatal !if fatal error
RETURN ! end this procedure
OF Level:Notify !if end of file reached
MESSAGE('Reached end of file.') ! acknowledge EOF
END

See Also: Fetch

172 ABC Library Reference

NotifyUpdateError (throw error on update)

NotifyUpdateError( ), BYTE, VIRTUAL

The NotifyUpdateError method returns an error code to the active ErrorManager when an attempted update to refresh a
record has failed.

Implementation: The NotifyUpdateError is called from the BrowseClass UpdateViewRecord method, which is used to
retrieve the VIEW record that corresponds to a chosen listbox record.

Return Data Type: BYTE

Example:
IF SELF.ListQueue.Records()
SELF.CurrentChoice = SELF.ILC.Choice()
SELF.ListQueue.Fetch(SELF.CurrentChoice)
WATCH(SELF.View)
REGET(SELF.View,SELF.ListQueue.GetViewPosition())
RC = ERRORCODE()
IF RC = NoDriverSupport
Pos = POSITION (SELF.View)
RESET(SELF.View,SELF.ListQueue.GetViewPosition())
WATCH(SELF.View)
NEXT(SELF.View)
RC = ERRORCODE()
RESET(SELF.View,Pos)
END
IF RC <> 0
SELF.NeedRefresh = SELF.NotifyUpdateError()
END
END

See Also: UpdateViewRecord

BrowseClass 173

PostNewSelection (post an EVENT:NewSelection to the browse list)

PostNewSelection
The PostNewSelection method posts an EVENT:NewSelection to the browse list to support scrolling, inserts, deletes,
and other changes of position within the browse list.

Implementation: Event EQUATEs are declared in EQUATES.CLW.

Example:
UpdateMyBrowse ROUTINE
!update code
MyBrowse.ResetFromFile !after insert or change, reload Q from file
MyBrowse.PostNewSelection !after update, post a new selection event
!so window gets properly refreshed
174 ABC Library Reference

Previous (get the previous browse item)

Previous, VIRTUAL
The Previous method gets the previous record from the browse view and returns a value indicating its success or failure.

Implementation: Returns Level:Benign if successful, Level:Notify if it reached the end of the file, and Level:Fatal if it
encountered a fatal error. Corresponding severity level EQUATEs are declared in ABERROR.INC. See
Error Class for more information on error severity levels.
Level:Benign EQUATE(0)
Level:User EQUATE(1)
Level:Program EQUATE(2)
Level:Fatal EQUATE(3)
Level:Cancel EQUATE(4)
Level:Notify EQUATE(5)

The Previous method is called by the Fetch and ResetThumbLimits methods. Among other things,
Previous calls the PARENT.Previous (ViewManager.Previous) method. See ViewManager for more
information.

Return Data Type: BYTE

Example:
CASE MyBrowse.Previous() !get previous record
OF Level:Benign !if successful, continue
OF Level:Fatal !if fatal error
RETURN ! end this procedure
OF Level:Notify !if end of file reached
MESSAGE('Reached end of file.')! acknowledge EOF
END

See Also: Fetch

BrowseClass 175

Records (return the number of browse queue items)

Records, PROC
The Records method returns the number of records in the browse list queue and disables appropriate controls if the
record count is zero.

Return Data Type: LONG

Example:
DeleteMyBrowse ROUTINE
!delete code
MyBrowse.Records() !disable delete button (and menu) if no items

ResetFields(reinitialize FieldPairsClass)
ResetFields
The ResetFields method reinitializes the FieldPairs recognized by the FieldPairsClass.

Implementation: The ResetFields method reinitializes the FieldPairs by first disposing the FieldsPairsClass and then
initializing the FieldPairsClass.

See Also: FieldPairsClass.Init , FieldPairsClass.Kill

176 ABC Library Reference

ResetFromAsk (reset browse after update)

ResetFromAsk( request, response ), VIRTUAL, PROTECTED

ResetFromAsk Resets the BrowseClass object following an update.

request A BYTE variable or value that indicates the type of update requested. Valid updates are insert (1), change
(2), and delete (3).
response A BYTE variable or value that indicates whether the requested update was completed (1) or cancelled
(2).
The ResetFromAsk method resets the BrowseClass object following an Ask or AskRecord update to a browse item.

Implementation: The Ask and AskRecord methods call ResetFromAsk as needed to reset the BrowseClass object.

ResetFromAsk FLUSHes the BrowseClass object's VIEW if needed, calls the appropriate "reset" method
(ResetQueue, ResetFromFile, or ResetFromView) to refill the QUEUE, then carries out any pending scroll
request made concurrently with the update. See WindowManager.VCRRequest.

EQUATEs for the request parameter are declared in \LIBSRC\TPLEQU.CLW as follows:

InsertRecord EQUATE (1) !Add a record to table
ChangeRecord EQUATE (2) !Change the current record
DeleteRecord EQUATE (3) !Delete the current record

EQUATEs for the response parameter are declared in \LIBSRC\TPLEQU.CLW as follows:

RequestCompleted EQUATE (1) !Update Completed
RequestCancelled EQUATE (2) !Update Aborted

Example:
BrowseClass.Ask PROCEDURE(BYTE Req)
Response BYTE
CODE
LOOP
SELF.Window.VCRRequest = VCR:None
IF Req=InsertRecord THEN
SELF.PrimeRecord
END
IF SELF.AskProcedure
Response = SELF.Window.Run(SELF.AskProcedure,Req)
SELF.ResetFromAsk(Req,Response) !reset the browse after update
ELSE
Response = SELF.AskRecord(Req)
END
UNTIL SELF.Window.VCRRequest = VCR:None
RETURN Response

See Also: Ask, AskRecord, ResetQueue, ResetFromFile, ResetFromView, WindowManager.VCRRequest

BrowseClass 177

ResetFromBuffer (fill queue starting from record buffer)

ResetFromBuffer, VIRTUAL
The ResetFromBuffer method fills or refills the browse queue starting from the record in the primary file buffer (and
secondary file buffers if applicable). If the record is found, ResetFromBuffer fills the browse queue starting from that
record. If the record is not found, ResetFromBuffer fills the browse queue starting from the nearest matching record.

If the active sort order (key) allows duplicates and duplicate matches exist, ResetFromBuffer fills the browse queue
starting from the first matching record.

Tip: Use ResetFromBuffer when the primary and secondary file positions and values are valid, but the result
set may no longer match the buffer values. For example, after a locator or scrollbar thumb move.

Implementation: ResetFromBuffer succeeds even if there is no exactly matching record and is typically used to locate the
appropriate record after a thumb movement.

ResetFromBuffer calls the ViewManager.Reset method for positioning, then calls the ResetQueue
method to fill the browse queue.

Example:
IF EVENT() = EVENT:ScrollDrag !if thumb moved
IF ?MyList{PROP:VScrollPos} <= 1 !handle scroll to top
POST(Event:ScrollTop, ?MyList)
ELSIF ?MyList{PROP:VScrollPos} = 100 !handle scroll to bottom
POST(Event:ScrollBottom, ?MyList)
ELSE !handle intermediate scroll
MyBrowse.Sort.FreeElement = MyBrowse.Sort.Step.GetValue(?MyList{PROP:VScrollPos})
MyBrowse.ResetFromBuffer !and reload the queue from that point
END
END

See Also: ViewManager.Reset, ResetQueue

178 ABC Library Reference

ResetFromFile (fill queue starting from file POSITION)

ResetFromFile, VIRTUAL
The ResetFromFile method fills or refills the browse queue starting from the current POSITION of the primary file. If no
POSITION has been established, ResetFromFile fills the browse queue starting from the beginning of the file.

Tip: Use ResetFromFile when the primary file position is valid but secondary records and their contents may
not be. For example, when returning from an update.

Implementation: ResetFromFile succeeds even if the record buffer is cleared and is typically used to get the current record
after an update.

Example:
MyBrowseClass.ResetFromAsk PROCEDURE(*BYTE Request,*BYTE Response)
CODE
IF Response = RequestCompleted
FLUSH(SELF.View)
IF Request = DeleteRecord
DELETE(SELF.ListQueue)
SELF.ResetQueue(Reset:Queue) !refill queue after delete
ELSE
SELF.ResetFromFile !refill queue after insert or change
END
ELSE
SELF.ResetQueue(Reset:Queue)
END
BrowseClass 179

ResetFromView (reset browse from current result set)

ResetFromView, VIRTUAL
The ResetFromView method resets the BrowseClass object to conform to the current result set.

Tip: Use ResetFromView when you want to reset for any changes that may have happened to the entire record
set, such as new records added or deleted by other workstations.

Implementation: The SetSort method calls the ResetFromView method.

The ResetFromView method readjusts the scrollbar thumb if necessary. The ABC Templates override the
BrowseClass.ResetFromView method to recalculate totals if needed.

Example:
BRW1.ResetFromView PROCEDURE
ForceRefresh:Cnt LONG
CODE
SETCURSOR(Cursor:Wait)
SELF.Reset
LOOP
CASE SELF.Next()
OF Level:Notify
BREAK
OF Level:Fatal
RETURN
END
SELF.SetQueueRecord
ForceRefresh:Cnt += 1
END
ForceRefresh = ForceRefresh:Cnt
SETCURSOR()
180 ABC Library Reference

ResetQueue (fill or refill queue)

ResetQueue( resetmode ), VIRTUAL

ResetQueue Fills or refills the browse queue.

resetmode A numeric constant, variable, EQUATE, or expression that determines how ResetQueue determines the
highlighted record after the reset. A value of Reset:Queue highlights the currently selected item. A value
of Reset:Done highlights a record based on the view's current position and other factors, such as the
RetainRow property.
The ResetQueue method fills or refills the browse queue and appropriately enables or disables Change, Delete, and
Select controls. The refill process depends on the value of the resetmode parameter and several other BrowseClass
properties, including ActiveInvisible, AllowUnfilled, RetainRow, etc.

A resetmode value of Reset:Queue usually produces a more efficient queue refill than Reset:Done.

Implementation: ResetQueue calls the Fetch method to fill the queue.

The resetmode EQUATEs are declared in ABBROWSE.INC as follows:

ITEMIZE,PRE(Reset)
Queue EQUATE
Done EQUATE
END

Example:
DeleteMyBrowse ROUTINE
!delete code
MyBrowse.ResetQueue(Reset:Queue) !after delete, refresh Q
MyBrowse.PostNewSelection !after delete, post a new selection event
!so window gets properly refreshed

See Also: ActiveInvisible, AllowUnfilled, RetainRow, ChangeControl, DeleteControl, SelectControl, Fetch

BrowseClass 181

ResetResets (copy the Reset fields)

ResetResets, PROTECTED
The ResetResets method copies the current values of the Reset fields so any subsequent changes in their contents can
be detected.

The AddResetField method adds an associated reset field for the sort order defined by the preceding call to
AddSortOrder. You may add multiple reset fields for each sort order with multiple calls to AddResetField.

Example:
MyBrowse.CheckReset PROCEDURE
IF NOT SELF.Sort.Resets.Equal() !if reset fields changed,
SELF.ResetQueue(Reset:Queue) !refresh Q
SELF.ResetResets !take a new copy of the reset field values
END

See Also: AddResetField

182 ABC Library Reference

ResetSort (apply sort order to browse)

ResetSort( force ), VIRTUAL, PROC

ResetSort Reapplies the active sort order to the browse list.

force A numeric constant, variable, EQUATE, or expression that indicates whether to reset the browse
conditionally or unconditionally. A value of one (1 or True) unconditionally resets the browse; a value of
zero (0 or False) only resets the brose as circumstances require (sort order changed, reset fields
changed, first loading, etc.).
The ResetSort method reapplies the active sort order to the browse list and returns one (1) if the sort order changed; it
returns zero (0) if the order did not change. Any range limits, locators, or reset fields associated with the sort order are
enabled.

Tip: Use ResetSort followed by UpdateWindow to refresh and redisplay your ABC BrowseBoxes. Or, use the
WindowManager.Reset method.

Implementation: The ResetSort method calls the SetSort method to applt the current sort order. The ABC Templates
override the ResetSort method to apply the sort order based on the selected tab.

Return Data Type: BYTE

Example:
BRW1.ResetSort FUNCTION(BYTE Force) !apply appropriate sort order

CODE
IF CHOICE(?CurrentTab) = 1 !If 1st tab selected
RETURN SELF.SetSort(1,Force) !apply first sort order
ELSE !otherwise
RETURN SELF.SetSort(2,Force) !apply second sort order
END

See Also: AddRange, AddResetField, AddSortOrder, Set Sort ,UpdateWindow

BrowseClass 183

ScrollEnd (scroll to first or last item)

ScrollEnd( scrollevent ), VIRTUAL, PROTECTED

ScrollEnd Scrolls to the first or last browse list item.

scrollevent A numeric constant, variable, EQUATE, or expression that indicates the requested scroll action. Valid
scroll actions for this method are scrolls to the top or bottom of the list.
The ScrollEnd method scrolls to the first or last browse list item.

Implementation: The BrowseClass.TakeScroll method calls the ScrollEnd method.

A hexadecimal scrollevent value of EVENT:ScrollTop scrolls to the first list item. A value of
EVENT:ScrollBottom scrolls to the last list item. Corresponding scroll event EQUATEs are declared in
EQUATES.CLW:
EVENT:ScrollTop EQUATE (07H)
EVENT:ScrollBottom EQUATE (08H)

Example:
BrowseClass.TakeScroll PROCEDURE( SIGNED Event )
CODE
IF RECORDS(SELF.ListQueue)
CASE Event
OF Event:ScrollUp OROF Event:ScrollDown
SELF.ScrollOne( Event )
OF Event:PageUp OROF Event:PageDown
SELF.ScrollPage( Event )
OF Event:ScrollTop OROF Event:ScrollBottom
SELF.ScrollEnd( Event )
END
END

See Also: TakeScroll

184 ABC Library Reference

ScrollOne (scroll up or down one item)

ScrollOne( scrollevent ), VIRTUAL, PROTECTED

ScrollOne Scrolls up or down one browse list item.

scrollevent A numeric constant, variable, EQUATE, or expression that indicates the requested scroll action. Valid
scroll actions for this method are scrolls up or down a single list item.
The ScrollOne method scrolls up or down one browse list item.

Implementation: The BrowseClass.TakeScroll method calls the ScrollOne method.

A hexadecimal scrollevent value of EVENT:ScrollUp scrolls up one list item. A value of

EVENT:ScrollDown scrolls down one list item. Corresponding scroll event EQUATEs are declared in
EQUATES.CLW:
EVENT:ScrollUp EQUATE (03H)
EVENT:ScrollDown EQUATE (04H)

Example:
BrowseClass.TakeScroll PROCEDURE( SIGNED Event )
CODE
IF RECORDS(SELF.ListQueue)
CASE Event
OF Event:ScrollUp OROF Event:ScrollDown
SELF.ScrollOne( Event )
OF Event:PageUp OROF Event:PageDown
SELF.ScrollPage( Event )
OF Event:ScrollTop OROF Event:ScrollBottom
SELF.ScrollEnd( Event )
END
END

See Also: TakeScroll

BrowseClass 185

ScrollPage (scroll up or down one page)

ScrollPage( scrollevent ), VIRTUAL, PROTECTED

ScrollPage Scrolls up or down one page of browse list items.

scrollevent A numeric constant, variable, EQUATE, or expression that indicates the requested scroll action. Valid
scroll actions for this method are scrolls up one page or down one page of browse list items.
The ScrollPage method scrolls up or down one page of browse list items.

Implementation: The BrowseClass.TakeScroll method calls the ScrollPage method.

A hexadecimal scrollevent value of EVENT:PageUp scrolls up one page of browse list items. A value of
EVENT:PageDown scrolls down one page of browse list items. Corresponding scroll event EQUATEs are
declared in EQUATES.CLW:
EVENT:PageUp EQUATE (05H)
EVENT:PageDown EQUATE (06H)

Example:
BrowseClass.TakeScroll PROCEDURE( SIGNED Event )
CODE
IF RECORDS(SELF.ListQueue)
CASE Event
OF Event:ScrollUp OROF Event:ScrollDown
SELF.ScrollOne( Event )
OF Event:PageUp OROF Event:PageDown
SELF.ScrollPage( Event )
OF Event:ScrollTop OROF Event:ScrollBottom
SELF.ScrollEnd( Event )
END
END

See Also: TakeScroll

186 ABC Library Reference

SetAlerts (alert keystrokes for list and locator controls)

SetAlerts, VIRTUAL
The SetAlerts method alerts standard keystrokes for the browse's list control and for any associated locator controls.

The BrowseClass.TakeKey method processes the alerted keystrokes.

Implementation: The BrowseClass.SetAlerts method alerts the mouse DOUBLE-CLICK, the INSERT, DELETE and
CTRL+ENTER keys for the browse's list control and calls the LocaorClass.SetAlerts method for each
associated locator control. Corresponding keycode EQUATEs are declared in KEYCODES.CLW.

The BrowseClass.SetAlerts method also sets up a popup menu for the browse list that mimics the
behavior of any control buttons (insert, change, delete, select).

Example:
PrepareStateBrowse ROUTINE !Setup the BrowseClass object:
BrowseState.Init(?StateList,| ! identify its LIST control,
StateQ.Position, | ! its VIEW position string,
StateView, | ! its source/target VIEW,
StateQ, | ! the LIST's source QUEUE,
Relate:State) ! and primary file RelationManager
BrowseState.SetAlerts !alert LIST and locator keystrokes

See Also: TakeKey

BrowseClass 187

SetLocatorField (set sort free element to passed field)

SetLocatorField (free), VIRTUAL

SetLocatorField Sets the sort free element to the passed field.

free An ANY data type, passed by address, that contains the free element that will be used as the
locator field.
The SetLocatorField method sets the specified locator sort to the browse list. The free element represents a potential
sort that has modified the default sort in the browse list. That element now can become the active locator.

Implementation: The BrowseClass.SetLocatorFromSort call the SetLocatorField method.

SetLocatorFromSort (use sort like locator field)

SetLocatorFromSort (free), VIRTUAL

SetLocatorFromSort Applies a specified locator to the browse list.

The SetLocatorFromSort method uses the first field of the sort as the locator field if there is a sort order active.

Implementation: None
188 ABC Library Reference

SetQueueRecord (copy data from file buffer to queue buffer:BrowseClass)

SetQueueRecord, VIRTUAL
The SetQueueRecord method copies corresponding data from the filefield fields to the queuefield fields specified by the
AddField method. Typically these are the file buffer fields and the browse list's queue buffer fields so that the queue buffer
matches the file buffers.

Implementation: The BrowseClass.Fetch and BrowseClass.Ask methods call the SetQueueRecord method.

Example:
MyBrowseClass.SetQueueRecord PROCEDURE
CODE
SELF.Fields.AssignLeftToRight !copy data from file to q buffer
SELF.ViewPosition = POSITION( SELF.View )!set the view position
!your custom code here

See Also: Ask, AddField, Fetch

BrowseClass 189

SetSort (apply a sort order to the browse)

SetSort( order, force reset ), VIRTUAL, PROC

SetSort Applies a specified sort order to the browse list.

order An integer constant, variable, EQUATE, or expression that specifies the sort order to apply.
force reset A numeric constant, variable, EQUATE, or expression that tells the method whether to reset the browse
conditionally or unconditionally. A value of zero (0 or False) resets the browse only if circumstances
require (sort order changed, reset fields changed, first time loading); a value of one (1 or True)
unconditionally resets the browse.
The SetSort method applies the specified sort order to the browse list and returns one (1) if the sort order changed; it
returns zero (0) if the sort order did not change. Any range limits, locators, and reset fields associated with the sort order
are enabled and applied.

The order value is typically a value returned by the AddSortOrder method which identifies the particular sort order. Since
AddSortOrder returns sequence numbers, a value of one (1) applies the sort order specified by the first call to
AddSortOrder; two (2) applies the sort order specified by the next call to AddSortOrder; etc. A value of zero (0) applies the
default sort order.

Implementation: The ResetSort method calls the SetSort method.

Return Data Type: BYTE

Example:
IF FIELD() = ?FirstTab !if first tab selected
IF MyBrowse.SetSort(1,0) !apply the first sort order
MyBrowse.ResetThumbLimits !if sort changed, reset thumb limits
END
MyBrowse.UpdateBuffer !update file buffer from selected item
END

See Also: AddRange, AddResetField, AddSortOrder, ResetSort

190 ABC Library Reference

TakeAcceptedLocator (apply an accepted locator value)

TakeAcceptedLocator, VIRTUAL
The TakeAcceptedLocator method applies an accepted locator value to the browse list--the BrowseClass object scrolls
the list to the requested item.

Locators with entry controls are the only locators whose values are accepted. Other types of locators are invoked in other
ways, for example, with alerted keys. Locator values are accepted whenthe end user TABS off or otherwise switches
focus away from the locator's entry control.

The AddLocator method establishes locators for the browse.

Implementation: The TakeAcceptedLocator method calls the appropriate LocatorClass.TakeAccepted method.

Example:
IF FIELD() = ?MyLocator !focus on locator field
IF EVENT() = EVENT:Accepted !if accepted
MyBrowse.TakeAcceptedLocator !BrowseClass object handles it
END
END
See Also: AddLocator
BrowseClass 191

TakeEvent (process the current ACCEPT loop event:BrowseClass)

TakeEvent, VIRTUAL
The TakeEvent method processes the current ACCEPT loop event for the BrowseClass object. The TakeEvent method
handles all events associated with the browse list except a new selection event. The TakeNewSelection method handles
new selection events for the browse.

Implementation: The WindowManager.TakeEvent method calls the TakeEvent method. The TakeEvent method calls the
TakeScroll or TakeKey method as appropriate.
Example:
MyWindowManager.TakeEvent PROCEDURE
RVal BYTE(Level:Benign)
I USHORT,AUTO
CODE
!procedure code
LOOP I = 1 TO RECORDS(SELF.Browses)
GET(SELF.Browses,I)
SELF.Browses.Browse.TakeEvent
END
LOOP i=1 TO RECORDS(SELF.FileDrops)
GET(SELF.FileDrops,i)
ASSERT(~ERRORCODE())
SELF.FileDrops.FileDrop.TakeEvent
END
RETURN RVal

See Also: TakeKey, TakeNewSelection, TakeScroll, WindowManager.TakeEvent

192 ABC Library Reference

TakeKey (process an alerted keystroke:BrowseClass)

TakeKey, VIRTUAL, PROC

The TakeKey method processes an alerted keystroke for the BrowseClass object, including DOUBLE-CLICK, INSERT,
CTRLENTER, or DELETE, and returns a value indicating whether any action was taken.

Implementation: TakeKey returns one (1) if any action is taken, otherwise it returns zero (0).

The TakeEvent method calls the TakeKey method as appropriate. The BrowseClass.TakeKey method
calls the Locator.TakeKey method as appropriate.

Return Data Type: BYTE

Example:
IF FIELD() = ?MyBrowseList !focus on browse list
IF EVENT() EVENT:AlertKey !if alerted keystroke
MyBrowse.TakeKey !BrowseClass object handles it
END
END

See Also: TakeEvent

BrowseClass 193

TakeNewSelection (process a new selection:BrowseClass)

TakeNewSelection, VIRTUAL, PROC

The TakeNewSelection method processes a new browse list item selection and returns a value indicating whether a
window redraw is needed.

Implementation: TakeNewSelection returns one (1) if a window redraw is needed, otherwise it returns zero (0).

The TakeEvent method calls the TakeNewSelection method when appropriate. The
BrowseClass.TakeNewSelection method calls the appropriate Locator.TakeNewSelection method.

Return Data Type: BYTE

Example:
IF FIELD() = ?MyBrowse !focus on browse list
IF EVENT() = EVENT:NewSelection !if new selection
MyBrowse.TakeNewSelection() !BrowseClass object handles it
ELSE !if other event
MyBrowse.TakeEvent !BrowseClass object handles it
END
END
194 ABC Library Reference

TakeScroll (process a scroll event)

TakeScroll( [scrollevent] ), VIRTUAL

TakeScroll Processes a scroll event for the browse list.

scrollevent An integer constant, variable, EQUATE, or expression that specifies the scroll event. Valid scroll events
are up one item, down one item, up one page, down one page, up to the first item, and down to the last
item. If omitted, no scrolling occurs.
The TakeScroll method processes a scroll event for the browse list.

Implementation: A scrollevent value of EVENT:ScrollUp scrolls up one item; EVENT:ScrollDown scrolls down one item;
EVENT:PageUp scrolls up one page; EVENT:PageDown scrolls down one page; EVENT:ScrollTop
scrolls to the first list item; EVENT:ScrollBottom scrolls to the last list item. Corresponding scrollevent
EQUATEs are declared in EQUATES.CLW.
EVENT:ScrollUp EQUATE (03H)
EVENT:ScrollDown EQUATE (04H)
EVENT:PageUp EQUATE (05H)
EVENT:PageDown EQUATE (06H)
EVENT:ScrollTop EQUATE (07H)
EVENT:ScrollBottom EQUATE (08H)

The TakeScroll method calls the ScrollEnd, ScrollOne, or ScrollPage method as needed.

Example:
IF FIELD() = ?MyBrowse !focus on browse list
CASE EVENT() !scroll event
OF EVENT:ScrollUp
OROF EVENT:ScrollDown
OROF EVENT:PageUp
OROF EVENT:PageDown
OROF EVENT:ScrollTop
OROF EVENT:ScrollBottom
MyBrowse.TakeScroll !BrowseClass object handles it
END
END

See Also: ScrollEnd, ScrollOne, ScrollPage

BrowseClass 195

TakeVCRScroll (process a VCR scroll event)

TakeVCRScroll( [vcrevent] ), VIRTUAL

TakeVCRScroll Processes a VCR scroll event for the browse list.

vcrevent An integer constant, variable, EQUATE, or expression that specifies the scroll event. Valid scroll events
are up one item, down one item, up one page, down one page, up to the first item, and down to the last
item. If omitted, no scrolling occurs.
The TakeVCRSroll method processes a VCR scroll event for the browse

Implementation: A vcrevent value of VCR:Forward scrolls down one item; VCR:Backward scrolls up one item;
VCR:PageForward scrolls down one page; VCR:PageBackward scrolls up one page; VCR:Last scrolls to
the last list item; VCR:First scrolls to the first list item. Corresponding vcrevent EQUATEs are declared in
\LIBSRC\ABTOOLBA.INC.
ITEMIZE,PRE(VCR)
Forward EQUATE(Toolbar:Down)
Backward EQUATE(Toolbar:Up)
PageForward EQUATE(Toolbar:PageDown)
PageBackward EQUATE(Toolbar:PageUp)
First EQUATE(Toolbar:Top)
Last EQUATE(Toolbar:Bottom)
Insert EQUATE(Toolbar:Insert)
None EQUATE(0)
END

The TakeVCRScroll method calls the TakeScroll method, translating the vcrevent to the appropriate
scrollevent.

Example:
LOOP !process repeated scroll events
IF VCRRequest = VCR:None !if no more events
BREAK !break out of loop
ELSE !if scroll event
MyBrowse.TakeVCRScroll( VCRRequest ) !BrowseClass object handles it
END
END

See Also: TakeScroll

196 ABC Library Reference

UpdateBuffer (copy selected item from queue buffer to file buffer)

UpdateBuffer, VIRTUAL
The UpdateBuffer method copies corresponding data from the queuefield fields to the filefield fields specified by the
AddField method for the currently selected browse item. Typically these are the browse list's queue buffer fields and the
file buffer fields so that the file buffers match the currently selected browse list item.

Implementation: Many of the BrowseClass methods call the UpdateBuffer method.

Example:
IF FIELD() = ?FirstTab !if first tab selected
IF MyBrowse.SetSort(1,0) !apply the first sort order
MyBrowse.ResetThumbLimits !if sort changed, reset thumb limits
END
MyBrowse.UpdateBuffer !update file buffer from selected item
MyBrowse.UpdateResets !update file buffer from reset fields
END

See Also: AddField

BrowseClass 197

UpdateQuery (set default query interface)

UpdateQuery( querymanager, [casesensitive])

UpdateQuery Defines a default query interface for the BrowseClass object.

querymanager The label of the BrowseClass object's QueryClass object. See QueryClass for more information.
casesensitive A numeric constant, variable, EQUATE, or expression that indicates the case sensitivity of the query
expression. If this parameter is omitted the query is case insensitive.
The UpdateQuery method defines a default query interface (dialog) for the BrowseClass object.

Tip: You may use the UpdateQuery method in combination with the QueryClass.AddItem method to define a
query interface that contains the displayed fields plus other queryable items.

Implementation: The UpdateQuery method sets the value of the Query property, then calls the QueryClass.AddItem
method for each displayed field, so that each displayed field accepts filter criteria in the query dialog.

Example:
QueryForm QueryFormClass
QueryVis QueryFormVisual
BRW1 CLASS(BrowseClass)
Q &CusQ
END

CusWindow.Init PROCEDURE()
CODE
!open files, views, window, etc.
IF DefaultQuery
BRW1.UpdateQuery(QueryForm)
ELSE
BRW1.Query &= QueryForm
QueryForm.AddItem('UPPER(CUS:NAME)','','')
QueryForm.AddItem('UPPER(CUS:CITY)','','')
QueryForm.AddItem('CUS:ZIP_CODE','','')
END
RETURN Level:Benign

See Also: Query, QueryClass.AddItem

198 ABC Library Reference

UpdateResets (copy reset fields to file buffer)

UpdateResets, PROTECTED
The UpdateResets method copies reset field values to corresponding file buffer fields.

The AddResetField method defines the reset fields for the BrowseClass object.

Implementation: The BrowseClass.Next an BrowseClass.Previous methods call the UpdateResets method.

Example:
MyBrowseClass.Next PROCEDURE !method of class derived from BrowseClass
CODE
IF Level:Fatal = PARENT.Next() !do parent method
POST(EVENT:CloseWindow) !if fails, shut down
ELSE !otherwise
SELF.UpdateResets !update file buffer from reset fields
END

See Also: AddResetField, Next, Previous

BrowseClass 199

UpdateThumb (position the scrollbar thumb)

UpdateThumb
The UpdateThumb method positions the scrollbar thumb and enables or disables the vertical scroll bar depending on the
number of items in the browse list, the currently selected item, and the active step distribution method. See Control
Templates--BrowseBox for more information on thumb behavior.

Implementation: The AddSortOrder method sets the stepdistribution methods for the BrowseClass object.

Example:
IF FIELD() = ?MyBrowse !focus on browse list
IF EVENT() = EVENT:NewSelection !if new selection
IF MyBrowse.TakeNewSelection() !BrowseClass object handles it
MyBrowse.UdateThumb !Reposition the thumb
END
END
END
200 ABC Library Reference

UpdateThumbFixed (position the scrollbar fixed thumb)

UpdateThumbFixed, PROTECTED
The UpdateThumbFixed method positions the scrollbar fixed thumb and enables or disables the vertical scroll bar
depending on the number of items in the browse list, the currently selected item, and the active step distribution method.
See Control Templates--BrowseBox for more information on fixed thumb behavior.

Implementation: The AddSortOrder method sets the step distribution methods for the BrowseClass object.

Example:
MyBrowseClass.UpdateThumb PROCEDURE
CODE
IF SELF.Sort.Thumb &= NULL !if no step object
SELF.UpdateThumbFixed !reposition thumb as fixed
ELSE
!reposition thumb per step object
END
BrowseClass 201

UpdateViewRecord (get view data for the selected item)

UpdateViewRecord, VIRTUAL
The UpdateViewRecord method regets the browse's VIEW record for the selected browse list item so the VIEW record
can be written to disk. The UpdateViewRecord method arms automatic optimistic concurrency checking so the eventual
write (PUT) to disk returns an error if another user changed the data since it was retrieved by UpdateViewRecord.

Imlementation: The UpdateViewRecord method uses WATCH and REGET to implement optimistic concurrency
checking; see the Language Reference for more information.

Example:
IF FIELD() = ?ChangeButton !on change button
IF EVENT() = EVENT:Accepted !if button clicked
MyBrowse.UpdateViewRecord !refresh buffers and arm WATCH
DO MyBrowse:ButtonChange !call the update routine
END
END
202 ABC Library Reference

UpdateWindow (update display variables to match browse)

UpdateWindow, VIRTUAL
The UpdateWindow method updates display variables to match the current state of the browse list.

Tip: Use ResetSort followed by UpdateWindow to refresh and redisplay your ABC BrowseBoxes. Or, use the
WindowManager.Reset method.

Implementation: The BrowseClass.UpdateWindow method calls the appropriate LocatorClass.UpdateWindow method,

which ensures the locator field contains the current search value.

Example:
IF FIELD() = ?MyBrowse !focus on browse list
IF EVENT) = EVENT:NewSelection !if new selection
IF MyBrowse.TakeNewSelection() !BrowseClass object handles it
MyBrowse.SetSort(0,1) !reapply sort order
MyBrowse.UpdateBuffer !refresh file buffer from selected item
MyBrowse.UpdateWindow !update display variables (locator)
DISPLAY() !and redraw the window
END
END
END
BrowseClass 203
204 ABC Library Reference

BrowseQueue Interface
BrowseQueue Concepts
The BrowseQueue interface is a defined set of behaviors that relate to the VIEW and QUEUE that the LIST control uses.

Relationship to Other Application Builder Classes

The StandardBehavior class implements the BrowseQueue interface. For more information, see the StandardBehavior
class.

BrowseQueue Source Files

The BrowseQueue source code is installed by default to the Clarion \LIBSRC folder. The specific BrowseQueue source
code and their respective components are contained in:

ABBROWSE.INC BrowseQueue interface declaration

ABBROWSE.CLW BrowseQueue method definitions
BrowseQueue Interface 205

BrowseQueue Methods

Delete(remove entry in LIST queue)

Delete
TheDelete method removes an entry in the queue that the LIST control is using.

Fetch(retrieve entry from LIST queue)

Fetch(position)

Fetch Retrieves an entry from the queue for the LIST control.
position An integer constant, variable, EQUATE, or expression that indicates the relative
position in the queue for the LIST.
The Fetch method retrieves an entry from the queue that the LIST control is using at the relative position specified.

Free(clear contents of LIST queue)

Free
The Free method clears all entries from the queue that the LIST control is using.

GetViewPosition(retrieve VIEW position)

GetViewPosition
The GetViewPosition method retrieves the VIEW's POSITION.

Return Data Type: STRING

Insert(add entry to LIST queue)

Insert([position])

Insert Adds an entry to the queue for the LIST control.

position An integer constant, variable, EQUATE, or expression that indicates the relative
position in the queue for the LIST.
The Insert method adds an entry to the queue that the LIST control is using. If no position parameter is used, the entry is
added to the end of the queue. If the position parameter is used, the entry is added at the relative position specified. If an
entry exists at that position, it is moved down to make room for the new entry.
206 ABC Library Reference

Records(return number of records)

Records
The Records method returns the number of records available in the queue for the LIST control.

Return Data Type: UNSIGNED

SetViewPosition(set VIEW position)

SetViewPosition(position)

SetViewPosition Sets the POSITION of the VIEW.

position A string constant, variable, EQUATE, or expression containing the POSITION to
set in the VIEW.
The SetViewPosition sets the POSITION of the VIEW based on the position parameter.

Update(update entry in LIST queue)

Update
The Update method updates an entry in the queue that the LIST control is using.

Who(returns field name)

Who(column)

Who Returns the queue field name for the specified column.
column An integer constant, variable, EQUATE, or expression that contains a column
number from the queue.
The Who method returns the queue field name for the column specified by the column parameter.

Return Data Type: STRING

BrowseQueue Interface 207
208 ABC Library Reference

BrowseToolbarClass
BrowseToolbarClass Overview
The BrowseToolbarClass handles events for specialized buttons for scrolling in the associated BrowseBox. This class
works with the BrowseClass and the WindowManager objects to accomplish these tasks.

BrowseToolbarClass Concepts
The BrowseToolbarClass object interacts with the BrowseClass and WindowManager to allow the toolbar buttons to scroll
the browse highlight bar within the BrowseBox. When a toolbar button is pressed and EVENT:Accepted is posted to the
associated Browse control.

Relationship to Other Application Builder Classes

The BrowseToolbarClass works with the BrowseClass and WindowManager to accomplish its tasks.

BrowseToolbarClass ABC Template Implementation

The BrowseToolbarControl control template generates code to declare a BrowseToolbarClass object in the Browse
procedure that the control template is placed. The templates also generate code to register the BrowseToolbarClass
object with the BrowseClass and WindowManager objects, as well as initializing all toolbar button controls.

BrowseToolbarClass Source Files

The BrowseToolbarClass source code is installed by default to the Clarion \LIBSRC folder. The specific
BrowseToolbarClass source code and their respective components are contained in:

ABTOOLBA.INC BrowseToolbarClass declarations

ABTOOLBA.CLW BrowseToolbarClass method definitions
BrowseToolbarClass 209

BrowseToolbarClass Properties

Browse (BrowseClass object)

Browse &BrowseClass, PROTIECTED

The Browse property is a reference to the BrowseClass object. The BrowseToolbarClass object uses this property to
access the BrowseClass object's properties and methods.

Implementation: The BrowseToolbarClass.Init method sets the value of the Browse property.

See Also: BrowseToolbarClass.Init

Button (toolbar buttons FEQ values)

Button SIGNED, DIM(Toolbar:Last+1-Toolbar:First), PROTECTED

The Button property is a dimensioned variable that holds the contol numbers (FEQ) of the buttons that are represented
on the toolbar. A value of zero (0) disables the individual toolbar button

Implementation: The BrowseToolbarClass object uses this property to enable or disable a toolbar control.

Window (WindowManager object)

Window &WindowManager, PROTECTED

The Window property is a reference to the WindowManager object for this BrowseToolbarClass object. The
WindowManager object forwards events to the BrowseToolbarClass object for processing.

Implementation: The BrowseToolbarClass.Init method sets the value of the Window property.

See Also: BrowseToolbarClass.Init

210 ABC Library Reference

BrowseToolbarClass Methods

Init (initialize the BrowseToolbarClass object)

Init(WindowManager, BrowseClass)

Init Initializes the BrowseToolbarClass object.

WindowManager The label of the toolbar's WindowManager object. See Window Manager for
more information.
BrowseClass The label of the toolbar's BrowseClass object. See BrowseClass for more
information.
The Init method initializes the BrowseToolbarClass object by declaring a reference to both the WindowManager and
BrowseClass objects. All toolbar buttons are initialized to zero (0).

InitBrowse (initialize the BrowseToolbarClass update buttons)

InitBrowse(insert, change, delete, select)

InitBrowse Initializes the BrowseToolbarClass update buttons.

insert An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Insert control.
change An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Change control.
delete An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Delete control.
select An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Select control.
The InitBrowse method initializes the Button property with the control numbers (FEQ) for the update controls on the
toolbar.

Inplementation: This method is called automatically by the ABC BrowseToolbarControl template.

BrowseToolbarClass 211

InitMisc (initialize the BrowseToolbarClass miscellaneous buttons)

InitMisc(history, help)

InitMisc Initializes the BrowseToolbarClass miscellaneous buttons.

history An integer constant, variable, EQUATE, or expression that identifies the FEQ for
the History control.
help An integer constant, variable, EQUATE, or expression that identifies the FEQ for
the Help control.
The InitMisc method initializes the Button property with the control numbers (FEQ) for the History and Help controls on
the toolbar.

Inplementation: This method is called automatically by the ABC BrowseToolbarControl template.

212 ABC Library Reference

InitVCR (initialize the BrowseToolbarClass VCR buttons)

InitVCR(top, bottom, pageup, pagedown, up, down, locate)

InitVCR Initializes the BrowseToolbarClass VCR buttons.

top An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Top control.
bottom An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Bottom control.
pageup An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
PageUp control.
pagedown An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
PageDown control.
up An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Up control.
down An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Down control.
locate An integer constant, variable, EQUATE, or expression that identifies the FEQ for the
Locate control.
The InitVCR method initializes the Button property with the control numbers (FEQ) for the VCR controls on the toolbar.

Inplementation: This method is called automatically by the ABC BrowseToolbarControl template.

BrowseToolbarClass 213

ResetButton (synchronize toolbar with a corresponding browse control)

ResetButton(toolbutton, browsebutton), PROTECTED

ResetButton Sync Toolbar control properties with its corresponding Browse control.
toolbutton An integer constant, variable, EQUATE, or expression that identifies a particular
toolbar control.
browsebutton An integer constant, variable, EQUATE, or expression that identifies a specific
browse control.
The ResetButton method enables/disables, hides/unhides a toolbar control based on the current properties of its
corresponding browse control.

There are predefined equates that represent each button available on the toolbar. These equates can be found at the top
of ABTOOLBA.INC.

Inplementation: This method is called by the BrowseToolBarClass.ResetFromBrowse method.

214 ABC Library Reference

ResetFromBrowse(synchronize toolbar controls with browse controls)

ResetFromBrowse, VIRTUAL
The ResetFromBrowse method synchronizes the toolbar controls with their corresponding brrowse control. These
controls include the Select, Insert, Change, Delete, History, Help and Locate buttons.

Inplementation: This method is called from the BrowseToolBarClass.TakeEvent method.

TakeEvent(process the current event)

TakeEvent, VIRTUAL
The TakeEvent method processes all accepted events for the toolbar controls. When an accepted event occurs, an
EVENT:Accepted is posted to the corresponding Browse control. When a NewSelection event occurs on the BrowseBox,
the ResetFromBrowse method is called to redisplay the toolbar controls with the correct properties (hide, unhide, enable,
disable).

A Level:Benign is returned from this method.

Return Data Type: BYTE

BrowseToolbarClass 215
216 ABC Library Reference

BufferedPairsClass
BufferedPairsClass Overview
The BufferedPairsClass is a FieldPairs class with a third buffer area (a "save" area). The BufferedPairsClass can compare
the save area with the primary buffers, and can restore data from the save area to the primary buffers (to implement a
standard "cancel" operation).

BufferedPairsClass Concepts

The BufferedPairsClass lets you move data between field pairs, and lets you compare the field pairs to detect whether
any changes occurred since the last operation.

This class provides methods that let you identify or "set up" the targeted field pairs.

Note: The paired fields need not be contiguous in memory, nor do they need to be part of a structure. You can
build a virtual structure simply by adding a series of otherwise unrelated fields to a BufferedPairsClass
object. The BufferedPairsClass methods then operate on this virtual structure.

Once the field pairs are identified, you call a single method to move all the fields in one direction (left to right), and others
single methods to move all the fields in the other directions (right to left, left to buffer, etc.). You simply have to remember
which entity (set of fields) you described as "left" and which entity you described as "right." Other methods compares the
sets of fields and return a value to indicate whether or not they are equivalent.

BufferedPairsClass Relationship to Other Application Builder Classes

The BufferedPairsClass is derived from the FieldPairsClass. The BrowseClass, ViewManager, and RelationManager use
the FieldPairsClass and BufferedPairsClass to accomplish various tasks.

BufferedPairsClass ABC Template Implementation

Various ABC Library objects instantiate BufferedPairsClass objects as needed; therefore, the template generated code
does not directly reference the BufferedPairsClass.

BufferedPairsClass Source Files

The BufferedPairsClass source code is installed in the Clarion \LIBSRC folder. The BufferedPairsClass source code and
their respective components are contained in:

ABUTIL.INC BufferedPairsClass declarations

ABUTIL.CLW BufferedPairsClass method definitions
BufferedPairsClass 217

BufferedPairsClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a
BufferedPairsClass object.

Let's assume you have a Customer file declared as:

Customer FILE,DRIVER('TOPSPEED'),PRE(CUST),CREATE,BINDABLE
ByNumber KEY(CUST:CustNo),NOCASE,OPT,PRIMARY
Record RECORD,PRE()
CustNo LONG
Name STRING(30)
Phone STRING(20)
Zip DECIMAL(5)
END
END

And you have a Customer queue declared as:

CustQ QUEUE
CustNo LONG
Name STRING(30)
Phone STRING(20)
Zip DECIMAL(5)
END

And you want to move data between the file buffer and the queue buffer.
INCLUDE('ABUTIL.INC') !declare BufferedPairsClass
Fields BufferedPairsClass !declare Fields object

CODE
Fields.Init !initialize Fields object
Fields.AddPair(CUST:CustNo, CustQ.CustNo) !establish CustNo pair
Fields.AddPair(CUST:Name, CustQ.Name) !establish Name pair
Fields.AddPair(CUST:Phone, CustQ.Phone) !establish Phone pair
Fields.AddPair(CUST:Zip, CustQ.Zip) !establish Zip pair

Fields.AssignLeftToRight !copy from Customer FILE to CustQ QUEUE

Fields.AssignLeftToBuffer !copy from Customer FILE to save area
!accept user input
IF ACCEPTED() = ?RestoreButton
Fields.AssignBufferToLeft !copy from save area to Customer FILE
Fields.AssignBufferToRight !copy from save area to Customer QUEUE
END

Fields.Kill !shut down Fields object

218 ABC Library Reference

BufferedPairsClass Properties
BufferedPairsClass Properties
The BufferedPairsClass inherits the properties of the FieldPairsClass from which it is derived. See FieldPairsClass
Properties for more information.

In addition to (or instead of) the inherited properties, the BufferedPairsClass contains the RealList property.

RealList (recognized field pairs)

RealList &FieldPairsQueue
The RealList property is a reference to the structure that holds all the field pairs recognized by the BufferedPairsClass
object.

Use the AddPair method to add field pairs to the RealList property. For each field pair, the RealList property includes the
designated "Left" field, the designated "Right" field, plus a "Buffer" field you can use as an intermediate storage area (a
save area).

The "Left," "Right," and "Buffer" designations are reflected in other BufferedPairsClass method names (for example, field
assignment methods--AssignLeftToRight and AssignRightToBuffer) so you can easily and accurately control the
movement of data between the three sets of fields.

Implementation: During initialization, the BufferedPairsClass initialization method "points" the inherited List property to the
RealList property so there is, in fact, only one list of fields which may be referred to as RealList.

RealList is a reference to a QUEUE declared in ABUTIL.INC as follows:

BufferedPairsQueue QUEUE,TYPE
Left ANY
Right ANY
Buffer ANY
END

The Init method creates the List and RealList properties; the Kill method disposes of them. AddPair adds field pairs to the
RealList property.

See Also: AddPair, Init, Kill

BufferedPairsClass 219

BufferedPairsClass Methods
BufferedPairsClass Methods
The BufferedPairsClass inherits all the methods of the FieldPairsClass from which it is derived. See FieldPairsClass
Methods for more information.

In addition to (or instead of) the inherited methods, the BufferedPairsClass contains other methods listed below.

BufferedPairsClass Functional Organization

Expected Use
As an aid to understanding the BufferedPairsClass, it is useful to organize its methods into two large categories according
to their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the BufferedPairsClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

Init initialize the BufferedPairsClass object
AddPairV add a field pair to the List property
Kill shut down the BufferedPairsClass object

V These methods are also Virtual.

Occasional Use:
AssignLeftToRight assign each "left" field to its "right" counterpart
AssignLeftToBuffer assign each "left" field to its "buffer" counterpart
AssignRightToLeft assign each "right" field to its "left" counterpart
AssignRightToBuffer assign each "right" field to its "buffer" counterpart
AssignBufferToLeft assign each "buffer" field to its "left" counterpart
AssignBufferToRight assign each "buffer" field to its "right" counterpart
EqualLeftRight return 1 if each left equal right, otherwise return 0
EqualLeftBuffer return 1 if each left equal buffer, otherwise return 0
EqualRightBuffer return 1 if right equal buffer, otherwise return 0
ClearLeft CLEAR each "left" field
ClearRight CLEAR each "right" field
220 ABC Library Reference

Inappropriate Use:

These methods are inherited from the FieldPairsClass and typically are not used in the context of this
(BufferedPairsClass) derived class.

AddItem add a field pair from one source field

Equal return 1 if each left equal right, otherwise return 0

Virtual Methods

Typically you will not call these methods directly. However, we anticipate you will often want to override these methods,
and because they are virtual, they are very easy to override. These methods do provide reasonable default behavior in
case you do not want to override them.
BufferedPairsClass 221

AddPair (add a field pair:BufferedPairsClass)

AddPair( left, right ), VIRTUAL

AddPair Adds a field pair to the RealList property.

left The label of the "left" field of the pair. The field may be any data type, but may not be an array.
right The label of the "right" field of the pair. The field may be any data type, but may not be an array.
The AddPair method adds a field pair to the RealList property. A third "buffer" field is supplied for you. You may use this
third "buffer" as an intermediate storage area (a save area).

The fields need not be contiguous in memory, nor do they need to be part of a structure. Therefore you can build a virtual
structure simply by adding a series of otherwise unrelated fields to a BufferedPairs object. The other BufferedPairs
methods then operate on this virtual structure.

Implementation: AddPair assumes the RealList property has already been created by Init or by some other method.

By calling AddPair for a series of fields (for example, the corresponding fields in a RECORD and a QUEUE), you
effectively build three virtual structures containing the fields and a (one-to-one-to-one) relationship between the structures.

Example:
INCLUDE('ABUTIL.INC') !declare BufferedPairs Class
Fields &BufferedPairsClass !declare BufferedPairs reference

Customer FILE,DRIVER('TOPSPEED'),PRE(CUST),CREATE,BINDABLE
ByNumber KEY(CUST:CustNo),NOCASE,OPT,PRIMARY
Record RECORD,PRE()
CustNo LONG
Name STRING(30)
Phone STRING(20)
END
END

CustQ QUEUE
CustNo LONG
Name STRING(30)
Phone STRING(20)
END

CODE
Fields &= NEW BufferedPairsClass !instantiate BufferedPairs object
Fields.Init !initialize BufferedPairs object
Fields.AddPair(CUST:CustNo, CustQ.CustNo) !establish CustNo pair
Fields.AddPair(CUST:Name, CustQ.Name) !establish Name pair
Fields.AddPair(CUST:Phone, CustQ.Phone) !establish Phone pair

See Also: Init, RealList

222 ABC Library Reference

AssignBufferToLeft (copy from "buffer" fields to "left" fields)

AssignBufferToLeft
The AssignBufferToLeft method copies the contents of each "buffer" field to its corresponding "left" field in the RealList
property.

Implementation: The "left" field is the first (left) parameter of the AddPair method. The "right" field is the second (right)
parameter of the AddPair method. The BufferedPairsClass automatically supplies the "buffer" field.

Example:
Fields.AddPair(CUST:Name, CustQ.Name) !establish Name pair
Fields.AddPair(CUST:Phone, CustQ.Phone) !establish Phone pair
Fields.AddPair(CUST:ZIP, CustQ.ZIP) !establish ZIP pair
!some code
IF ~Fields.EqualRightBuffer !compare QUEUE fields to save buffer
CASE MESSAGE('Abandon Changes?',,,BUTTON:Yes+BUTTON:No)
OF BUTTON:No
Fields.AssignRightToLeft !copy changes to CUST (write) buffer
OF BUTTON:Yes
Fields.AssignBufferToLeft !restore original to CustQ (display) buffer
END
END

See Also: AddPair, RealList

BufferedPairsClass 223

AssignBufferToRight (copy from "buffer" fields to "right" fields)

AssignBufferToRight
The AssignBufferToRight method copies the contents of each "buffer" field to its corresponding "right" field in the
RealList property.

Implementation: The "left" field is the first (left) parameter of the AddPair method. The "right" field is the second (right)
parameter of the AddPair method. The BufferedPairsClass automatically supplies the "buffer" field.

Example:
Fields.AddPair(CUST:Name, CustQ.Name) !establish Name pair
Fields.AddPair(CUST:Phone, CustQ.Phone) !establish Phone pair
Fields.AddPair(CUST:ZIP, CustQ.ZIP) !establish ZIP pair
!some code
IF ~Fields.EqualRightBuffer !compare QUEUE fields to save buffer
CASE MESSAGE('Abandon Changes?',,,BUTTON:Yes+BUTTON:No)
OF BUTTON:No
Fields.AssignRightToBuffer
OF BUTTON:Yes
Fields.AssignBufferToRight
END
END

See Also: AddPair, RealList

224 ABC Library Reference

AssignLeftToBuffer (copy from "left" fields to "buffer" fields)

AssignLeftToBuffer
The AssignLeftToBuffer method copies the contents of each "left" field to its corresponding "buffer" field in the RealList
property.

Implementation: The "left" field is the first (left) parameter of the AddPair method. The "right" field is the second (right)
parameter of the AddPair method. The BufferedPairsClass automatically supplies the "buffer" field.

Example:
Fields.AddPair(CUST:Name, CustQ.Name) !establish Name pair
Fields.AddPair(CUST:Phone, CustQ.Phone) !establish Phone pair
Fields.AddPair(CUST:ZIP, CustQ.ZIP) !establish ZIP pair
!some code
IF ~Fields.EqualRightBuffer !compare QUEUE fields to save buffer
CASE MESSAGE('Abandon Changes?',,,BUTTON:Yes+BUTTON:No)
OF BUTTON:No
Fields.AssignRightToLeft
OF BUTTON:Yes
Fields.AssignLeftToBuffer
END
END

See Also: AddPair, RealList

BufferedPairsClass 225

AssignRightToBuffer (copy from "right" fields to "buffer" fields)

AssignRightToBuffer
The AssignRightToBuffer method copies the contents of each "right" field to its corresponding "buffer" field in the
RealList property.

Implementation: The "left" field is the first (left) parameter of the AddPair method. The "right" field is the second (right)
parameter of the AddPair method. The BufferedPairsClass automatically supplies the "buffer" field.

Example:
Fields.AddPair(CUST:Name, CustQ.Name) !establish Name pair
Fields.AddPair(CUST:Phone, CustQ.Phone) !establish Phone pair
Fields.AddPair(CUST:ZIP, CustQ.ZIP) !establish ZIP pair
!some code
IF ~Fields.EqualRightBuffer !compare QUEUE fields to save buffer
CASE MESSAGE('Abandon Changes?',,,BUTTON:Yes+BUTTON:No)
OF BUTTON:No
Fields.AssignRightToBuffer
OF BUTTON:Yes
Fields.AssignBufferToRight
END
END

See Also: AddPair, RealList

226 ABC Library Reference

EqualLeftBuffer (compare "left" fields to "buffer" fields)

EqualLeftBuffer
The EqualLeftBuffer method returns one (1) if each "left" field equals its corresponding "buffer" field; otherwise it returns
zero (0).

Implementation: The "left" field is the first (left) parameter of the AddPair method. The "right" field is the second (right)
parameter of the AddPair method. The BufferedPairsClass automatically supplies the "buffer" field.

Example:
Fields.AddPair(CUST:Name, CustQ.Name) !establish Name pair
Fields.AddPair(CUST:Phone, CustQ.Phone) !establish Phone pair
Fields.AddPair(CUST:ZIP, CustQ.ZIP) !establish ZIP pair
!some code
IF ~Fields.EqualLeftBuffer !compare CUST fields to save buffer
CASE MESSAGE('Abandon Changes?',,,BUTTON:Yes+BUTTON:No)
OF BUTTON:No
Fields.AssignRightToLeft !copy changes to CUST (write) buffer
OF BUTTON:Yes
Fields.AssignBufferToLeft !restore original to CustQ (display) buffer
END
END

See Also: AddPair, RealList

BufferedPairsClass 227

EqualRightBuffer (compare "right" fields to "buffer" fields)

EqualRightBuffer
The EqualRightBuffer method returns one (1) if each "right" field equals its corresponding "buffer" field; otherwise it
returns zero (0).

Implementation: The "left" field is the first (left) parameter of the AddPair method. The "right" field is the second (right)
parameter of the AddPair method. The BufferedPairsClass automatically supplies the "buffer" field.

Example:
Fields.AddPair(CUST:Name, CustQ.Name) !establish Name pair
Fields.AddPair(CUST:Phone, CustQ.Phone) !establish Phone pair
Fields.AddPair(CUST:ZIP, CustQ.ZIP) !establish ZIP pair
!some code
IF ~Fields.EqualRightBuffer !compare CUST fields to save buffer
CASE MESSAGE('Abandon Changes?',,,BUTTON:Yes+BUTTON:No)
OF BUTTON:No
Fields.AssignRightToLeft !copy changes to CUST (write) buffer
OF BUTTON:Yes
Fields.AssignBufferToLeft !restore original to CustQ (display) buffer
END
END

See Also: AddPair, RealList

228 ABC Library Reference

Init (initialize the BufferedPairsClass object)

Init
The Init method initializes the BufferedPairsClass object.

Implementation: The Init method creates the List and RealList properties. This method "points" the inherited List property
to the RealList property so there is, in fact, only one list of fields which may be referred to as RealList.

Example:
INCLUDE('ABUTIL.INC') !declare BufferedPairs Class
Fields &BufferedPairsClass !declare BufferedPairs reference

CODE
Fields &= NEW BufferedPairsClass !instantiate BufferedPairs object
Fields.Init !initialize BufferedPairs object
.
.
.
Fields.Kill !terminate BufferedPairs object
DISPOSE(Fields) !release memory allocated for BufferedPairs object

See Also: Kill, List, RealList

BufferedPairsClass 229

Kill (shut down the BufferedPairsClass object)

Kill
The Kill method disposes any memory allocated during the object's lifetime and performs any other necessary termination
code.

Implementation: The Kill method disposes the List and RealList properties created by the Init method.

Example:
INCLUDE('ABUTIL.INC') !declare BufferedPairs Class
Fields &BufferedPairsClass !declare BufferedPairs reference

CODE
Fields &= NEW BufferedPairsClass !instantiate BufferedPairs object
Fields.Init !initialize BufferedPairs object
.
.
.
Fields.Kill !terminate BufferedPairs object
DISPOSE(Fields) !release memory allocated for BufferedPairs object

See Also: Init, List, RealList

230 ABC Library Reference

ConstantClass
ConstantClass Overview
The ConstantClass provides an easy, flexible, and efficient way to "loop through" constant data. That is, the
ConstantClass parses structures like the following so you can access each (unlabeled) data item discretely:
Errors GROUP,STATIC
Items USHORT(40) !item count
USHORT(Msg:RebuildKey) !begin item 1
BYTE(Level:Notify)
PSTRING('Invalid Key')
USHORT(Msg:RebuildFailed) !begin item 2
BYTE(Level:Fatal)
PSTRING('Key was not built')
!38 more USHORT,BYTE,PSTRING combinations
END

ConstantClass Concepts

The ConstantClass parses and loads constant data such as error messages or translation text from the GROUP structure
that declares the data into other data structures or memory variables (one item at a time). It can also write all the constant
data into a QUEUE or a FILE.

The ConstantClass intelligently handles irregular data--you can declare the constant text data with a series of strings of
varying lengths so that no space is wasted. The ConstantClass also handles a variety of numeric datatypes including
BYTE, SHORT, USHORT, and LONG.

The ConstantClass provides several ways to stop processing the constant data, including a simple item count, a text
match, and a read-to-the-end option.

A single ConstantClass object can process multiple GROUP structures with the same (or incremental) layouts.
ConstantClass 231

Declaring the Data

To use the ConstantClass, you must declare the constant data within a GROUP structure. The GROUP structure may
declare a single sequence using any combination of the permitted datatypes, or a series of such sequences (the GROUP
repeats the combination of datatypes as many times as needed). The ConstantClass permits CSTRING, PSTRING,
BYTE, SHORT, USHORT, and LONG datatypes. The GROUP structure may contain an initial BYTE or USHORT that
specifies how many times a sequence of datatypes is repeated. For example:

Errors GROUP,STATIC
Items BYTE(2) !optional item count
USHORT(Msg:RebuildKey) !begin first item
BYTE(Level:Notify)
PSTRING('Invalid Key') !end first item
USHORT(Msg:RebuildFailed) !begin second item
BYTE(Level:Fatal)
PSTRING('Key not built') !end second item
END

Here is another example of a structure the ConstantClass can handle:

Translation GROUP,STATIC !no item count
PSTRING('&Across') !default text
PSTRING('') !translation text
PSTRING('Align all window Icons') !default text
PSTRING('') !translation text
PSTRING('Arrange Icons') !default text
PSTRING('') !translation text
END

If the GROUP is declared within a procedure it must have the STATIC attribute. See the Language Reference for more
information.

Describing the Data

The ConstantClass uses two methods to describe or understand the structure of the constant data it processes: the Init
method and the AddItem method. The Init method (termination parameter) indicates whether or not the GROUP structure
declares an item count as well as the datatype of the item count (see Init). The AddItem method identifies each repeating
component of the GROUP structure as well as the target variable that receives the contents of the repeating component
(see AddItem).
232 ABC Library Reference

ConstantClass Relationship to Other Application Builder Classes

The TranslatorClass, ErrorClass, ToolbarClass, and PrintPreview classes all use the ConstantClass. These classes
automatically instantiate the ConstantClass as needed.

ConstantClass ABC Template Implementation

All ABC Library references to the ConstantClass are encapsulated with ABC Library methods--the ABC Templates do not
directly reference the ConstantClass.

ConstantClass Source Files

The ConstantClass source code is installed by default to the Clarion \LIBSRC. The specific ConstantClass source code
and their respective components are contained in:

ABUTIL.INC ConstantClass declarations

ABUTIL.CLW ConstantClass method definitions

ConstantClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a
ConstantClass object. The example loads translation pairs from a constant GROUP into two CSTRINGs, which are then
passed as parameters to another TranslatorClass method. Note that the target CSTRINGs could just as easily be fields in
a QUEUE or FILE buffer.
INCLUDE('ABUTIL.INC') !declare ConstantClass, TranslatorClass
Spanish GROUP !declare constant data
Items BYTE(50) !item count
PSTRING('One') !begin first item
PSTRING('Uno')
PSTRING('Two') !begin second item
PSTRING('Dos')
!48 more PSTRING pairs
END

LangQ QUEUE
Text CSTRING(50)
Repl CSTRING(50)
Done BYTE
END

Const ConstantClass !declare & instantiate Const object

Text CSTRING(255),AUTO !a variable to receive a constant value
Repl CSTRING(255),AUTO !a variable to receive a constant value
EndFlag BYTE !terminator flag
ConstantClass 233

CODE
!process items one-at-a-time:
Const.Init(Term:BYTE) !initialize the Const object,
!the first BYTE contains item count
Const.AddItem(ConstType:PString, Text) !Describe constant structure and
Const.AddItem(ConstType:PString, Repl) ! variables to accept the values
Const.AddItem(ConstType:PString, EndFlag)
Const.TerminatorValue = 1 ! terminate when endFlag =1
Const.TerminatorField = 50 ! 50th field is the terminating field
Const.TerminatorInclude = True ! include the terminating record
Const.Set(Spanish) ! pass the constant data to Const object
LOOP WHILE Const.Next()= Level:Benign !copy constant data one at a time
!do something with Text and Repl !to AddItem variables
END
Const.Kill !shut down Const object

!process all items at a time:

Const.Init(Term:BYTE) !re initialize the Const object,
!the first BYTE contains item count
Const.AddItem(ConstType:PString,LangQ.Text) !Describe constant structure and
Const.AddItem(ConstType:PString,LangQ.Repl) ! variables to accept the values
Const.Set(Spanish) !pass the constant data to Const object
Const.Next(LangQ) !copy all constant items to the LangQ
Const.Kill !shut down Const object
234 ABC Library Reference

ConstantClass Properties
TerminatorField (identify the terminating field)

TerminatorField USHORT

The TerminatorField property contains a value that can be set to a number that represents the number (1 based)
of the field that will tested to see if it contains the termination value. The default value is 1.
See Also:

TerminatorInclude

TerminatorValue

ConstantClass.Next

Conceptual Example

TerminatorInclude (include matching terminator record)

7

TerminatorInclude BOOL

The TerminatorInclude property, when set to true (1), will include the record that matches the terminator value in the
"returned records". When set to FALSE (0), the record containing the termination value will not be included in the returned
records. By default, this property is set to FALSE (0)

See Also:

TerminatorField

TerminatorValue

Conceptual Example

ConstantClass.Next
ConstantClass 235

TerminatorValue (end of data marker)

TerminatorValue ANY
The TerminatorValue property contains a value that the ConstantClass object looks for within the constant data. When
the ConstantClass object finds the TerminatorValue, it stops processing the constant data (inclusive).

The TerminatorValue property is only one of several techniques you can use to mark the end of the constant data. See
the Init method for more information on this and other techniques.

Implementation: The Init method CLEARs the TerminatorValue property; therefore, you should set the TerminatorValue
property after the Init method executes.

The Next() method returns Level:Notify when the characters of the constant data matches the value of the
TerminatorValue property. The Next(FILE) and Next(QUEUE) methods stop processing when the
ConstantClass object finds the TerminatorValue.

The TerminatorField property can be set to a number that represents the number (1 based) of the field
that will tested to see if it contains the termination value.

When the TerminatorInclude property is set to true, this will include the record that matches the terminator
value in the 'returned records'. When false, the record containing termination value will not be included in
the returned records. By default this is set to false.

See Also: Init, Next

236 ABC Library Reference

ConstantClass Methods
ConstantClass Functional Organization--Expected Use
As an aid to understanding the ConstantClass, it is useful to organize the its methods into two large categories according
to their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the ConstantClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

Init initialize the ConstantClass object
AddItem set constant datatype and target variable
Set set the constant data to process
Kill shut down the ConstantClass object

Mainstream Use:
Next copy one or all constant items to targets

Occasional Use:
Reset reset the object to beginning of the constant data

Virtual Methods

The ConstantClass has no virtual methods.

ConstantClass 237

AddItem (set constant datatype and target variable)

AddItem( datatype, target )

AddItem Sets the (repeating) constant datatype and its corresponding target variable.
datatype An integer constant, variable, EQUATE or expresssion that identifies the datatype of a repeating constant
within the constant GROUP structure. Valid datatype values are ConstType:Cstring, ConstType:Pstring,
ConstType:Byte, ConstType:Short, ConstType:Ushort, and ConstType:Long.
target The label of the variable that receives the constant value.
The AddItem method sets a (repeating) constant datatype and its corresponding target variable. Use multiple calls to the
AddItem method to "describe" the constant data structure as well as the target variables that receive the constant data.
Implementation: You should call AddItem for each repeating datatype declared in the constant GROUP structure. The
Next method processes the constant data items described by the AddItem calls. EQUATEs for the
datatype parameter are declared in ABUTIL.INC:
ITEMIZE(1),PRE(ConstType)
First EQUATE
Cstring EQUATE(ConstType:First)
Pstring EQUATE
Byte EQUATE !1 byte unsigned integer
Short EQUATE !2 byte signed integer
UShort EQUATE !2 byte unsigned interger
Long EQUATE !4 byte signed integer
Last EQUATE(ConstType:Long)
END

Example:
Errors GROUP,STATIC
USHORT(Msg:RebuildKey) !begin first item
PSTRING('Invalid Key') !end first item
USHORT(Msg:RebuildFailed) !begin second item
PSTRING('Key not built') !end second item
END
ErrorQ QUEUE
ID LONG
Text CSTRING(255)
END
CODE
!The following describes the Errors GROUP and its corresonding target variables
Const.AddItem(ConstType:Ushort, ErrorQ.ID) !USHORT constant maps to error ID
Const.AddItem(ConstType:PString, ErrorQ.Text)!PSTRING constant maps to error text

See Also: Next

238 ABC Library Reference

Init (initialize the ConstantClass object)

Init( [termination] )

Init Initializes the ConstantClass object.

termination An integer constant, variable, EQUATE or expresssion that controls when the Next(FILE) and
Next(QUEUE) methods stop processing the constant data. If omitted, termination defaults to Term:Ushort.
Valid termination values are Term:Ushort, Term:Byte, Term:EndGroup, andTerm:FieldValue
The Init method initializes the ConstantClass object.

The termination parameter provides two important pieces of information to the ConstantClass object: it tells the
ConstantClass object whether there is a non-repeating item count declared at the beginning of the constant data
(describes the structure of the constant data), and it tells the ConstantClass object how to recognize the end of the
constant data. Valid termination values are:

Term:Ushort The GROUP declares a USHORT containing the item count--stops reading when item
count reached.
Term:Byte The GROUP declares a BYTE containing the item count--stops reading when item count
reached.
Term:EndGroup The GROUP does not declare an item count—stops reading at end of GROUP structure.
Term:FieldValue The GROUP does not declare an item count—stops reading when it finds the
TerminatorValue within the constant data.

Implementation: The Init method CLEARs the TerminatorValue property. The Init method allocates memory and should
always be paired with the Kill method, which frees the memory.

EQUATEs for the termination parameter are declared in ABUTIL.INC:

ITEMIZE(1),PRE(Term)
EndGroup EQUATE !Stops reading at end of GROUP
UShort EQUATE !Reads number of items specified by USHORT at start of group
Byte EQUATE !Reads number of items specified by BYTE at start of group
FieldValue EQUATE !Stops when specified value is found in first AddItem field,
!only first 32 chars are compared
END

Example:
Const.Init(Term:BYTE) !Initialize the Const object,
!the first BYTE contains item count

Const.AddItem(ConstType:PString, LangQ.Text)
!Describe constant structure and variables to accept the values
Const.AddItem(ConstType:PString, LangQ.Repl)

Const.Set(Spanish) !pass the constant data to Const object

Const.Next(LangQ) !copy all constant items to the LangQ
Const.Kill !shut down Const object

See Also: Kill, Next, TerminatorValue

ConstantClass 239

Kill (shut down the ConstantClass object)

Kill
The Kill method frees any memory allocated during the life of the object and does any other required termination code.

Example:
Const.Init(Term:BYTE) !Initialize the Const object,
! the first BYTE contains item count
Const.AddItem(ConstType:PString, LangQ.Text) !Describe constant structure and
Const.AddItem(ConstType:PString, LangQ.Repl) !variables to accept the values
Const.Set(Spanish) !pass the constant data to Const object
Const.Next(LangQ) !copy all constant items to the LangQ
Const.Kill !shut down Const object
240 ABC Library Reference

Next (load all constant items to file or queue)

Next( | file |)

| queue | )

Next Loads all the constant items to a file or queue.

file The label of the FILE to which to ADD each constant item.
queue The label of the QUEUE to which to ADD each constant item.
The Next method processes all of the constant items and executes an ADD(file) or ADD(queue) for each item.

Prior calls to the AddItem method determine the makeup of the item as well as the target variables that receive the item.
The target variables should be within the file or queue structure to make the corresponding ADD meaningful.

The Init method determines what constitutes the end of the constant data.

Implementation: The Next(FILE) and Next(QUEUE) methods call the Next() method for each constant item, then execute
an ADD(file) or ADD(queue) for each item.

Example:
Spanish GROUP !declare constant data
Items BYTE(50) !item count
PSTRING('One') !begin first item
PSTRING('Uno')
PSTRING('Two') !begin second item
PSTRING('Dos')
!48 more PSTRING pairs
END

LangQ QUEUE
Text CSTRING(50)
Repl CSTRING(50)
END

Const ConstantClass !declare & instantiate Const object

Text CSTRING(255),AUTO !a variable to receive a constant value
Repl CSTRING(255),AUTO !a variable to receive a constant value
CODE
!process all items at a time
Const.Init(Term:BYTE) !Initialize the Const object,
! the first BYTE contains item count
Const.AddItem(ConstType:PString, LangQ.Text) !Describe constant structure and
Const.AddItem(ConstType:PString, LangQ.Repl) ! variables to accept the values
Const.Set(Spanish) !pass the constant data to Const object
Const.Next(LangQ) !copy all constant items to the LangQ
Const.Kill !shut down Const object

See Also: AddItem, Init, Next

ConstantClass 241

Next (copy next constant item to targets)

Next, PROC
The Next method copies the next constant item to its respective targets (as defined by the AddItem method) and returns a
value indicating whether the item was copied. A return value of Level:Benign indicates the item was copied successfully; a
return value of Level:Notify indicates the item was not copied because the end of the constant data, as defined by the Init
method, was reached.

Prior calls to the AddItem method determine the makeup of the item as well as the target variables that receive the item.

Implementation: The Next method parses a single item in the constant data, performing any required datatype
conversions, and increments appropriate internal counters.

Return Data Type: BYTE

Example:
Spanish GROUP !declare constant data
Items BYTE(50) !item count
PSTRING('One') !begin first item
PSTRING('Uno')
PSTRING('Two') !begin second item
PSTRING('Dos')
!48 more PSTRING pairs
END

Const ConstantClass !declare & instantiate Const object

Text CSTRING(255),AUTO !a variable to receive a constant value
Repl CSTRING(255),AUTO !a variable to receive a constant value
CODE
!process items one-at-a-time
Const.Init(Term:BYTE) !initialize the Const object,
! the first BYTE contains item count
Const.AddItem(ConstType:PString, Text) !Describe constant structure and
Const.AddItem(ConstType:PString, Repl) ! variables to accept the values
Const.Set(Spanish) !pass the constant data to Const object
LOOP WHILE Const.Next()=Level:Benign !copy constant data one item at a time
!do something with Text and Repl ! to respective AddItem target variables
END
Const.Kill !shut down Const object

See Also: AddItem, Init, Next

242 ABC Library Reference

Reset (reset the object to the beginning of the constant data)

Reset
The Reset method resets internal counters to start processing constant data from the beginning.

Implementation: The Set, Next(FILE) and Next(QUEUE) methods call the Reset method. Typically you will not call this
method.

Example:
ConstantClass.Set PROCEDURE(*STRING Src)
CODE
DISPOSE(SELF.Str)
SELF.Str &= NEW STRING(LEN(Src))
SELF.Str = Src
SELF.SourceSize=LEN(SELF.Str)
SELF.Reset
ConstantClass 243

Set (set the constant data to process)

Set( datasource )

Set Sets the GROUP structure to process.

datasource The label of the GROUP structure the ConstantClass object processes.
The Set method sets the GROUP structure to process.

Implementation: The Set method takes a copy of datasource and calls the Reset method to reset internal counters to
process datasource copy from the beginning.

Example:
Spanish GROUP !declare constant data
Items BYTE(50) !item count
PSTRING('One') !begin first item
PSTRING('Uno')
PSTRING('Two') !begin second item
PSTRING('Dos')
!48 more PSTRING pairs
END

LangQ QUEUE
Text CSTRING(50)
Repl CSTRING(50)
END

Const ConstantClass !declare & instantiate Const object

CODE
!process all items at a time
Const.Init(Term:BYTE) !re initialize the Const object,
! the first BYTE contains item count
Const.AddItem(ConstType:PString, LangQ.Text) !Describe constant structure and
Const.AddItem(ConstType:PString, LangQ.Repl) ! variables to accept the values
Const.Set(Spanish) !pass the constant data to Const object
Const.Next(LangQ) !copy all constant items to the LangQ
Const.Kill !shut down Const object

See Also: Reset

244 ABC Library Reference

Crystal8 Class
Seagate Software‘s Crystal Reports is one of the leading report writers delivering Windows reports. For more information
on this product see Seagate Software at www.seagatesoftware.com.

Clarion‘s Crystal Report interface is comprised of templates, libraries, and DLLs that communicate with Seagate‘s
Crystal Reports, version 8. The DLL is accessed by a Class Interface and is hooked to your application using simple
standard Clarion code. This interface allows a seamless integration of previously defined Crystal reports within a Clarion
application. The Crystal report engine accesses data and creates the report. The report can be previewed in a Clarion
window.

Clarion‘s Crystal Reports implementation is compatible with both the ABC and Legacy templates. It can only be used in
32-bit applications.

Crystal8 Class Concepts

Clarion‘s Crystal Reports implementation is a DLL that communicates with Seagate Software‘s Crystal Reports report
writer. The Crystal 8 Class accesses the DLL. There are several templates available which make the interface to the
report writer easily accessible from your Clarion program. Previewing and/or printing reports are simple.

Relationship to Other Application Builder Classes

The Crystal8 class works independently of all other ABC classes.

ABC Template Implementation

The PreviewCrystalReport and PrintCrystalReport template extensions instantiate an object based on the object name
specified by either of these extensions. The object is instantiated in the procedure where the extension exists.

Crystal8 Source Files

The Crystal8 class declarations are installed by default to the Clarion \LIBSRC folder. The Crystal8 component is
distributed as a LIB/DLL, therefore the source code for the methods is not available. However, the methods are defined
in this chapter and may be implemented in applications provided the required LIB/DLL is available at runtime.

CLAcr8.INC Crystal Class Definition

CLAcr8l.INC Crystal Class Definition Local Compile
CLAcr8.dll Crystal DLL
CLAcr8.lib Crystal LIB
CLAcr8L.lib Crystal Local LIB

Crystal8 Class Properties

There are no properties associated with the Crystal8 Class Library.
Crystal8Class 245

Crystal8 Methods
AllowPrompt (prompt for runtime parameter data)

AllowPrompt(| allowpromptflag |)

AllowPrompt Allow report runtime prompting for Crystal Parameter fields.

Allowpromptflag An integer constant, variable, EQUATE, or expression that specifies whether the report will
prompt for runtime parameter fields. A value of one (1) is used to allow prompting; a value of zero
(0) is used to disallow field prompting.

The AllowPrompt method can conditionally allow the Crystal report that is being previewed or printed to prompt for runtime
parameter fields. These parameter fields must be defined in the Crystal report. This method returns a BYTE representing
the value of allowpromptflag.

Return Data Type: BYTE

Example:
oCrystal8.AllowPrompt(1)
246 ABC Library Reference

CanDrillDown(allow Crystal drill down support )

CanDrillDown(| candrilldown |)

CanDrillDown Allows use of Crystal Report‘s drill down feature.

candrilldown An integer constant, variable, EQUATE, or expression that specifies whether the report make use
of Crystal‘s drill down feature. A value of one (1) allows drill down to be used; a value of zero (0)
removes the ability to drill down.

The CanDrillDown method allows a Crystal Report to use the defined drill down support. For more information on
Crystal‘s drill down feature refer to the Crystal Report documentation. This method returns a BYTE representing
the value of candrilldown.

Return Data Type: BYTE

Example:
oCrystal8.CanDrillDown(1)
Crystal8Class 247

HasCancelButton (display cancel button on report preview)

HasCancelButton (| hascancelbutton |)

HasCancelButton Allow a cancel button on the report preview window.

hascancelbutton An integer constant, variable, EQUATE, or expression that specifies whether a cancel button will
appear on the report‘s preview window. A value of one (1) displays the cancel button; a value of
zero (0) does not display the cancel button.

The HasCancelButton method is used to optionally display a cancel button on the report preview window. This
method returns a BYTE representing the value of hascancelbutton.

Return Data Type: BYTE

Example:

oCrystal8.HasCancelButton(1)
248 ABC Library Reference

HasCloseButton (display close button on report preview)

HasCloseButton (| hasclosebutton |)

HasCloseButton Allow a close button on the report preview window.

hasclosebutton An integer constant, variable, EQUATE, or expression that specifies whether a close button will
appear on the reports preview window. A value of one (1) displays the close button; a value of
zero (0) does not display the close button.

The HasCloseButton method is used to optionally display a close button on the report preview window. This
method returns a BYTE representing the value of hasclosebutton.

Return Data Type: BYTE

Example:

oCrystal8.HasCloseButton(1)
Crystal8Class 249

HasExportButton (display export button on report preview)

HasExportButton (| hasexportbutton |)

HasExportButton Allow an export button on the report preview window.

hasexportbutton An integer constant, variable, EQUATE, or expression that specifies whether an export button will
appear on the reports preview window. A value of one (1) displays the export button; a value of
zero (0) does not display the export button.

The HasExportButton method is used to optionally display an export button on the report preview window. This
method returns a BYTE representing the value of hasexportbutton.

Return Data Type: BYTE

Example:

oCrystal8.HasExportButton(1)
250 ABC Library Reference

HasLaunchButton (display launch button on report preview)

HasLaunchButton (| haslaunchbutton |)
HasLaunchButton Allow a launch button on the report preview window.

haslaunchbutton An integer constant, variable, EQUATE, or expression that specifies whether a launch button will
appear on the reports preview window. A value of one (1) displays the launch button; a value of
zero (0) does not display the launch button.

The HasLaunchButton method is used to optionally display a launch button on the report preview window. This
method returns a BYTE representing the value of haslaunchbutton. The launch button is used to launch the
Seagate Analysis tool.

Return Data Type: BYTE

Example:

oCrystal8.HasLaunchButton(1)
Crystal8Class 251

HasNavigationControls (display navigation controls on report preview)

HasNavigationControls (| hasnavigationcontrols |)

HasNavigationControls Allows navigation controls on the report preview window.

hasnavigationcontrols An integer constant, variable, EQUATE, or expression that specifies whether the
navigation controls will appear on the report‘s preview window. A value of one (1)
displays the navigation controls; a value of zero (0) does not display the navigation
controls.

The HasNavigationControls method is used to optionally display navigation controls on the report preview
window. This method returns a BYTE representing the value of hasnavigationcontrols. Navigation controls are
used to navigate through a report, immediately to the beginning, end or anywhere in between.

Return Data Type: BYTE

Example:

oCrystal8.HasNavigationControls(1)
252 ABC Library Reference

HasPrintButton (display print button on report preview)

HasPrintButton (| hasprintbutton |)

HasPrintButton Allows a print button on the report preview window.

Hasprintbutton An integer constant, variable, EQUATE, or expression that specifies whether a print button will
appear on the report‘s preview window. A value of one (1) displays the print button; a value of
zero (0) does not display the print button.

The HasPrintButton method is used to optionally display a print button on the report preview window. This method
returns a BYTE representing the value of hasprintbutton.

Return Data Type: BYTE

Example:

oCrystal8.HasPrintButton(1)
Crystal8Class 253

HasPrintSetupButton (display print setup button on report preview)

HasPrintSetupButton (| hasprintsetupbutton |)

HasPrintSetupButton Allows a print setup button on the report preview window.

hasprintsetupbutton An integer constant, variable, EQUATE, or expression that specifies whether a print setup button
will appear on the reports preview window. A value of one (1) displays the print setup button; a
value of zero (0) does not display the print setup button.

The HasPrintSetupButton method is used to optionally display a print setup button on the report preview window.
This method returns a BYTE representing the value of hasprintsetupbutton.

Return Data Type: BYTE

Example:

oCrystal8.HasPrintSetupButton(1)
254 ABC Library Reference

HasProgressControls (display progress controls on report preview)

HasProgressControls (| hasprogresscontrols |)

HasProgressControls Allows navigation controls on the report preview window.

Hasprogresscontrols An integer constant, variable, EQUATE, or expression that specifies whether the progress
controls will appear on the reports preview window. A value of one (1) displays the progress
controls; a value of zero (0) does not display the progress controls.

The HasProgressControls method is used to optionally display progress controls on the report preview window.
This method returns a BYTE representing the value of hasprogresscontrol. The Progress controls display the
progress of the report when it is running. It displays records read, records selected, etc.).

Return Data Type: BYTE

Example:

oCrystal8.HasProgressControls(1)
Crystal8Class 255

HasRefreshButton (display refresh button on report preview)

HasRefreshButton (| hasrefreshbutton |)

HasRefreshButton Allows a refresh button on the report preview window.

hasrefreshbutton An integer constant, variable, EQUATE, or expression that specifies whether a refresh button will
appear on the report‘s preview window. A value of one (1) displays the refresh button; a value of
zero (0) does not display the refresh button.

The HasRefreshButton method is used to optionally display a refresh button on the report preview window. This
method returns a BYTE representing the value of hasrefreshbutton.

Return Data Type: BYTE

Example:

oCrystal8.HasRefreshButton(1)
256 ABC Library Reference

HasSearchButton (display search button on report preview)

HasSearchButton (| hassearchbutton |)

HasSearchButton Allows a search button on the report preview window.

hassearchbutton An integer constant, variable, EQUATE, or expression that specifies whether a search button will
appear on the reports preview window. A value of one (1) displays the search button; a value of
zero (0) does not display the search button.

The HasSearchButton method is used to optionally display a search button on the report preview window. This
method returns a BYTE representing the value of hassearchbutton.

Return Data Type: BYTE

Example:

oCrystal8.HasSearchButton(1)
Crystal8Class 257

HasZoomControl (display zoom control on report preview)

HasZoomControl (| haszoomcontrol |)

HasZoomControl Allows a zoom control on the report preview window.

haszoomcontrol An integer constant, variable, EQUATE, or expression that specifies whether a zoom button will
appear on the report‘s preview window. A value of one (1) displays the zoom control; a value of
zero (0) does not display the zoom control.

The HasZoomControl method is used to optionally display a zoom control on the report preview window. This
method returns a BYTE representing the value of haszoomcontrol.

Return Data Type: BYTE

Example:

oCrystal8.HasZoomControl(1)
258 ABC Library Reference

Init (initialize Crystal8 object)

Init (reportname)

Init Initialize the Crystal8 object.

reportname A string constant, variable, EQUATE, or expression containing the report name. This report name is used
when previewing a report. It is also the window caption (text).

The Init method initializes the Crystal8 object. This method also sets the title of the preview window, if the report is
previewed. A BYTE is returned from this method and represents whether the report engine is successfully
initialized.

Return Data Type: BYTE

Example:

oCrystal8.Init( ReportPathName )
Crystal8Class 259

Kill (shut down Crystal8 object)

Kill

The Kill method shuts down the Crystal8 object, releasing any memory allocated durring the lifetime of the object.

Example:

oCrystal8.Kill()
260 ABC Library Reference

Preview (preview a Crystal Report)

Preview (| windowtitle, initstate, frame, icon, systemmenu, maximizebox, 3dflag|)
Preview Preview a Crystal Report.

windowtitle A string constant, variable, EQUATE, or expression containing the text to display in the report preview
window‘s title bar. This parameter is optional.

initstate A string constant, variable, EQUATE, or expression containing an N, M, or I. Use N (Normal) to display
the preview window at the default size. Use M (Maximized) to display the preview window in a maximized
state. Use I (Iconized) to display the preview window in an iconized state. This parameter is optional.

frame A string constant, variable, EQUATE, or expression containing an S, D, R, or N. Use S to give the preview
window a single pixel frame. Use D to give the preview window a thick frame. Use R to give the preview
window a thick but resizeable frame. Use N to give the preview window no frame under Windows 3.1 or a
single pixel frame under Window 95/98. This parameter is optional.

icon A string constant, variable, EQUATE, or expression containing an icon filename. By specifiying an icon
file, a minimize button is automatically placed on the preview window. This parameter is optional.

systemmenu An integer constant, variable, EQUATE, or expression that specifies whether the preview window will
contain a system menu. A value of TRUE will give the preview window a system menu. A value of
FALSE (the default value) will not include the system menu on the preview window. This parameter is
optional.

maximizebox An integer constant, variable, EQUATE, or expression that specifies whether the preview window will
contain a maximize button. A value of TRUE (the default value) will place the maximize button on the
preview window. A value of FALSE will not include the maximize box on the preview window. This
parameter is optional.

3dflag An integer constant, variable, EQUATE, or expression that specifies whether the preview window will
have a 3D look. The 3D look provides the window with a gray backgound and chiseled control look. A
value of TRUE (the default value) will provide the preview window with the 3D look. A value of FALSE will
not provide the preview window with the 3d look. This parameter is optional.

The Preview method is used to preview a Crystal report within a Clarion window. This method supports several
preview window options.

Example:

oCrystal8.Preview( 'My Report','I','R',,0,1,1 )

Crystal8Class 261

_Print (print a Crystal Report)

_Print(| copies, printersetup |)

_Print Print a Crystal Report.

copies An integer constant, variable, EQUATE, or expression that specifies the number of copies of the report to
print. The default for this parameter is 1. This parameter is optional.

printersetup An integer constant, variable, EQUATE, or expression that specifies whether the Printer Setup dialog is
displayed before sending the report to the printer. Specifying TRUE or 1 for this parameter will cause the
Printer Setup dialog to be displayed; a value of FALSE or 0 (the default value) will allow the report to go
directly to the printer. This parameter is optional.

The _Print method prints a Crystal report directly to the printer without any option to preview the report. The
printer setup dialog is optional before the report is sent to the printer.

Example:

oCrystal8._Print( 1, 1 )
262 ABC Library Reference

Query (retrieve or set the SQL data query)

Query( | querystring |)

Query Set or retrieve the SQL data query.

querystring A string constant, variable, EQUATE, or expression containing the SQL query to be sent to the SQL data
source. This parameter is optional.

The Query method is used to either get or set the SQL query. If the querystring is omitted from the method call,
the current query is retrieved.

Return Data Type: STRING

Example:

formula = oCrystal8.Query()!retrieve query into formula variable

formula = '{{Customer.Country} in ["Australia"]' ! SQL query
oCrystal8.Query( formula ) ! Set the query
Crystal8Class 263

SelectionFormula (retrieve or set the Crystal formula )

SelectionFormula(| formulastring |)

SelectionFormula Set or retrieve the Crystal formula.

Formulastring A string constant, variable, EQUATE, or expression containing the Crystal formula. This
parameter is optional.

The SelectionFormula method is used to either get or set the report‘s formula used to limit retrieved records. If the
formulastring is omitted from the method call, the current formula is retrieved.

Return Data Type: STRING

Example:

formula = oCrystal8.SelectionFormula()!retrieve selection formula into formula variable

formula = '{{Customer.Country} in ["Australia"]' ! SQL query
oCrystal8.SelectionFormula( formula ) ! Set the query
264 ABC Library Reference

ShowDocumentTips (show tips on docuement in the preview window)

ShowDocumentTips(| showdocumenttips |)

ShowDocumentTips Display tooltips in the document being previewed.

showdocumenttips An integer constant, variable, EQUATE, or expression that specifies whether to enable tooltips on
the document in the report preview window. A value of one (1) indicates that tooltips will be
shown. A value of zero (0) indicates that tooltips will not be displayed on the document in the
preview window. This is the default if the parameter is omitted.

The ShowDocumentTips method is used to enable tooltips on the document being previewed in the report
preview window. This method returns a BYTE representing the value of showdocumenttips.

Return Data Type: BYTE

Example:

oCrystal8.ShowDocumentTips(1)
Crystal8Class 265

ShowReportControls (show print controls)

ShowReportControls (| showreportcontrols |)

ShowReportControls Display tooltips in the document being previewed.

showreportcontrols An integer constant, variable, EQUATE, or expression that specifies whether the print controls
are displayed. A value of one (1) will cause the print controls to be displayed. A value of zero (0)
indicates that will hide the print controls. This parameter is optional and defaults to TRUE if
omitted.

The ShowReportControls method is used to display the print controls. The print controls include the First,
Previous, Next, and Last Page buttons as well as the buttons for Cancel, Close, Export, and Print to Printer. This
method returns a BYTE representing the value of showreportcontrols.

Return Data Type: BYTE

Example:
oCrystal8.ShowReportControls(1)
266 ABC Library Reference

ShowToolbarTips (show tips on preview window toolbar)

ShowToolbarTips(| showtooltips |)

ShowToolbarTips Display tooltips in the preview window‘s toolbar.

showtooltips An integer constant, variable, EQUATE, or expression that specifies whether to enable tooltips on
the toolbar in the report preview window. A value of one (1) indicates that tooltips will be shown.
This is the default if the parameter is omitted. A value of zero (0) indicates that tooltips will not be
displayed in the report preview window.

The ShowToolbarTips method is used to enable tooltips on the toolbar of the report preview window. This method
returns a BYTE representing the value of showtooltips.

Return Data Type: BYTE

Example:

oCrystal8.ShowToolBarTips(1)
Crystal8Class 267
268 ABC Library Reference

cwRTF Class
cwRTF Overview
Clarion's implementation of Rich Text Format (RTF) is derived from Microsoft's Rich Edit Control, version 3.0. Rich Text
provides a storage format for text that keeps the text compatible among different operating systems, and software
applications. A rich text control allows a user to enter, edit, format, print, and save text.

cwRTF Class Concepts

The features of Clarion's RTF control include the support for colorized text, fonts, font sizes, bold, italics, underlining,
paragraph justification, bullets, undo, redo, cut, copy and paste clipboard functionality, search, print, new open and save
to file, ruler, and tab settings.

Clarion's Rich Text support is compatible with both the ABC and Legacy templates. It may only be used in a 32-bit
application. Multiple RTF controls may be used on a single window.

Clarion's Rich Text Classes and Templates are wrappers around Microsoft's Rich Edit Control DLL's. The presence of
RichEdxx.DLL is required in the Windows/System directory. There are three versions of this DLL. The following list of
operating systems shows which DLL each system installs and supports. Other programs may install a newer version of
the Rich Edit DLL.

Windows NT/Windows 2000

Microsoft® Windows NT® version 4.0 includes Rich Edit 1.0 and 2.0. Microsoft Windows® 2000 includes Rich
Edit 3.0 with a Rich Edit 1.0 emulator.
Windows 98
Windows 98 includes Rich Edit 1.0 and 2.0.
Windows 95
Windows 95 includes only Rich Edit 1.0. However, Riched20.dll is compatible with Windows 95 and may be
installed if an application that uses Rich Edit 2.0 has been installed.
cwRTFClass 269

cwRTF Relationship to Other Application Builder Classes

The cwRTF class works independantly of all other ABC classes.

cwRTF ABC Template Implementation

Once the cwRTF procedure template extension is added to a procedure, the templates instantiate a cwRTF object into the
generated code for the procedure. This is also where the cwRTF object is initialized.

cwRTF Source Files

The cwRTF class declarations are installed by default to the Clarion \LIBSRC folder. The cwRTF component is distributed
as a LIB/DLL, therefore the source code for the methods is not available. However, the methods are defined in this
chapter and may be implemented in applications provided the required LIB/DLL is available at runtime.

CLARTF.INC Rich Text Class Definition

CLARTFL.INC Rich Text Class Definition Local Compile
CLARTF.lib Rich Text LIB
CLARTFL.lib Rich Text Local LIB

cwRTF Properties
cwRTF Properties
The cwRTF class contains many properties that although are not PRIVATE, should not be used. These methods are used
internally.

hRTFWindow(RTF control handle)

hRTFWindow LONG
The hRTFWindow property is a handle to the RTF control.
270 ABC Library Reference

cwRTF Methods
AlignParaCenter (center paragraph)
AlignParaCenter
The AlignParaCenter method is used to center the current or selected paragraph of text within the rich text control. The
current paragraph is the one that the cursor is within.

Example:
oRTF_RTFTextBox.AlignParaCenter() !Center paragraph

AlignParaLeft (left justify paragraph)

AlignParaLeft
The AlignParaLeft method is used to left justify the current or selected paragraph of text within the rich text control. The
current paragraph is the one that the cursor is within.

Example:
oRTF_RTFTextBox.AlignParaLeft() !Left justify paragraph

AlignParaRight (right justify paragraph)

AlignParaRight
The AlignParaRight method is used to right justify the current or selected paragraph of text within the rich text control.
The current paragraph is the one that the cursor is within.

Example:
oRTF_RTFTextBox.AlignParaRight() !Right justify paragraph
cwRTFClass 271

ChangeFontStyle (set current font style)

ChangeFontStyle(fontstyle)

ChangeFontStyle Sets the current font style.

fontstyle An integer constant, variable, EQUATE, or expression that contains a value that
represents a fontstyle. Valid fontstyle equates can be found in EQUATES.CLW.
The ChangeFontStyle method is used to set the current font style. The style of a font represents the strike weight and
style of the font.

Example:
oRTF_RTFTextBox.ChangeFontStyle(FONT:Italic ) !Font Style
oRTF_RTFTextBox.ChangeFontStyle(loc:fontstyle ) !Variable Font Style

CanRedo (check for redo data)

CanRedo
The CanRedo method is used to to see if there is data in the redo buffer. A return value of one (1 or True) indicates there
is redo data in the buffer, a redo operation is available; a return value of zero (0 or False) is returned if there is no redo
data in the buffer, a redo operation is not available.

Return Data Type: BYTE

Example:
loc:redo =oRTF_RTFTextBox.CanRedo() !Check for data in the Redo buffer
272 ABC Library Reference

CanUndo (check for undo data)

CanUndo
The CanUndo method is used to to see if there is data in the undo buffer. A return value of one (1 or True) indicates there
is undo data in the buffer, an undo operation is available; a return value of zero (0 or False) is returned if there is no undo
data in the buffer, an undo operation is not available.

Return Data Type: BYTE

Example:
loc:undo =oRTF_RTFTextBox.CanUndo() !Check for data in the Undo buffer

Color (set text color)

Color
The Color method calls the Windows standard color choice dialog box in order to allow a user to choose a color. If text is
selected prior to calling the color dialog, the selected text will be colored the selected color.

Example:
oRTF_RTFTextBox.Color()!Color text

Copy (copy selected text to clipboard)

Copy
The Copy method is used to copy selected text from the rich text control into the clipboard.

Example:
oRTF_RTFTextBox.Copy() !Copy text to clipboard
cwRTFClass 273

Cut (cut selected text )

Cut
The Cut method is used to cut the selected text from the rich text control into the clipboard.

Example:
oRTF_RTFTextBox.Cut() !Cut text to clipboard

Find (set current font style)

Find([findtext])

Find Search for text within the rich text field.

findtext A string constant, variable, EQUATE, or expression containing the text for search
for. If this is omitted the Find dialog is presented.
The Find method is used to search the Rich Text field for the text specified in findtext. If no findtext is specified, the Find
dialog is presented. The user can type in the text to search for as well as specify other search options such as Whoe
Words Only, Case Sensitive Search, and Search Direction (up or down).

This method returns a value indicating the character position where the text was found.

Return Data Type: LONG

Example:
loc:position =oRTF_RTFTextBox.Find(loc:find ) ! Search for contents of loc:find
loc:position =oRTF_RTFTextBox.Find('mytext ' ) ! Search for 'mytext'
loc:position =oRTF_RTFTextBox.Find() ! Show find dialog
274 ABC Library Reference

FlatButtons (use flat button style)

FlatButtons(buttonstatus)

FlatButtons Set the FormatBar and Toolbar buttons to appear in a flat or raised mode.

buttonstatus A numeric constant, variable, EQUATE, or expression that indicates whether to

use flat or raised buttons. A TRUE valid is passed to the method to use flat
buttons. A FLASE value is passed to the FlatButtons method to raised buttons.
The FlatButtons method is used to set the FormatBar and Toolbar buttons to appear in a flat or raised mode. A flat
button remains flat until the mouse cursor passes over it.

Example:
oRTF_RTFTextBox.FlatButtons(1 ) !Flat buttons
oRTF_RTFTextBox.FlatButtons(0 ) !Raised buttons
cwRTFClass 275

Font (apply font attributes)

Font([fontname], [fontsize], [fontcolor], [fontstyle])

Font Apply font attributes to rich text.

fontname A string constant or variable containing a font name.

fontsize An integer constant containing the size (in points) of the font.

fontcolor An integer constant containing the red, green, and blue values for the color of the
font in the low-order three bytes, for an EQUATE for a standard Windows color
value.

fontstyle An integer constant, constant expression, or EQUATE specifying the strike

weight and style of the font.
The Font method is used to set font attributes at the current insertion point or apply it to the currently selected text. If all of
the parameters for this method are omitted the Windows standard font dialog box is called in order to allow a user to set
standard font attributes.

Example:
!Using variables
oRTF_RTFTextBox.Font(FontName,FontSize,FontColor,FontStyle )
!Specific Font Attributes
oRTF_RTFTextBox.Font('Arial ',10,COLOR:Red,FONT:Underline )
!Font Dialog
oRTF_RTFTextBox.Font()
276 ABC Library Reference

GetText (copy text to variable)

GetText(text, [startpos], [endpos])

GetText Copy indicated text to a variable.

text A string variable that will receive the specified text. The highlighted text will be
assigned to the variable if no starting and ending positions are specified. If
positions are specified the text specified by these positions will be assigned to
the string variable.

startpos An integer constant or variable that specifies the starting character position to
copy text from.

endpos An integer constant or variable that specifies the ending character position to
copy text from.
The GetText method is used to copy the specified text to a string or variable. The method can return a result that
specifies the length (number of characters) of the copied text.

Return Data Type: LONG

Example:
oRTF_RTFTextBox.GetText(loc:find, ,) !read text into loc:find
loc:length =oRTF_RTFTextBox.GetText(loc:find,,) !return string length

!read text into loc:find from specified position

oRTF_RTFTextBox.GetText(loc:find,10,20)
cwRTFClass 277

Init (initialize the cwRTF object)

Init(window, textbox, [rulerflag], [toolbarflag], [formatbarflag])

Init Initialize the cwRTF object.

window The label of the WINDOW that contains the rich text control.

textbox A numeric constant, variable, EQUATE, or expression containing the control

number (FEQ) of the rich text control.

rulerflag A numeric constant, variable, EQUATE, or expression that indicates whether to

initially display the RulerBar with the rich text control.

toolbarflag A numeric constant, variable, EQUATE, or expression that indicates whether to

initially display the ToolBar with the rich text control.

formatbarflag A numeric constant, variable, EQUATE, or expression that indicates whether to

initially display the FormatBar with the rich text control.
The Init method initializes the cwRTF object. This method also sets the initial states of the RulerBar, ToolBar, and
FormatBar. By default all three bars are displayed.

Example:
oRTF_RTFTextBox.Init( Window, ?RTFTextBox, 1, 1, 1 )
278 ABC Library Reference

IsDirty (indicates modified data)

IsDirty([saveflag])

IsDirty Determines if the data in the rich text control has been modified.

saveflag A numeric constant, variable, EQUATE, or expression that indicates whether to

prompt the user to save changes to the rich text field if the field has changed
data. A one (1 or True) value signifies the user will be prompted. This is the
default value. A zero (0 or False) value signifies the user will not be prompted to
save the data.
The IsDirty method is used to determine if the text in the RTF control has changed. If the text has changed, the user can
be prompted to save all changes. A one (1 or True) is returned if the data in the rich text control contains changes; a zero
(0 or False) is returned if the data in the rich text control does not contain data changes.

Return Data Type: BYTE

Example:
loc:dirty =oRTF_RTFTextBox.IsDirty(1) !Prompt to save changes
loc:dirty =oRTF_RTFTextBox.IsDirty(0) !No prompt to save changes
cwRTFClass 279

Kill (shut down the csRTF object)

Kill([isdirty])

Kill Shut down the cwRTF object.

isdirty A numeric constant, variable, EQUATE, or expression that indicates whether the
rich text control's modified data should be saved to disk.
The Kill method shuts down the cwRTF object, releasing any memory allocated during the life of the obejct. Passing a
one (1 or True) value to this method will force the modified data to be saved upon termination of the method; a value of
zero (0 or False) will not save the modified data to the table.

Example:
oRTF_RTFTextBox.Kill( TRUE )

LeftIndent (indent the current or selected paragraph)

LeftIndent(indentsize)

LeftIndent Indent the current or selected paragraph.

indentsize A REAL numeric constant, variable, or expression that indicates the number of
inches to indent. A negative value will reverse the indent.
The LeftIndent method is used to indent the current or selected paragraph. The indentation size is specified in inches and
may also be a negative number to reverse the indentation.

Example:
oRTF_RTFTextBox.LeftIndent(.5) !Indent 1/2 inch from left
280 ABC Library Reference

LimitTextSize (limit amount of text)

LimitTextSize(maxtextsize)

LimitTextSize Limits the amount of text that can be placed in the rich text control regardless of
the method used to save the data field or file.

maxtextsize A numeric constant, variable, EQUATE, or expression that indicates the

maximum number of characters allowed in the rich text field. This includes the
rich text formatting characters.
The LimitTextSize method is used limit the number of text that can be placed in the rich text control regardless of the
method used to save the data field or file. This method should be called before the rich text control is loaded.

Example:
oRTF_RTFTextBox.LimitTextSize(2000) !Limit text to 2000 characters

LoadField (load rich text data from field)

LoadField(fieldname)

LoadField Load the rich text control with the data contained in the field specified.

fieldname The fully qualified label of a field to load the data from.
The LoadField method is used to load a string or memo rich text field into the rich text control.

Example:
oRTF_RTFTextBox.LoadField(let:letter ) !Load RTF field
cwRTFClass 281

LoadFile (load rich text data from file)

LoadFile(filename)

LoadFile Load the rich text control with the data contained in the file specified.

filename A string constant, variable, EQUATE, or expression containing the .RTF

filename. If no filename is specified, the Open file dialog is opened.
The LoadFile method is used to load a .RTF file into the rich text control.

Example:
oRTF_RTFTextBox.LoadField(let:letter ) !Load RTF field

NewFile (clear rich text data)

NewFile
The NewFile method is used to clear the contents of the rich text control.

Example:
oRTF_RTFTextBox.NewFile()

Offset (offset current or selected paragraph)

Offset(offsetsize)

Offset Offset the second and subsequent lines of a paragraph.

offsetsize A REAL numeric constant, variable, or expression that indicates the number of
inches to offset. A negative value will reverse the offset.
The Offset method is used to offset the second and subsequent lines of the current or selected paragraph. The offsetsize
is specified in inches and may also be a negative number to reverse the offset.

Example:
oRTF_RTFTextBox.Offset(1 ) !Offset by 1 inch

PageSetup (set page attributes)

PageSetup
The PageSetup method calls the Windows standard page setup dialog box. This dialog allows the setting of the paper
size and source, orientation, margins and printer selection and defaults.

Example:
oRTF_RTFTextBox.PageSetup()
282 ABC Library Reference

ParaBulletsOff (turn off paragraph bullets)

ParaBulletsOff
The ParaBulletsOff method is used turn off bullets for the current or selected paragraph. The current paragraph is the
one that the cursor is within.

Example:
oRTF_RTFTextBox.ParaBulletsOff() !Turn bullets off

ParaBulletsOn (turn on paragraph bullets)

ParaBulletsOn(bulletstyle)

ParaBulletsOn Turn on paragraph bullets.

bulletstyle A numeric constant, variable, EQUATE, or expression that identifies the
bullet style. Bullet styles are defined in CLARTF.INC.
The ParaBulletsOn method is used turn on bullets for the current or selected paragraph. The current paragraph is the
one that the cursor is within.

Supported bullet styles are:

Bullets:On (•)
Bullets:Arabic (1, 2, 3,...)
Bullets:LowerLetters (a, b, c,...)
Bullets:UpperLetters (A, B, C,...)
Bullets:LowerRoman (i, ii, iii,...)
Bullets:UpperRoman (I, II, III,...)

Example:
oRTF_RTFTextBox.ParaBulletsOn(BULLET:On) !Turn bullets on
cwRTFClass 283

Paste (paste text from clipboard)

Paste
The Paste method is used to paste clipboard text into the rich text control .

Example:
oRTF_RTFTextBox.Paste() !Paste text to clipboard

_Print (print rich text control contents)

_Print(showsetup, [jobtitle])

_Print Print rich text control data.

showsetup A numeric constant, variable, EQUATE, or expression that determines whether to
show the Windows Print Setup dialog.
jobtitle A string constant or variable containing a title of the job being printed. The job
title is seen from the print spooler. If no job title is specified, the default job title is
'Untitled'. If the Print icon is used from the toolbar, the job title is set to 'RTF
Data'.
The _Print method is used to simply print the rich text data.

If the PageSetup dialog is used, the method will return a one (1 or True) value if the OK button on the dialog is pressed. A
zero (0 or False) is returned if the Cancel button on the Page Seup dialog is pressed. If the Page Setup dialog is not used,
a one (1 or True) is returned.

Return Data Type: BYTE

Example:
oRTF_RTFTextBox._Print(1 ) !Show Print Setup dialog before printing
oRTF_RTFTextBox._Print(0 ) !Do not show Print Setup dialog
oRTF_RTFTextBox._Print(0, 'JobTitle' ) !Do not show Print Setup dialog
status = oRTF_RTFTextBox._Print(1, 'JobTitle' )!Do not show Print Setup dialog
284 ABC Library Reference

Redo (reapply action)

Redo
The Redo method is used to reapply the action that was previously undone on the rich text control. Redo can be used on
the previous 100 actions.

Example:
oRTF_RTFTextBox.Redo() !Redo previous undo action to rich text control

Replace (find and replace search)

Replace([findtext], [replacetext])

Replace Search for text within the rich text field.

findtext A string constant, variable, EQUATE, or expression containing the text for search
for. If this is omitted the Find dialog is presented.

replacetext A string constant, variable, EQUATE, or expression containing the text for search
for. If this is omitted the Find dialog is presented.
The Replace method is used to do a Find and Replace search option within the rich text control. If the findtext and
replacetext parameters are omitted the Find and Replace dialog will appear.

This method returns a value indicating the number of applied replaces.

Return Data Type: LONG

Example:
!Using Variables
loc:replace =oRTF_RTFTextBox.Replace(loc:find,loc:replace )
!Replace dialog
loc:replace =oRTF_RTFTextBox.Replace()
cwRTFClass 285

ResizeControls (used internally)

The ResizeControls method is used internally and should not be called otherwise.

RightIndent (indent the current or selected paragraph)

RightIndent(indentsize)

RightIndent Indent the current or selected paragraph.

indentsize A REAL numeric constant, variable, or expression that indicates the number of
inches to indent. A negative value will reverse the indent.
The RightIndent method is used to indent the current or selected paragraph from the right side of the rich text control.
The indentation size is specified in inches and may also be a negative number to reverse the indentation.

Example:
oRTF_RTFTextBox.RightIndent(.5) !Indent 1/2 inch from right

SaveField (save rich text data to field)

SaveField(fieldname)

SaveField Save the rich text control data to the field specified.

fieldname The fully qualified label of a field to save to.

The SaveField method is used to save rich text data into a table field.

Example:
oRTF_RTFTextBox.SaveField(let:letter )
286 ABC Library Reference

SaveFile (save rich text data to file)

SaveFile(filename)

SaveFile Save the rich text data to the file specified.

filename A string constant, variable, EQUATE, or expression containing the .RTF filename
to save the data to.
The SaveFile method is used to save rich text data to a .RTF file.

Example:
oRTF_RTFTextBox.SaveFile(loc:Filename )
oRTF_RTFTextBox.SaveFile('0101SS.RTF ' )

SelectText (select characters)

SelectText(startpos, endpos)

GetText Select a specific set of characters by character position.

startpos An integer constant or variable that specifies the starting character position to
select text from.

endpos An integer constant or variable that specifies the ending character position to
select text from.
The SelectText method is used select a specific set of characters by character position. The text is highlighted when it is
selected.

Example:
!Select text from position 1 to 20
oRTF_RTFTextBox.SelectText(1,20 )
!Select text from variable positions
oRTF_RTFTextBox.SelectText(loc:startpos,loc:endpos )
cwRTFClass 287

SetDirtyFlag (set modified flag)

SetDirtyFlag(status)

SetDirtyFlag Sets the modified flag for the rich text control

status A numeric constant, variable, EQUATE, or expression that indicates whether to

set or clear the dirty flag. A one (1 or True) sets the flag; a zero (0 or False)
claers the flag.
The SetDirtyFlag method is used to set or clear the modified flag for the rich text control. This can be used to clear the
flag so the user is not prompted to save data.

Example:
oRTF_RTFTextBox.SetDirtyFlag( 0) ! Clear dirty flag

SetFocus (give rich text control focus)

SetFocus
The SetFocus method is used to give the rich text control focus.

Example:
oRTF_RTFTextBox.SetFocus
288 ABC Library Reference

SetText (place text into rich text control)

SetText(text, [allowundo], [startpos], [endpos])

SetText Place indicated text into rich text control.

text A string constant or variable containing the text to place in the rich text control.

allowundo A numeric constant, variable, EQUATE, or expression that determines whether

the placement of text action is saved into the undo buffer. This allows the undo
method to be called for this action. A one (1 or True) allows an undo for this
action; a zero (0 or False) does not allow an undo for this action. The default
value is False.

startpos An integer constant or variable that specifies the starting character position to
place the text to.

endpos An integer constant or variable that specifies the ending character position to to
place the text to.
The SetText method is used to place the text to a specified position within the a rich text control. The text to place comes
from the specified string or variable. If the start and end positions are not available the current cursor position is used.

Example:
oRTF_RTFTextBox.SetText(loc:find,0,) !place text at current position
oRTF_RTFTextBox.SetText(loc:find,10,20) !place text at specified position
cwRTFClass 289

ShowControl (hide/unhide RTF control)

ShowControl(showstate)

ShowControl Hide/Unhide RTF control

showstate A numeric constant, variable, EQUATE, or expression that indicates whether the
RTF control is displayed or hidden. A one (1 or True) unhides the control; a zero
(0 or False) hides the control.
The ShowControl method is used hide or unhide the RTF control. When hidden, the ruler bar is also hidden.

Example:
oRTF_RTFTextBox.ShowControl( 0 ) ! Hide control
oRTF_RTFTextBox.ShowControl( 1 ) ! Unhide control

Undo (undo action)

Undo
The Undo method is used to undo (reverse) the action previously taken on the rich text control.

Example:
oRTF_RTFTextBox.Undo()!Undo previous change to rich text control
290 ABC Library Reference

DbAuditManager
DbAuditManager Overview
The DbAuditManager class declares an audit manager that consistently handles all database auditing operations. This
class provides methods that create and update an audit log file.

Relationship to Other Application Builder Classes

The DbAuditManager class uses the DbFileManager to handle the opening of the log file. This also takes care of any
errors that may occur when opening the file. The DbAuditManager class uses the DbChangeManager class to update the
audit log file.

This class also implements the DbdChangeAudit interface. This interface aids in the update of the log file.

DbAuditManager ABC Template Implementation

The DbAuditManager class is used in an application when the Global Database Auditing extension is added to the
application. The ABC Templates instantiate the DbAuditManager class in the global module of the application where the
class is also initialized.

The DbAuditManager class implements the IDbdChangeAudit interface.

DbAuditManager Source Files

The DbAuditManager source code is installed by default to the Clarion \LIBSRC folder. The specific DbAuditManager
source code and their respective components are contained in:

ABFILE.INC DbAuditManager declarations

ABFILE.CLW DbAuditManager method definitions
DbAuditManager 291

DbAuditManager Properties
The DbAuditManager contains the following properties:

Action (log file action column)

Action STRING(20)
The Action property contains a string that is used to update the Action column in the audit log file. The action column
show the type of update that was performed on the data file.

Implementation: The Action property is set by the OnInsert, OnDelete, OnChange, and BeforeChange methods. It is
used to update the log file by the AddLogFile method.

See Also: OnInsert, OnDelete, OnChange, and BeforeChange, AddLogFile

ColumnInfo (log file column queue)

ColumnInfo &DbColumnQueue, PROTECTED
The ColumnInfo property is a reference to a structure that is the source of the data that is added to the audit log file.

Implementation: The ColumnInfo queue is initialized by the Init method and updated by the AddItem method.

See Also: AddItem, AppendLog, CreateHeader, Init, Kill

LogFiles (log file queue)

LogFiles &LogFileQueue, PROTECTED
The LogFiles property is a reference to a structure that keeps track of all audit log files.

Implementation: The LogFiles queue is initialized by the Init method and updated by the AddLogFile method.

See Also: AddLogFile, Init, Kill, SetFm, OpenLogFile

292 ABC Library Reference

FM (DbLogFileManager object)

LFM &DbLogFileManager, PROTECTED

The LFM property is a reference to the DbLogFileManager object that creates and opens the various audit log files.

Implementation: The LFM property is intialized in the Init method.

See Also: AppendLog, CreateHeader, Init, Kill, OpenLogFile

Errors (ErrorClass object)

Errors &ErrorClass, PROTECTED

The Errors property is a reference to the ErrorClass object that handles unexpected conditions for the DbAuditManager. In
an ABC Template enerated program, the ErroClass object is called GlobaErros by default.

Implementation: The Init method initializes the Errors property.

See Also: Init, OpenLogFile

DbAuditManager 293

DbAuditManager Methods
The DbAuditManager class contains the following methods:

AddItem (maintain the columninfo structure)

AddItem(filename, fieldname, field, fieldheader, fieldpicture)

AddItem Adds fields to the columninfo structure so they can be monitored in the audit log
file.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is to be audited.

fieldname A string constant, variable, EQUATE, or expression containing the label of the
field that is to be audited.

field The fully qualified label for the FILE field.

fieldheader A string constant, variable, EQUATE, or expression containing the field header
(title) field that is to be audited. This is the column header that will appear in the
audit log file.

fieldpicture A string constant, variable, EQUATE, or expression containing the picture of the
field that is to be audited. This defines how the column in the audit log file will be
formatted.
The AddItem method maintains the ColumnInfo queue by updating it with field information needed to create and update
the log file.

Implementation: This method is called one time for each field that will appear in the log file. There is one extra column
that always appears in the log file. This is the action column that defines the update action that
occurred to cause the log file update.

See Also: AddLogFile

294 ABC Library Reference

AddLogFile (maintain log file structure)

AddLogFile(filename, logfilename)

AddLogFile Maintain the log file queue.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is to be audited.
logfilename A string constant, variable, EQUATE, or expression containing the audit log file
name.
The AddLogFile method maintains the LogFiles structure in order to keep track of each log file and its associated data
file.

Implementation: In template generated code, the AddLogFile method is called after the DbAuditManager object is
initialized. This method should be a called once for each file being auditied.

AppendLog (initiate audit log file update)

AppendLog(filename)

AppendLog Initiate audit log file update.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is to be audited.
The AppendLog method initiates the audit log file update by retrieving the field information and setting the date and time
of the update. This information is added to the log file by the FileManager.

See Also: LFM

DbAuditManager 295

BeforeChange (update audit log file before file change)

BeforeChange(filename, BFP), VIRTUAL

BeforeChange
filename A string constant, variable, EQUATE, or expression containing the label of the file
that is to be audited.
BFP The label of a BufferedPairsClass object. See BufferedPairsClass for more
information.
The BeforeChange method saves the values of the record before a change is made. These values are used for
comparison after the record is saved back to disk.

Implementation: The BeforeChange method sets the Action property and saves the current field values to the log file.
This method is called from the DbChangeManager.CheckChanges method.

See Also: BufferedPairsClass, DbChangeManager.CheckChanges

CreateHeader (create log file header records)

CreateHeader(filename, LFM), VIRTUAL

CreateHeader Create the header records in the audit log file.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is to be audited.
LFM The label of the log file's DbLogFileManager object.
The CreateHeader method updates the audit log file just after file creation. It adds header records to the log file which
serve as column heading information. The header includes the Date, Time, Action, and Field header.

Implementation: The CreateHeader method is called by the OpenLogFile method.

See Also: OpenLogFile

296 ABC Library Reference

Init (initialize the DbAuditManager object)

Init(error handler), VIRTUAL

Init Initializes the DbAuditManager object

error handler The label of an ErrorClass object. See Error Class for more information.
The Init method initializes the DbAuditManager object. The error handler object, ColumnInfo, LogFiles, and LFM
properties are initialized at this time.

Implementation: In template generated code, the Init method is called in the main application module. It is called with
the GlobalErrors error handler.

Kill (shut down DbAuditManger object)

Kill, VIRTUAL
The Kill method frees any memory allocated during the life of the object and does any other required termination code.

Implementation: The Kill method frees memory allocated to the ColumnInfo, LogFiles, and LFM properties.
DbAuditManager 297

OnChange (update audit log file after a record change)

OnChange(filename, file), VIRTUAL

OnChange Initiates an update to the audit log file after a Change to the file.
filename A string constant, variable, EQUATE, or expression containing the label of the file
that is to be audited.
file The label of the FILE being auditied.
The OnChange method initiates the update to the audit log file after a Change action.

Implementation: The OnChange method sets the Action property and calls the AppendLog method. This method is
called from the DbChangeManager.CheckChanges method.

See Also: DbChangeManager.CheckChanges

OnDelete (update audit log file when a record is deleted)

OnDelete(filename, file), VIRTUAL

OnDelete Initiates an update the audit log file on a Delete action.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is to be audited.
file The label of the FILE being auditied.
The OnDelete method initiates the update to the audit log file on a Delete action.

Implementation: The OnDelete method sets the Action property and calls the AppendLog method. This method is
called from the RelationManager's Delete method.

See Also: RelationManager.Delete

298 ABC Library Reference

OnFieldChange (virtual method for each field change)

OnFieldChange(left, right, fieldname, filename), VIRTUAL

OnFieldChange Manage field changes.

left The label of the "left" field of the pair that contains the original value of the field
being updated. The field may be any data type, but may not be an array.
right The label of the "right" field of the pair that contains the new value of the field
being updated. The field may be any data type, but may not be an array.
fieldname A string constant, variable, EQUATE, or expression containing the label of the
field that is to be audited.
filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
The OnFieldChange method is called for each field in the record that has changed. The before and after values are
passed to this method.

Implementation: OnFieldChange is a VIRTUAL method so that other base class methods can directly call the
OnFieldChange virtual method in a derived class. This lets you easily implement your own custom
version of this method.

See Also: DbChangeManager.CheckPair

DbAuditManager 299

OnInsert (update audit log file when a record is added)

OnInsert(filename, file), VIRTUAL

OnInsert Initiates an update the audit log file on an Insert action.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is to be audited.
file The label of the FILE being auditied.
The OnInsert method initiates the update to the audit log file on an Insert action.

Implementation: The OnInsert method sets the Action property and calls the AppendLog method. This method is
called from the FileManager's Insert method.

See Also: FileManager.Insert

OpenLogFile (open the audit log file)

OpenLogFile(filename), PROTECTED

OpenLogFile Opens the audit log file.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
The OpenLogFile method opens the audit log file that is to be updated. If the log file does not already exist, the file is
created and the headers are added to it.

Implementation: This method is called by the AppendLog method to ensure the log file exists before trying to update it.

See Also: AppendLog, DbLogFileManager class

300 ABC Library Reference

SetFM (determine log file status)

SetFM(filename), PROTECTED

SetFM Determines log file status.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
The SetFM method is used to determine if the log file has been initialized by the AddLogFile method.

A one (1 or True) value is returned if the log file has been correctly initialized into the LogFiles structure; a zero (0 or
False) is returned otherwise.

Implementation: The SetFM method is called by the AddItem and AppendLog methods.

Return Data Type: BYTE

See Also: AddItem, AppendLog

DbAuditManager 301
302 ABC Library Reference

DbChangeManager
DbChangeManager Overview
The DbChangeManager class declares an audit manager that consistently handles all database change operations.

Relationship to Other Application Builder Classes

The DbChangeManager class works in conjunctions with the DbAuditManager class and the IDbChangeManager
interface.

DbChangeManager ABC Template Implementation

The DbChangeManager class is used in an application when the Global Database Auditing extension is added to the
application. The ABC Templates instantiate the DbChangeManager class in the global module of the application where
the class is also initialized.

DbChangeManager Source Files

The DbChangeManager source code is installed by default to the Clarion \LIBSRC folder. The specific
DbChangeManager source code and their respective components are contained in:

ABFILE.INC DbChangeManager declarations

ABFILE.CLW DbChangeManager method definitions
DbChangeManager 303

DbChangeManager Properties
The DbChangeManager contains the following properties:

NameQueue (pointer into trigger queue)

NameQueue &DbNameQueue, PROTECTED

The NameQueue property keeps track of the file and field names when a change is made to a file that is being audited.
The NameQueue queue entry also points into the trigger queue for the change data.

Implementation: The NameQueue structure is updated in the DbChangeManager.AddItem method. This queue
contains a pointer into the TriggerQueue.

See Also: DbChangeManager.Init, DbChangeManager.Kill, DbChangeManager.AddItem,

DbChangeManager.CheckPair

TriggerQueue (pointer to BFP for field changes)

TriggerQueue &DbTriggerQueue, PROTECTED

The TriggerQueue property contains the field change information by managing the BufferFieldPairs structure.
304 ABC Library Reference

DbChangeManager Methods
The DbChangeManager class contains the following methods:

AddItem (maintain the namequeue structure)

AddItem(left, name, filename)

AddItem Maintains the namequeue structure.

left The label of the "left" field of the pair that contains the original value of the field
being updated. The field may be any data type, but may not be an array.
name A string constant, variable, EQUATE, or expression containing the label of the
field that is to be audited.
filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
The AddItem method maintains the NameQueue structure by updating it with field information needed to track before and
after file changes.

Implementation: This method is called one time for each field that will appear in the log file.

AddThread (maintains the triggerqueue)

AddThread(filename)

AddThread Maintains the TriggerQueue.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
The AddThread method maintains the TriggerQueue by updating it with the current thread number and an instance of
the BufferedPairsClass.
DbChangeManager 305

CheckChanges(check record for changes)

CheckChanges(filename, file)

CheckChanges Checks the record for changes.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
file The label of the FILE being auditied.
The CheckChanges method checks to see if there were any changes made to the columns in the audited file. This
method calls the CheckPairs method to compare the before and after field values of the audited file.

See Also: DbChangeManagerBeforeChange, IDbChangeManagerOnChange, DbChangeManager.CheckPair

CheckPair(check field pairs for changes)

CheckPair(FP)

CheckPairs Checks fields for changes.

FP The label of a FieldPairsClass object. See FieldPairsClass for more information.
The CheckPair method compares the before and after values of a field to see if there were changes made. This is
needed to know whether to update the audit log file.
306 ABC Library Reference

Equal(checks for equal before and after values)

Equal(filename)

Equal Compares before and after values of fields.

filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
The Equal method returns one (1) if all pairs are equal and returns zero (0) if any pairs are not equal.

Implementation: The Equal method simply calls FieldPairsClass.Equat method which calls the
FieldPairsClass.EqualLeftRight method which in turn does all the comparison work.

Return Data Type: BYTE

See Also: FieldPairsClass.Equal

Init (initialize the DbChangeManager object)

Init(IDBC), VIRTUAL

Init Initializes the DbChangeManager object

IDBC The label of an IDbChangeManager interface. See IDbChangeManager for more
information.
The Init method initializes the DbChangeManager object. The TriggerQueue and NameQueue are also initialized at this
time.

Implementation: In template generated code, the Init method is called in the main application module.
DbChangeManager 307

Kill (shut down DbChangeManger object)

Kill, VIRTUAL
The Kill method frees any memory allocated during the life of the object and does any other required termination code.

Implementation: The Kill method frees memory allocated to the NameQueue and TriggerQueue structures.

SetThread (read triggerqueue)

SetThread(filename)

SetThread Reads the TriggerQueue for the specified file and current thread.
filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
The SetThread method reads the TriggerQueue for the specified file and current thread. If a matching entry is found in
the queue a one (1 or True) is returned; if an entry is not found in the TriggerQueue a zero (0 or False) is returned.

Return Data Type: BYTE

308 ABC Library Reference

Update (update the audit log file buffer)

Update(filename)

Update
filename A string constant, variable, EQUATE, or expression containing the label of the file
that is audited.
The Update method calls the BufferFieldPairs class to update the record buffer with the changes made in order for the
audit log file to be updated with the before and after values.

See Also: BFP.AssignLeftToRight

DbChangeManager 309
310 ABC Library Reference

DbLogFileManager
DbLogFileManager Overview
The DbLogFileManager class declares a file manager that consistently handles the routine database operations on the
audit log file. The DbLogFileManager is derived from the FileManager class.

Relationship to Other Application Builder Classes

The DbLogFileManager class is derived from the FileManager class. This class inherits all FileManager class properties
and methods. The DbLogFileManager also relies on the ErrorClass for most of its error handling.

DbLogFileManager ABC Template Implementation

The DbLogFileManager class is instantiated by the DbAuditManager LFM property in the DbAuditManager.Init method.

DbLogFileManager Source Files

The DbLogFileManager source code is installed by default to the Clarion \LIBSRC folder. The specific
DbLogFileManager source code and their respective components are contained in:

ABFILE.INC DbLogFileManager declarations

ABFILE.CLW DbLogFileManager method definitions
DbLogFileManager 311

DbLogFileManager Properties
DbLogFileManager Properties
The DbLogFileManager inherits all the properties of the FileManager class from which it is derived. See FileManager
Properties for more information.

In addition to the inherited properties, the DbLogFileManager contains the following properties:

Opened (file opened flag)

Opened BYTE
The Opened property indicates whether the DbLogFileManager's FILE (the log file) has been opened. A value of one (1
or True) indicates the FILE is open; a value of zero (0 or False) indicates the FILE is not opened.
312 ABC Library Reference

DbLogFileManager Methods
DbLogFileManager Methods
The DbLogFileManager inherits all the methods of the FileManager class from which it is derived. See FileManager
Methods for more information.

In addition to the inherited methods, the DbLogFileManager contains the following methods:

Init (initialize the DbLogFileManager object)

Init(errorclass, logfilename), VIRTUAL

Init Initializes the DbAuditManager object

errorclass The label of an ErrorClass object. See Error Class for more information.
logfilename A string constant, variable, EQUATE, or expression that contains the audit log file
name.
The Init method initializes the DbLogFileManager object.
DbLogFileManager 313
314 ABC Library Reference

EditClass
EditClass Overview
The EditClass lets you implement a dynamic edit-in-place control for each column in a LIST. The EditClass is an abstract
class--it is not useful by itself, but serves as the foundation and framework for its derived classes. See EditCheckClass,
EditColorClass, EditFileClass, EditDropListClass, EditFontClass, and EditMultiSelectClass.

EditClass Concepts
The EditClass creates an input control (CHECK, ENTRY, SPIN, COMBO, etc.), accepts input from the end user, then
returns the input to a specified variable, typically the variable associated with a specific LIST cell--a field in the LIST
control's data source QUEUE. The EditClass also signals the calling procedure whenever significant edit-in-place events
occur, such as tabbing to a new column, cancelling the edit, or completing the edit (moving to a new record or row). The
EditClass provides virtual methods (TakeEvent) to allow you to take control of significant edit-in-place events.

The BrowseClass (AskRecord method) uses the EditClass to accomplish edit-in-place data entry by assigning the
EditClass input control to a specific LIST cell--see BrowseClass.AskRecord.

Relationship to Other Application Builder Classes

Derived Classes

The EditClass serves as the foundation and framework for its derived classes. See EditCheckClass, EditColorClass,
EditEntryClass, EditFileClass, EditFileDropClass, EditFontClass, and EditMultiSelectClass. These derived classes each
provide a different type of input control or input user interface. You can control the values returned by these derived
EditClass objects by using their virtual methods. See the Conceptual Example.

BrowseClass
The EditClass is loosely integrated into the BrowseClass. The BrowseClass depends on the EditClass operating
according to this chapter's specification; however, the EditClass may be called by non-BrowseClass procedures and
objects.
The BrowseClass.AskProcedure property indicates whether the BrowseClass object uses the EditClass for updates.
The BrowseClass.AskRecord method is the engine for the edit-in-place functionality. This method uses the EditClass to
dynamically create the Edit-in-place control upon request (Insert, Change, or Delete) by the end user. When the end user
moves off the edited record (enter key, click on another item) the AskRecord method saves or deletes the record and
uses the EditClass to destroy the Edit-in-place control.
EditClass 315

ABC Template Implementation

The BrowseUpdateButtons template generates references to EditClass objects as needed. One check box on the
BrowseUpdateButtons control template enables default edit-in-place support for a given BrowseBox--any associated Form
(update) procedure then becomes redundant.

If you accept the BrowseUpdateButtons default edit-in-place behavior, the generated code does not reference the
EditClass, because the default edit-in-place behavior is implemented in the BrowseClass (see BrowseClass.AskRecord),
and no additional generated code is needed.

If you use custom (Configure EditInPlace) edit-in-place behavior, the BrowseUpdateButtons template generates the
code to instantiate the requested object (derived from the EditClass) and register the object with the BrowseClass object.
The BrowseClass object then calls the registered EditClass object's methods as needed. See Control Templates--
BrowseUpdateButtons for more information.

EditClass Source Files

The EditClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditClass source code and
their respective components are contained in:

ABEIP.INC EditClass declarations

ABEIP.CLW EditClass method definitions
ABEIP.TRN EditClass translation strings
316 ABC Library Reference

EditClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate several
EditClass objects and a related BrowseClass object. The example page-loads a LIST of fieldnames and associated
control attributes (such as color, icon, etc.), then edits the list items with a variety of edit-in-place objects. Note that the
BrowseClass object calls the "registered" EditClass objects' methods as needed.
PROGRAM
_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)
INCLUDE('ABWINDOW.INC') !declare WindowManager
INCLUDE('ABBROWSE.INC') !declare BrowseClass
INCLUDE('ABEIP.INC') !declare Edit-in-place classes
MAP
END

Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
ControlType STRING(12)
END
END
PropView VIEW(Property)
END

PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color)
PR:ControlType LIKE(PR:ControlType)
PR:Hidden LIKE(PR:Hidden)
PR:IconFile LIKE(PR:IconFile)
ViewPosition STRING(1024)
END

PropWindow WINDOW('Browse Field Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
'60L(2)|_M~Control Type~@s12@' &|
'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END

Edit:PR:FieldName EditEntryClass !declare Edit:PR:FieldName-EIP ENTRY control

Edit:PR:Color CLASS(EditColorClass) !declare Edit:PR:Color-EIP color dialog

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END

Edit:PR:Hide CLASS(EditCheckClass) !declare Edit:PR:Color-EIP CHECK control

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END
Edit:PR:IconFile CLASS(EditFileClass)!declare Edit:PR:IconFile-EIP file dialog
Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END
EditClass 317

Edit:PR:ControlType CLASS(EditDropListClass) !declare Edit:PR:ContolType -EIP droplist

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END

BRW1 CLASS(BrowseClass) !declare BRW1, the BrowseClass object

Q &PropQ ! that drives the EditClass objects--
END ! i.e. calls Init, TakeEvent, Kill

GlobalErrors ErrorClass
Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END
GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD
CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
?PropList{PROP:LineHeight}=12 !enlarge rows to accomodate EditClass icons
BRW1.Q &= PropQ
BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName)
BRW1.AddField(PR:Color,BRW1.Q.PR:Color)
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden)
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile)
BRW1.AddEditControl(Edit:PR:FieldName,1) !Register Edit:PR:FieldName with BRW1
BRW1.AddEditControl(Edit:PR:Color,2) !Register Edit:PR:Color with BRW1
BRW1.AddEditControl(Edit:PR:ControlType,3)!Register Edit:PR:ControlType with BRW1
BRW1.AddEditControl(Edit:PR:Hide,4) !Register Edit:PR:Hide with BRW1
BRW1.AddEditControl(Edit:PR:IconFile,5) !Register Edit:PR:IconFile with BRW1
318 ABC Library Reference

BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
RETURN ReturnValue

Edit:PR:Color.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Title='Select field color' !set EIP color dialog title

Edit:PR:Hide.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Feq{PROP:Text}='Hide ' !set EIP check box text
SELF.Feq{PROP:Value,1}='Y' !set EIP check box true value
SELF.Feq{PROP:Value,2}='N' !set EIP check box false value

Edit:PR:IconFile.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Title='Select icon file' !set EIP file dialog title
SELF.FilePattern='Icon files *.ico|*.ico' !set EIP file dialog file masks
SELF.FileMask=FILE:KeepDir+FILE:LongName !set EIP file dialog behavior flag

Edit:PR:ControlType.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Feq{PROP:From}='ENTRY|SPIN|TEXT|STRING' !set ControlType droplist choices

Access:Property.Init PROCEDURE !initialize FileManager

CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)

Relate:Property.Init PROCEDURE !initialize RelationManager

CODE
Access:Property.Init
PARENT.Init(Access:Property,1)

Relate:Property.Kill PROCEDURE !shut down RelationManager

CODE
Access:Property.Kill
PARENT.Kill
EditClass 319

EditClass Properties
The EditClass contains the following properties.

FEQ (the edit-in-place control number)

FEQ UNSIGNED
The FEQ property contains the control number of the edit-in-place control.

The CreateControl method sets the value of the FEQ property when it creates the control.

See Also: CreateControl

ReadOnly ( edit-in-place control is read-only)

ReadOnly BYTE
The ReadOnly property is a flag indicating that the edit-in-place control is not editable.

See Also: SetReadOnly

320 ABC Library Reference

EditClass Methods
Functional Organization--Expected Use
As an aid to understanding the EditClass, it is useful to organize its methods into two large categories according to their
expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of the
EditClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitV initialize the EditClass object
Kill V shut down the EditClass object

Mainstream Use:
TakeEventV handle events for the edit control

Occasional Use:
CreateContolV a virtual to create the edit control
SetAlertsV alert appropriate keystrokes for the edit control

V These methods are also virtual.

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

Init initialize the EditClass object

CreateContol a virtual to create the edit control
SetAlerts alert appropriate keystrokes for the edit control
TakeAccpted handle accepted events for the edit control
TakeEventV handle events for the edit control
Kill shut down the EditClass object
EditClass 321

CreateControl (a virtual to create the edit control)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method is a virtual placeholder to create the appropriate window control for derived classes.

Implementation: The Init method calls the CreateControl method. The CreateControl method must set the value of the
FEQ property.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditCheckClass.CreateControl, EditColorClass.CreateControl, EditEntryClass.CreateControl,

EditFileClass.CreateControl, EditDropListClass.CreateControl, EditMultiSelectClass.CreateControl
322 ABC Library Reference

Init (initialize the EditClass object)

Init( column, listbox, editedfield ), VIRTUAL

Init Initializes the EditClass object.

column An integer constant, variable, EQUATE, or expression that contains the edited
column number of the listbox.
listbox An integer constant, variable, EQUATE, or expression that contains the control
number of the edited LIST control--typically a BrowseClass object's LIST.
editedfield The fully qualifiedlabel of the edited field--typically a field in the BrowseClass
object's QUEUE.
The Init method initializes the EditClass object.

Implementation: The BrowseClass.AskRecord method calls the Init method. The Init method creates the edit-in-place
control, loads it with the selected list item's data, and alerts the appropriate edit-in-place navigation
keys.

Example:
MyEditClass.Init(1,?MyList,StateQ:StateCode) !initialize EditClass object
!program code
MyEditClass.Kill !shut down EditClass object

See Also: BrowseClass.AskRecord

EditClass 323

Kill (shut down the EditClass object)

Kill, VIRTUAL
The Kill method frees any memory allocated during the life of the object and performs any other required termination
code. The Kill method must leave the object in an Initable state.

Implementation: The BrowseClass.AskRecord method calls the Kill method. The Kill method destroys the edit-in-place
control created by the Init method.

Example:
MyEditClass.Init(1,?MyList,StateQ:StateCode) !initialize EditClass object
!program code
MyEditClass.Kill !shut down EditClass object

See Also: BrowseClass.AskRecord

SetAlerts (alert keystrokes for the edit control)

SetAlerts, VIRTUAL
The SetAlerts method method alerts appropriate keystrokes for the edit-in-place control.

Implementation: The Init method calls the CreateControl method to create the input control and set the FEQ property.
The Init method then calls the SetAlerts method to alert standard edit-in-place keystrokes for the edit
control. Alerted keys are:
TabKey !next field
ShiftTab !previous field
EnterKey !complete and save
EscKey !complete and cancel
DownKey !complete and save, then edit next row
UpKey !complete and save, then edit prior row
Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: Init

324 ABC Library Reference

SetReadOnly (set edit control to read-only)

SetReadOnly( state ), VIRTUAL

SetReadOnly The SetReadOnly method places the edit-in-place control in a read-only state.
state An integer constant, variable, EQUATE, or expression that indicates whether to
disable a droplist control's dropdown button. A value of one (1 or True) disables the
button. A value of zero (0 or False) has no effect on the control.
Implementation: The SetReadOnly method uses PROP:ReadOnly to place the edit-in-place conrol in a read-only
state. After the parent call in the Init method of the EditInPlace object is the recommended place to
call SetReadonly.

Example:
EditInPlace::CUS:Number.SetReadOnly()

See Also: ReadOnly, EditDropListClass.SetReadOnly

TakeAccepted (validate EIP field)

TakeAccepted (Action), VIRTUAL

The TakeAccepted method processes the accepted EIP field value and returns a value indicating whether to continue
editing or to complete the field. If the EIPManager Class attribute SELF.REQ is TRUE, the field will be required, and the
row can not be accepted if the field is blank. If the TakeAccepted method returns the EditAction:Cancel equate, the EIP
wil remain on the current field.

Return Data Type: BYTE

See Also: EIPManager.TakeAcceptAll

EditClass 325

TakeEvent (process edit-in-place events)

TakeEvent( event ), VIRTUAL

TakeEvent Processes an event for the EditClass object.

event An integer constant, variable, EQUATE, or expression that contains the event
number (see EVENT in the Language Reference).
The TakeEvent method processes an event for the EditClass object and returns a value indicating the user requested
action. Valid actions are none, complete or OK, cancel, next record, previous record, next field, and previous field.

Implementation: The BrowseClass.AskRecord method calls the TakeEvent method. The TakeEvent method process
an EVENT:AlertKey for the edit-in-place control and returns a value indicating the user requested
action. The BrowseClass.AskRecord method carries out the user requested action.

Corresponding EQUATEs for the possible edit-in-place actions are declared in ABBROWSE.INC as
follows:
EditAction ITEMIZE(0),PRE
None EQUATE ! no action
Forward EQUATE ! next field
Backward EQUATE ! previous field
Complete EQUATE ! OK
Cancel EQUATE ! cancel
Next EQUATE ! next record
Previous EQUATE ! previous record
END

Return Data Type: BYTE

Example:
EditClassAction ROUTINE
CASE SELF.EditList.Control.TakeEvent(EVENT())
OF EditAction:Forward
!handle tab forward (new field, same record)
OF EditAction:Backward
!handle tab backward (new field, same record)
OF EditAction:Next
!handle down arrow (new record, offer to save prior record)
OF EditAction:Previous
!handle up arrow (new record, offer to save prior record)
OF EditAction:Complete
!handle OK or enter key (save record)
OF EditAction:Cancel
!handle Cancel or esc key (restore record)
END

See Also: BrowseClass.AskRecord

326 ABC Library Reference

EditSpinClass
EditSpinClass--Overview
The EditSpinClass is an EditClass that supports a SPIN control. The EditSpinClass lets you implement a dynamic edit-in-
place SPIN control for a column in a LIST.

EditSpinClass Concepts
The EditSpinClass creates a SPIN control, accepts input from the end user, then returns the input to the variable specified
by the Init method, typically the variable associated with a specific LIST cell--a field in the LIST control's data source
QUEUE. The EditSpinClass also signals the calling procedure whenever significant edit-in-place events occur, such as
tabbing to a new column, cancelling the edit, or completing the edit (moving to a new record or row). The EditSpinClass
provides a virtual TakeEvent method to let you take control of significant edit-in-place events.

EditSpinClass -- Relationship to Other Application Builder Classes

EditClass

The EditSpinClass is derived from the EditClass. The EditClass serves as the foundation and framework for its derived
classes. These derived classes each provide a different type of input control or input user interface. You can control the
values returned by these derived EditClass objects by using their virtual methods. See the Conceptual Example.

BrowseEIPManagerClass

The EditClass is managed by the BrowseEIPManagerClass. The BrowseEIPManagerClass depends on the EditClass
operating according to it's documented specifications; however, the EditClass may be called by non-BrowseClass
procedures and objects.

EditSpinClass--ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditSpinClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The BrowseClass
object then calls the registered EditSpinClass object's methods as needed. See Control Templates--
BrowseUpdateButtons for more information. EditSpinClass Source Files

The EditSpinClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditSpinClass source
code and their respective components are contained in:

ABEIP.INC EditSpinClass declarations

ABEIP.CLW EditSpinClass method definitions
EditSpinClass 327

EditSpinClass--Conceptual Example
The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditSpinClass object and a related BrowseClass object. The example page-loads a LIST of actions and associated
attributes (priority and completed), then edits the "Priority" items with an EditSpinClass object. Note that the BrowseClass
object calls the "registered" EditSpinClass object's methods as needed.

Note: The EditSpinClass requires values for PROP:RangeLow, PROP:RangeHigh, and PROP:Step to function
correctly. The EditSpinClass.Init method is the proper place to set these properties. See SPIN in the
Language Reference for more information.
PROGRAM
_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)
INCLUDE('ABWINDOW.INC'),ONCE
INCLUDE('ABEIP.CLW'),ONCE
INCLUDE('ABBROWSE.CLW'),ONCE
MAP
END
Actions FILE,DRIVER('TOPSPEED'),PRE(ACT),CREATE,BINDABLE,THREAD
KeyAction KEY(ACT:Action),NOCASE,OPT
Record RECORD,PRE()
Action STRING(20)
Priority DECIMAL(2)
Completed DECIMAL(1)
END
END
ViewActions VIEW(Actions)
END
ActQ QUEUE
ACT:Action LIKE(ACT:Action)
ACT:Priority LIKE(ACT:Priority)
ACT:Completed LIKE(ACT:Completed)
ViewPosition STRING(1024)
END

ActionWindow WINDOW('Actions File'),AT(,,164,144),IMM,SYSTEM,GRAY|

LIST,AT(8,6,148,115),USE(?List),IMM,HVSCROLL,FORMAT('80L(2)|~Action~'&|
'@S20@31C|~Priority~@N2@40L(2)|~Done~L(0)@N1@'),FROM(ActQ)
BUTTON('&Insert'),AT(10,126,45,14),USE(?Insert:2)
BUTTON('&Change'),AT(59,126,45,14),USE(?Change:2),DEFAULT
BUTTON('&Delete'),AT(108,126,45,14),USE(?Delete:2)
END
ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,DERIVED
Kill PROCEDURE(),BYTE,PROC,DERIVED
END
BRW1 CLASS(BrowseClass)
Q &ActQ
END

Edit:ACT:Priority CLASS(EditSpinClass) ! Edit-in-place class for field ACT:Priority

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),DERIVED
END
328 ABC Library Reference

CODE
GlobalResponse = ThisWindow.Run()

ThisWindow.Init PROCEDURE
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue =PARENT.Init()
IF ReturnValue THEN RETURN ReturnValue.
SELF.FirstField = ?List
SELF.Errors &= GlobalErrors
CLEAR(GlobalRequest)
CLEAR(GlobalResponse)
Relate:Actions.Open
FilesOpened = True
BRW1.Init(?List,ActQ.ViewActions,BRW1::ViewActions,ActQ,Relate:Actions,SELF)
OPEN(ActionWindow)
SELF.Opened=True
BRW1.Q &= ActQ
BRW1.AddSortOrder(ACT:KeyAction)
BRW1.AddField(ACT:Action,BRW1.Q.ACT:Action)
BRW1.AddField(ACT:Priority,BRW1.Q.ACT:Priority)
BRW1.AddField(ACT:Completed,BRW1.Q.ACT:Completed)
BRW1.AddEditControl(EditInPlace::ACT:Priority,2) !Add cutom edit-inplace class
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert:2
BRW1.ChangeControl=?Change:2
BRW1.DeleteControl=?Delete:2
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE
ReturnValue BYTE,AUTO
CODE
ReturnValue =PARENT.Kill()
IF ReturnValue THEN RETURN ReturnValue.
IF FilesOpened
Relate:Actions.Close
END
RETURN ReturnValue

Edit:ACT:Priority.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.FEQ{PROP:RANGE,1} = 1 !Set the Low Range for the Spinbox
SELF.FEQ{PROP:RANGE,2} = 10 !Set the High Range for the Spinbox
SELF.FEQ{PROP:Step} = 1 !Set the incremental steps of the Spinbox
EditSpinClass 329

EditSpinClass Properties
EditSpinClass Properties
The EditSpinClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties and
EditClass Concepts for more information.
330 ABC Library Reference

EditSpinClass Methods
EditSpinClass Methods
The EditSpinClass inherits all the methods of the EditClass from which it is derived. See EditClass Methods and EditClass
Concepts.

EditSpinClass--Functional Organization--Expected Use

As an aid to understanding the EditSpinClass it is useful to organize its methods into two large categories according to
their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EditSpinClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitVI initialize the EditSpinClass object
KillVI shut down the EditSpinClass object

Mainstream Use:
TakeEventVI handle events for the SPIN control

Occasional Use:
CreateContolV create the SPIN control
SetAlertsVI alert keystrokes for the SPIN control

V These methods are also virtual.

I These methods are inherited from the EditClass

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

InitI initialize the EditSpinClass object

CreateContol create the SPIN control
SetAlertsI alert keystrokes for the SPIN control
TakeEventI handle events for the SPIN control
KillI shut down the EditSpinClass object
EditSpinClass 331

CreateControl (create the edit-in-place SPIN control)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method creates the edit-in-place SPIN control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method sets the value of the FEQ
property. Use the Init method or the CreateControl method to set any required properties of the SPIN
control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

332 ABC Library Reference

EditCheckClass
EditCheckClass Overview
The EditCheckClass is an EditClass that supports a CHECK control. The EditCheckClass lets you implement a dynamic
edit-in-place CHECK control for a column in a LIST.

EditCheckClass Concepts
The EditCheckClass creates a CHECK control, accepts input from the end user, then returns the input to the variable
specified by the Init method, typically the variable associated with a specific LIST cell—a field in the LIST control's data
source QUEUE. The EditCheckClass also signals the calling procedure whenever significant edit-in-place events occur,
such as tabbing to a new column, cancelling the edit, or completing the edit (moving to a new record or row). The
EditCheckClass provides a virtual TakeEvent method to let you take control of significant edit-in-place events.

EditCheckClass Relationship to Other Application Builder Classes

EditClass

The EditCheckClass is derived from the EditClass. The EditClass serves as the foundation and framework for its derived
classes. These derived classes each provide a different type of input control or input user interface. You can control the
values returned by these derived EditClass objects by using their virtual methods. See the Conceptual Example.

BrowseClass

The EditClass is loosely integrated into the BrowseClass. The BrowseClass depends on the EditClass operating
according to it's documented specifications; however, the EditClass may be called by non-BrowseClass procedures and
objects.

EditCheckClass ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditCheckClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The
BrowseClass object then calls the registered EditCheckClass object's methods as needed. See Control Templates—
BrowseUpdateButtons for more information.

EditCheckClass Source Files

The EditCheckClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditCheckClass
source code and their respective components are contained in:

ABEIP.INC EditCheckClass declarations

ABEIP.CLW EditCheckClass method definitions
EditCheckClass 333

EditCheckClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditCheckClass object and a related BrowseClass object. The example page-loads a LIST of fieldnames and associated
control attributes (such as color, icon, etc.), then edits the "Hide" items with an EditCheckClass object. Note that the
BrowseClass object calls the "registered" EditCheckClass object's methods as needed.
PROGRAM
_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)
INCLUDE('ABWINDOW.INC') !declare WindowManager
INCLUDE('ABBROWSE.INC') !declare BrowseClass
INCLUDE('ABEIP.INC') !declare Edit-in-place classes

MAP
END
Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
ControlType STRING(12)
END
END

PropView VIEW(Property)
END

PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color)
PR:ControlType LIKE(PR:ControlType)
PR:Hidden LIKE(PR:Hidden) !edit this LIST field with a CHECK control
PR:IconFile LIKE(PR:IconFile)
ViewPosition STRING(1024)
END

PropWindow WINDOW('Browse Field Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
'60L(2)|_M~Control Type~@s12@' &|
'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END

Edit:PR:Hide CLASS(EditCheckClass) !declare Edit:PR:Color-EIP CHECK control

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END
334 ABC Library Reference

BRW1 CLASS(BrowseClass) !declare BRW1, the BrowseClass object

Q &PropQ ! that drives the EditClass objects--
END ! i.e. calls Init, TakeEvent, Kill

GlobalErrors ErrorClass
Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END

GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD
CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO

CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
BRW1.Q &= PropQ
BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName)
BRW1.AddField(PR:Color,BRW1.Q.PR:Color)
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden)
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile)
BRW1.AddEditControl(Edit:PR:Hide,4) !Use Edit:PR:Hide to edit BRW1 column 4
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
RETURN ReturnValue

Edit:PR:Hide.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

EditCheckClass 335

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Feq{PROP:Text}='Hide ' !set EIP check box text
SELF.Feq{PROP:Value,1}='Y' !set EIP check box true value
SELF.Feq{PROP:Value,2}='N' !set EIP check box false value

Access:Property.Init PROCEDURE !initialize FileManager

CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)

Relate:Property.Init PROCEDURE !initialize RelationManager

CODE
Access:Property.Init
PARENT.Init(Access:Property,1)

Relate:Property.Kill PROCEDURE !shut down RelationManager

CODE
Access:Property.Kill
PARENT.Kill
336 ABC Library Reference

EditCheckClass Properties
The EditCheckClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties and
EditClass Concepts for more information.
EditCheckClass 337

EditCheckClass Methods
The EditCheckClass inherits all the methods of the EditClass from which it is derived. See EditClass Methods and
EditClass Concepts.

In addition to (or instead of) the inherited methods, the EditCheckClass contains the following methods:

EditCheckClass Functional Organization—Expected Use

As an aid to understanding the EditCheckClass it is useful to organize its methods into two large categories according to
their expected use—the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EditCheckClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitVI initialize the EditCheckClass object
KillVI shut down the EditCheckClass object

Mainstream Use:
TakeEventVI handle events for the CHECK control

Occasional Use:
CreateContolV create the CHECK control
SetAlertsVI alert keystrokes for the CHECK control

V These methods are also virtual.

I These methods are inherited from the EditClass

Virtual Methods

Typically you will not call these methods directly—the Non-Virtual methods call them. However, we anticipate you will
often want to override these methods, and because they are virtual, they are very easy to override. These methods do
provide reasonable default behavior in case you do not want to override them.

InitI initialize the EditCheckClass object

CreateContol create the CHECK control
SetAlertsI alert keystrokes for the CHECK control
TakeEventI handle events for the CHECK control
Kill shut down the EditCheckClass object
338 ABC Library Reference

CreateControl (create the edit-in-place CHECK control)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method creates the edit-in-place CHECK control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method sets the value of the FEQ
property. Use the Init method or the CreateControl method to set any required properties of the
CHECK control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

EditCheckClass 339
340 ABC Library Reference

EditColorClass
EditColorClassOverview
The EditColorClass is an EditClass that supports the Windows Color dialog by way of a dynamic edit-in-place COMBO
control.

EditColorClass Concepts
The EditColorClass creates a COMBO control with an ellipsis button that invokes the Windows Color dialog. The
EditColorClass accepts a color selection from the end user, then returns the selection to the variable specified by the Init
method, typically the variable associated with a specific LIST cell--a field in the LIST control's data source QUEUE.

The EditColorClass also signals the calling procedure whenever significant edit-in-place events occur, such as tabbing to
a new column, cancelling the edit, or completing the edit (moving to a new record or row). The EditColorClass provides a
virtual TakeEvent method to let you take control of significant edit-in-place events.

EditColorClass Relationship to Other Application Builder Classes

EditClass

The EditColorClass is derived from the EditClass. The EditClass serves as the foundation and framework for its derived
classes. These derived classes each provide a different type of input control or input user interface. You can control the
values returned by these derived EditClass objects by using their virtual methods. See the Conceptual Example.

BrowseClass

The EditClass is loosely integrated into the BrowseClass. The BrowseClass depends on the EditClass operating
according to it's documented specifications; however, the EditClass may be called by non-BrowseClass procedures and
objects.

EditColorClass ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditColorClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The
BrowseClass object then calls the registered EditColorClass object's methods as needed. See Control Templates--
BrowseUpdateButtons for more information.

EditColorClass Source Files

The EditColorClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditColorClass source
code and their respective components are contained in:

ABEIP.INC EditColorClass declarations

ABEIP.CLW EditColorClass method definitions
ABEIP.TRN EditColorClass translation strings
EditColorClass 341

EditColorClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditColorClass object and a related BrowseClass object. The example page-loads a LIST of fieldnames and associated
control attributes (such as color, icon, etc.), then edits the "Color" items with an EditColorClass object. Note that the
BrowseClass object calls the "registered" EditColorClass object's methods as needed.
PROGRAM

_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)

INCLUDE('ABWINDOW.INC') !declare WindowManager

INCLUDE('ABBROWSE.INC') !declare BrowseClass
INCLUDE('ABEIP.INC') !declare Edit-in-place classes

MAP
END

Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
ControlType STRING(12)
END
END

PropView VIEW(Property)
END

PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color) !edit this LIST field with the color dialog
PR:ControlType LIKE(PR:ControlType)
PR:Hidden LIKE(PR:Hidden)
PR:IconFile LIKE(PR:IconFile)
ViewPosition STRING(1024)
END
342 ABC Library Reference

PropWindow WINDOW('Browse Field Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
'60L(2)|_M~Control Type~@s12@' &|
'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END

Edit:PR:Color CLASS(EditColorClass) !declare Edit:PR:Color-EIP color dialog

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END

BRW1 CLASS(BrowseClass) !declare BRW1, the BrowseClass object

Q &PropQ ! that drives the EditClass objects --
END ! i.e. calls Init, TakeEvent, Kill

GlobalErrors ErrorClass
Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END
GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD
CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill
EditColorClass 343

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
BRW1.Q &= PropQ
BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName)
BRW1.AddField(PR:Color,BRW1.Q.PR:Color)
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden)
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile)
BRW1.AddEditControl(Edit:PR:Color,2) !Use Edit:PR:Color to edit BRW1 column 2
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
RETURN ReturnValue

Edit:PR:Color.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Title='Select field color' !set EIP color dialog title

Access:Property.Init PROCEDURE !initialize FileManager

CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)

Relate:Property.Init PROCEDURE !initialize RelationManager

CODE
Access:Property.Init
PARENT.Init(Access:Property,1)

Relate:Property.Kill PROCEDURE !shut down RelationManager

CODE
Access:Property.Kill
PARENT.Kill
344 ABC Library Reference

EditColorClass Properties
EditColorClass Properties
The EditColorClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties for more
information.

In addition to the inherited properties, the EditColorClass contains the following properties:

Title (color dialog title text)

Title CSTRING(256)
The Title property contains a string that sets the title bar text in the Windows color dialog.

Implementation: The EditColorClass (TakeEvent method) uses the Title property as the title parameter to the
COLORDIALOG procedure. See COLORDIALOG in the Language Reference for more information.

See Also: TakeEvent

EditColorClass 345

EditColorClass Methods
EditColorClass Functional Organization--Expected Use
As an aid to understanding the EditColorClass it is useful to organize its methods into two large categories according to
their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EditColorClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitVI initialize the EditColorClass object
KillVI shut down the EditColorClass object

Mainstream Use:
TakeEventV handle events for the edit control

Occasional Use:
CreateContolV create the edit (COMBO) control
SetAlertsVI alert keystrokes for the edit control

V These methods are also virtual.

I These methods are inherited from the EditClass

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

InitI initialize the EditColorClass object

CreateContol create the edit (COMBO) control
SetAlertsI alert keystrokes for the edit control
TakeEvent handle events for the edit control
KillI shut down the EditColorClass object
346 ABC Library Reference

CreateControl (create the edit-in-place control)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method creates the edit-in-place COMBO control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method creates a COMBO
control with an ellipsis button and sets the value of the FEQ property.

Use the Init method or the CreateControl method to set any required properties of the COMBO
control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

EditColorClass 347

TakeEvent (process edit-in-place events:EditColorClass)

TakeEvent( event ), VIRTUAL

TakeEvent Processes an event for the EditColorClass object.

event An integer constant, variable, EQUATE, or expression that contains the event
number (see EVENT in the Language Reference).
The TakeEvent method processes an event for the EditColorClass object and returns a value indicating the user
requested action. Valid actions are none, complete or OK, cancel, next record, previous record, next field, and previous
field.

Implementation: The BrowseClass.AskRecord method calls the TakeEvent method. The TakeEvent method processes an
EVENT:AlertKey for the edit-in-place control. On EVENT:DroppingDown, TakeEvent invokes the
Windows color dialog and stores the color selection in the edited field specified by the Init method. Finally,
TakeEvent returns a value indicating the user requested action. The BrowseClass.AskRecord method
carries out the user requested action.

Corresponding EQUATEs for the possible edit-in-place actions are declared in ABBROWSE.INC as
follows:
EditAction ITEMIZE(0),PRE
None EQUATE ! no action
Forward EQUATE ! next field
Backward EQUATE ! previous field
Complete EQUATE ! OK
Cancel EQUATE ! cancel
Next EQUATE ! next record
Previous EQUATE ! previous record
Ignore EQUATE ! no action
END

Return Data Type: BYTE

Example:
EditClassAction ROUTINE
CASE SELF.EditList.Control.TakeEvent(EVENT())
OF EditAction:Forward !handle tab forward (new field, same record)
OF EditAction:Backward !handle tab backward (new field, same record)
OF EditAction:Next !handle down arrow (new record, offer to save prior record)
OF EditAction:Previous !handle up arrow (new record, offer to save prior record)
OF EditAction:Complete !handle OK or enter key (save record)
OF EditAction:Cancel !handle Cancel or esc key (restore record)
END
See Also: Init, BrowseClass.AskRecord
348 ABC Library Reference

EditDropComboClass
EditDropComboClass Overview
The EditDropComboClass is an EditClass that supports a dynamic edit-in-place COMBO control for a column in a LIST.

EditDropComboClass Concepts
The EditDropComboClass creates a COMBO control, accepts input from the end user, then returns the input to the
variable specified by the Init method, typically the variable associated with a specific LIST cell—a field in the LIST control's
data source QUEUE. The EditDropComboClass also signals the calling procedure whenever significant edit-in-place
events occur, such as tabbing to a new column, canceling the edit, or completing the edit (moving to a new record or row).
The EditDropComboClass provides a virtual TakeEvent method to let you take control of significant edit-in-place events.

Relationship to Other Application Builder Classes

EditClass

The EditDropComboClass is derived from the EditDropListClass which in turn is derived from the EditClass. The
EditClass serves as the foundation and framework for its derived classes. These derived classes each provide a different
type of input control or input user interface. You can control the values returned by these derived EditClass objects by
using their virtual methods. See the Conceptual Example.

BrowseEIPManagerClass

The EditClass is managed by the BrowseEIPManagerClass. The BrowseEIPManagerClass depends on the EditClass
operating according to its documented specifications; however, the EditClass may be called by non-BrowseClass
procedures and objects.

EditDropComboClass ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditDropComboClass object called EditInPlace:fieldname and register the object with the BrowseClass object. The
BrowseClass object then calls the registered EditDropComboClass object's methods as needed. See Control
Templates—BrowseUpdateButtons for more information.

EditDropComboClass Source Files

The EditDropComboClass source code is installed by default to the Clarion \LIBSRC folder. The specific
EditDropComboClass source code and their respective components are contained in:

ABEIP.INC EditDropComboClass declarations

ABEIP.CLW EditDropComboClass method definitions
EditDropComboClass 349

EditDropComboClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditDropComboClass object and a related BrowseClass object. The example page-loads a LIST of fieldnames and
associated control attributes (such as color, icon, etc.), then edits the "ControlType" items with an EditDropComboClass
object. Note that the BrowseClass object calls the "registered" EditDropComboClass object's methods as needed.
PROGRAM
_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)

INCLUDE('ABWINDOW.INC') !declare WindowManager

INCLUDE('ABBROWSE.INC') !declare BrowseClass
INCLUDE('ABEIP.INC') !declare Edit-in-place classes

MAP
END

Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
ControlType STRING(12)
END
END

PropView VIEW(Property)
END

PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color)
PR:ControlType LIKE(PR:ControlType) !edit this field with a COMBO control
PR:Hidden LIKE(PR:Hidden)
PR:IconFile LIKE(PR:IconFile)
ViewPosition STRING(1024)
END

PropWindow WINDOW('Browse Field Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
'60L(2)|_M~Control Type~@s12@' &|
'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END
!declare Edit:PR:ControlType-EIP COMBO
Edit:PR:ControlType CLASS(EditDropComboClass)
Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
350 ABC Library Reference

END

BRW1 CLASS(BrowseClass) !declare BRW1, the BrowseClass object

Q &PropQ ! that drives the EditClass objects—
END ! i.e. calls Init, TakeEvent, Kill

GlobalErrors ErrorClass
Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END

GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD

CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
BRW1.Q &= PropQ
BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName)
BRW1.AddField(PR:Color,BRW1.Q.PR:Color)
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden)
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile)
!Use Edit:PR:ControlType to edit BRW1 col 3
BRW1.AddEditControl(Edit:PR:ControlType,3)
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
EditDropComboClass 351

RETURN ReturnValue

Edit:PR:ControlType.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Feq{PROP:From}='ENTRY|SPIN|TEXT|STRING'!set ControlType droplist choices

Access:Property.Init PROCEDURE !initialize FileManager

CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)
Relate:Property.Init PROCEDURE !initialize RelationManager
CODE
Access:Property.Init
PARENT.Init(Access:Property,1)
Relate:Property.Kill PROCEDURE !shut down RelationManager
CODE
Access:Property.Kill
PARENT.Kill

EditDropComboClass Properties
The EditDropComboClass inherits all of the properties of the EditDropListClass and EditClass from which is derived. See
EditClass Properties and EditClass Concepts for more information.
352 ABC Library Reference

EditDropComboClass Methods
The EditDropComboClass inherits all the methods of the EditDropListClass and EditClass from which it is derived. See
EditClass Methods and EditClass Concepts for more information.

EditDropComboClass Functional Organization

Non-Virtual Methods

Occasional Use:
CreateContolV create the LIST control

V This method is also virtual.

Virtual Methods

Typically you will not call this method directly—the Non-Virtual methods call it. However, we anticipate you will often want
to override this method, and because it is virtual, it is very easy to override. This method does provide reasonable default
behavior in case you do not want to override it.

CreateContol create the LIST control

EditDropComboClass 353

CreateControl (create the edit-in-place COMBO control)

CreateControl, VIRTUAL, PROTECTED
The CreateControl method creates the edit-in-place COMBO control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method sets the value of the FEQ
property. Use the Init method or the CreateControl method to set any required properties of the
COMBO control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

354 ABC Library Reference

EditDropListClass
EditDropListClass Overview
The EditDropListClass is an EditClass that supports a DROPLIST control. The EditDropListClass lets you implement a
dynamic edit-in-place DROPLIST control for a column in a LIST.

EditDropListClass Concepts
The EditDropListClass creates a DROPLIST control, accepts input from the end user, then returns the input to the
variable specified by the Init method, typically the variable associated with a specific LIST cell--a field in the LIST control's
data source QUEUE. The EditDropListClass also signals the calling procedure whenever significant edit-in-place events
occur, such as tabbing to a new column, cancelling the edit, or completing the edit (moving to a new record or row). The
EditDropListClass provides a virtual TakeEvent method to let you take control of significant edit-in-place events.

EditDropListClass Relationship to Other Application Builder Classes

EditClass

The EditDropListClass is derived from the EditClass. The EditClass serves as the foundation and framework for its
derived classes. These derived classes each provide a different type of input control or input user interface. You can
control the values returned by these derived EditClass objects by using their virtual methods. See the Conceptual
Example.

BrowseClass

The EditClass is loosely integrated into the BrowseClass. The BrowseClass depends on the EditClass operating
according to it's documented specifications; however, the EditClass may be called by non-BrowseClass procedures and
objects.

EditDropListClass ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditDropListClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The
BrowseClass object then calls the registered EditDropListClass object's methods as needed. See Control Templates--
BrowseUpdateButtons for more information.

EditDropListClass Source Files

The EditDropListClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditDropListClass
source code and their respective components are contained in:

ABEIP.INC EditDropListClass declarations

ABEIP.CLW EditDropListClass method definitions
EditDropListClass 355

EditDropListClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditDropListClass object and a related BrowseClass object. The example page-loads a LIST of fieldnames and
associated control attributes (such as color, icon, etc.), then edits the "ControlType" items with an EditDropListClass
object. Note that the BrowseClass object calls the "registered" EditDropListClass object's methods as needed.
PROGRAM
_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)
INCLUDE('ABWINDOW.INC') !declare WindowManager
INCLUDE('ABBROWSE.INC') !declare BrowseClass
INCLUDE('ABEIP.INC') !declare Edit-in-place classes

MAP
END
Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
ControlType STRING(12)
END
END
PropView VIEW(Property)
END

PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color)
PR:ControlType LIKE(PR:ControlType) !edit this field with a DROPLIST control
PR:Hidden LIKE(PR:Hidden)
PR:IconFile LIKE(PR:IconFile)
ViewPosition STRING(1024)
END

PropWindow WINDOW('Browse Field Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
'60L(2)|_M~Control Type~@s12@' &|
'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END

!declare Edit:PR:ControlType-EIP DROPLIST

Edit:PR:ControlType CLASS(EditDropListClass)
Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END

BRW1 CLASS(BrowseClass) !declare BRW1, the BrowseClass object

356 ABC Library Reference

Q &PropQ ! that drives the EditClass objects--

END ! i.e. calls Init, TakeEvent, Kill

GlobalErrors ErrorClass
Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END
GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD

CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
BRW1.Q &= PropQ
BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName)
BRW1.AddField(PR:Color,BRW1.Q.PR:Color)
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden)
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile)
!Use Edit:PR:ControlType to edit BRW1 col 3
BRW1.AddEditControl(Edit:PR:ControlType,3)
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
RETURN ReturnValue

Edit:PR:ControlType.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
EditDropListClass 357

PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Feq{PROP:From}='ENTRY|SPIN|TEXT|STRING'!set ControlType droplist choices

Access:Property.Init PROCEDURE !initialize FileManager

CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)

Relate:Property.Init PROCEDURE !initialize RelationManager

CODE
Access:Property.Init
PARENT.Init(Access:Property,1)

Relate:Property.Kill PROCEDURE !shut down RelationManager

CODE
Access:Property.Kill
PARENT.Kill
358 ABC Library Reference

EditDropListClass Properties
EditDropListClass Properties
The EditDropListClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties and
EditClass Concepts for more information.
EditDropListClass 359

EditDropListClass Methods
EditDropListClass Functional Organization--Expected Use
As an aid to understanding the EditDropListClass it is useful to organize its methods into two large categories according to
their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EditDropListClass methods.

Non-Virtual Methods

The non-virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitVI initialize the EditDropListClass object
KillVI shut down the EditDropListClass object

Mainstream Use:
TakeEventVI handle events for the LIST control

Occasional Use:
CreateContolV create the LIST control
SetAlertsV alert keystrokes for the LIST control

V These methods are also virtual.

I These methods are inherited from the EditClass

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

InitI initialize the EditDropListClass object

CreateContol create the LIST control
SetAlerts alert keystrokes for the LIST control
TakeEventI handle events for the LIST control
KillI shut down the EditDropListClass object
360 ABC Library Reference

CreateControl (create the edit-in-place DROPLIST control)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method creates the edit-in-place DROPLIST control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method sets the value of the FEQ
property. Use the Init method or the CreateControl method to set any required properties of the
DROPLIST control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

EditDropListClass 361

SetAlerts (alert keystrokes for the edit control:EditDropListClass)

SetAlerts, VIRTUAL
The SetAlerts method alerts appropriate keystrokes for the edit-in-place DROPLIST control.

Implementation: The Init method calls the CreateControl method to create the input control and set the FEQ property.
The Init method then calls the SetAlerts method to alert appropriate edit-in-place keystrokes for the
edit control. Alerted keys are:
TabKey !next field
ShiftTab !previous field
EnterKey !complete and save
EscKey !complete and cancel

Tip: Arrowup and Arrowdown keys are not alerted for a DROPLIST control because these keys are used to
navigate within the DROPLISt.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: Init

362 ABC Library Reference

SetReadOnly (set edit control to read-only:EditDropClass)

SetReadOnly( state ), VIRTUAL

SetReadOnly The SetReadOnly method places the edit-in-place control in a read-only state.
state An integer constant, variable, EQUATE, or expression that indicates whether to
disable the droplist control's dropdown button. A value of one (1 or True) disables
the button. A value of zero (0 or False) has no effect on the control.
Implementation: The SetReadOnly method uses PROP:ReadOnly to place the edit-in-place conrol in a read-only
state. After the parent call in the Init method of the EditInPlace object is the recommended place to
call SetReadonly.

Example: EditInPlace::CUS:Number.SetReadOnly()

See Also: ReadOnly

EditDropListClass 363

TakeEvent (process edit-in-place events:EditDropList Class)

TakeEvent( event ), VIRTUAL

TakeEvent Processes an event for the EditDropListClass object.

event An integer constant, variable, EQUATE, or expression that contains the event
number (see EVENT in the Language Reference).
The TakeEvent method processes an event for the EditDropListClass object and returns a value indicating the user
requested action. Valid actions are none, complete or OK, cancel, next record, previous record, next field, and previous
field.

Implementation: The TakeEvent method is called by the WindowManager.TakeEvent method. The TakeEvent method
processes an EVENT:AlertKey for the edit-in-place control. TakeEvent returns a value indicating the
user requested action.

Corresponding EQUATEs for the possible edit-in-place actions are declared in ABEIP.INC as follows:
EditAction ITEMIZE(0),PRE
None EQUATE ! no action
Forward EQUATE ! next field
Backward EQUATE ! previous field
Complete EQUATE ! OK
Cancel EQUATE ! cancel
Next EQUATE ! next record
Previous EQUATE ! previous record
Ignore EQUATE ! no action
END

Return Data Type: BYTE

Example:
WindowManager.TakeEvent PROCEDURE
CODE
! Event handling code
LOOP i=1 TO RECORDS(SELF.FileDrops)
GET(SELF.FileDrops,i)
ASSERT(~ERRORCODE())
SELF.FileDrops.FileDrop.TakeEvent
END

See Also: Init

364 ABC Library Reference

EditEntryClass
EditEntryClass Overview
The EditEntryClass is an EditClass that supports an ENTRY control. The EditEntryClass lets you implement a dynamic
edit-in-place ENTRY control for a column in a LIST.

EditEntryClass Concepts
The EditEntryClass creates an ENTRY control, accepts input from the end user, then returns the input to the variable
specified by the Init method, typically the variable associated with a specific LIST cell--a field in the LIST control's data
source QUEUE. The EditEntryClass also signals the calling procedure whenever significant edit-in-place events occur,
such as tabbing to a new column, cancelling the edit, or completing the edit (moving to a new record or row). The
EditEntryClass provides a virtual TakeEvent method to let you take control of significant edit-in-place events.

EditEntryClass Relationship to Other Application Builder Classes

EditClass

The EditEntryClass is derived from the EditClass. The EditClass serves as the foundation and framework for its derived
classes. These derived classes each provide a different type of input control or input user interface. You can control the
values returned by these derived EditClass objects by using their virtual methods. See the Conceptual Example.

BrowseClass

The EditClass is loosely integrated into the BrowseClass. The BrowseClass depends on the EditClass operating
according to it's documented specifications; however, the EditClass may be called by non-BrowseClass procedures and
objects.

Tip: The BrowseClass instantiates the EditEntryClass as the default edit-in-place object whenever edit-in-
place is requested (when BrowseClass.AskProcedure is zero).
EditEntryClass 365

EditEntryClass ABC Template Implementation

When you check the Use EditInPlace box and you do not set column-specific configuration, the BrowseUpdateButtons
control template relies on the default BrowseBox edit-in-place behavior--which is the default BrowseClass edit-in-place
implementation--which instantiates an EditEntryClass object for each BrowseBox column.

You can also use the BrowseUpdateButtons control template (Configure EditInPlace) to explicitly instantiate an
EditEntryClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The BrowseClass
object then calls the registered EditEntryClass object's methods as needed. By explicitly requesting an EditEntryClass
object, you gain access to EditEntryClass method embed points. See Control Templates--BrowseUpdateButtons for more
information.

EditEntryClass Source Files

The EditEntryClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditEntryClass source
code and their respective components are contained in:

ABEIP.INC EditEntryClass declarations

ABEIP.CLW EditEntryClass method definitions

EditEntryClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditEntryClass object and a related BrowseClass object. The example page-loads a LIST of fieldnames and associated
control attributes (such as color, icon, etc.), then edits the items with an EditEntryClass object. Note that the BrowseClass
object calls the EditEntryClass object's methods as needed.
PROGRAM
_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)

INCLUDE('ABWINDOW.INC') !declare WindowManager

INCLUDE('ABBROWSE.INC') !declare BrowseClass
INCLUDE('ABEIP.INC') !declare Edit-in-place classes

MAP
END

Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
ControlType STRING(12)
END
END

PropView VIEW(Property)
END

PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color)
PR:ControlType LIKE(PR:ControlType)
PR:Hidden LIKE(PR:Hidden)
PR:IconFile LIKE(PR:IconFile)
366 ABC Library Reference

ViewPosition STRING(1024)
END

PropWindow WINDOW('Browse Field Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
'60L(2)|_M~Control Type~@s12@' &|
'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END

Edit:PR:Name CLASS(EditEntryClass) !declare Edit:PR:Name-EIP ENTRY control

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END

BRW1 CLASS(BrowseClass) !declare BRW1, the BrowseClass object

Q &PropQ ! that drives the EditClass objects--
END ! i.e. calls Init, TakeEvent, Kill

GlobalErrors ErrorClass

Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END

GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD

CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
EditEntryClass 367

BRW1.Q &= PropQ

BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName) !edit with Edit:PR:Name
BRW1.AddField(PR:Color,BRW1.Q.PR:Color) !default EditEntryClass
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)!edit with default EditEntryClass
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden) !edit with default EditEntryClass
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile) !edit with default EditEntryClass
BRW1.AddEditControl(Edit:PR:Name,1) !Use Edit:PR:Name for BRW1 col 1
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
RETURN ReturnValue

Edit:PR:Name.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Feq{PROP:CAP}=True !force EIP mixed case input

Access:Property.Init PROCEDURE !initialize FileManager

CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)

Relate:Property.Init PROCEDURE !initialize RelationManager

CODE
Access:Property.Init
PARENT.Init(Access:Property,1)

Relate:Property.Kill PROCEDURE !shut down RelationManager

CODE
Access:Property.Kill
PARENT.Kill
368 ABC Library Reference

EditEntryClass Properties
EditEntryClass Properties
The EditEntryClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties and
EditClass Concepts for more information.
EditEntryClass 369

EditEntryClass Methods
EditEntryClass Methods
The EditEntryClass inherits all the methods of the EditClass from which it is derived. See EditClass Methods and
EditClass Concepts.

EditEntryClass Functional Organization--Expected Use

As an aid to understanding the EditEntryClass it is useful to organize its methods into two large categories according to
their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EditEntryClass methods.

Non-Virtual Methods

The Non-Virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitVI initialize the EditEntryClass object
KillVI shut down the EditEntryClass object

Mainstream Use:
TakeEventVI handle events for the ENTRY control

Occasional Use:
CreateContolV create the ENTRY control
SetAlertsVI alert keystrokes for the ENTRY control

V These methods are also virtual.

I These methods are inherited from the EditClass

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

InitI initialize the EditEntryClass object

CreateContol create the ENTRY control
SetAlertsI alert keystrokes for the ENTRY control
TakeEventI handle events for the ENTRY control
KillI shut down the EditEntryClass object
370 ABC Library Reference

CreateControl (create the edit-in-place ENTRY control)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method creates the edit-in-place ENTRY control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method sets the value of the FEQ
property. Use the Init method or the CreateControl method to set any required properties of the
ENTRY control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

EditEntryClass 371
372 ABC Library Reference

EditFileClass
EditFileClass Overview
The EditFileClass is an EditClass that supports the Windows File dialog by way of a dynamic edit-in-place COMBO
control.

EditFileClass Concepts
The EditFileClass creates a COMBO control with an ellipsis button that invokes the Windows File dialog. The
EditFileClass accepts a pathname selection from the end user, then returns the selection to the variable specified by the
Init method, typically the variable associated with a specific LIST cell--a field in the LIST control's data source QUEUE.

The EditFileClass also signals the calling procedure whenever significant edit-in-place events occur, such as tabbing to a
new column, cancelling the edit, or completing the edit (moving to a new record or row). The EditFileClass provides a
virtual TakeEvent method to let you take control of significant edit-in-place events.

EditFileClass Relationship to Other Application Builder Classes

EditClass

The EditFileClass is derived from the EditClass. The EditClass serves as the foundation and framework for its derived
classes. These derived classes each provide a different type of input control or input user interface. You can control the
values returned by these derived EditClass objects by using their virtual methods. See the Conceptual Example.

BrowseClass

The EditClass is loosely integrated into the BrowseClass. The BrowseClass depends on the EditClass operating
according to it's documented specifications; however, the EditClass may be called by non-BrowseClass procedures and
objects.

EditFileClass ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditFileClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The BrowseClass
object then calls the registered EditFileClass object's methods as needed. See Control Templates--BrowseUpdateButtons
for more information.

EditFileClass Source Files

The EditFileClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditFileClass source
code and their respective components are contained in:

ABEIP.INC EditFileClass declarations

ABEIP.CLW EditFileClass method definitions
EditFileClass 373

EditFileClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditFileClass object and a related BrowseClass object. The example page-loads a LIST of fieldnames and associated
control attributes (such as color, icon, etc.), then edits the "IconFile" items with an EditFileClass object. Note that the
BrowseClass object calls the "registered" EditFileClass object's methods as needed.
PROGRAM
_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)

INCLUDE('ABWINDOW.INC') !declare WindowManager

INCLUDE('ABBROWSE.INC') !declare BrowseClass
INCLUDE('ABEIP.INC') !declare Edit-in-place classes
MAP
END

Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
ControlType STRING(12)
END
END
PropView VIEW(Property)
END
PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color)
PR:ControlType LIKE(PR:ControlType)
PR:Hidden LIKE(PR:Hidden)
PR:IconFile LIKE(PR:IconFile) !edit this LIST field with the file dialog
ViewPosition STRING(1024)
END

PropWindow WINDOW('Browse Field Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
'60L(2)|_M~Control Type~@s12@' &|
'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END

Edit:PR:IconFile CLASS(EditFileClass) !declare Edit:PR:IconFile-EIP file dialog

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? Use Var),VIRTUAL
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END

BRW1 CLASS(BrowseClass) !declare BRW1, the BrowseClass object

Q &PropQ ! that drives the EditClass objects--
374 ABC Library Reference

END ! i.e. calls Init, TakeEvent, Kill

GlobalErrors ErrorClass
Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END
GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD
CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
BRW1.Q &= PropQ
BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName)
BRW1.AddField(PR:Color,BRW1.Q.PR:Color)
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden)
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile)
BRW1.AddEditControl(Edit:PR:IconFile,5) !Use Edit:PR:IconFile to edit BRW1 col 5
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
RETURN ReturnValue

Edit:PR:IconFile.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVa r)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Title='Select icon file' !set EIP file dialog title
SELF.FilePattern='Icon files *.ico|*.ico' !set EIP file dialog file masks
EditFileClass 375

SELF.FileMask=FILE:KeepDir+FILE:LongName !set EIP file dialog behavior flag

376 ABC Library Reference

Access:Property.Init PROCEDURE !initialize FileManager

CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)

Relate:Property.Init PROCEDURE !initialize RelationManager

CODE
Access:Property.Init
PARENT.Init(Access:Property,1)

Relate:Property.Kill PROCEDURE !shut down RelationManager

CODE
Access:Property.Kill
PARENT.Kill
EditFileClass 377

EditFileClass Properties
EditFileClass Properties
The EditFileClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties and
EditClass Concepts for more information.

FileMask (file dialog behavior)

FileMask BYTE
The FileMask property is a bitmap that indicates the type of file action the Windows file dialog performs (select, multi-
select, save directory, lock directory, suppress errors).

Implementation: The EditFileClass (TakeEvent method) uses the FileMask property as the flag parameter to the
FILEDIALOG procedure. See FILEDIALOG in the Language Reference for more information.

See Also: TakeEvent

FilePattern (file dialog filter)

FilePattern CSTRING(1024)
The FilePattern property contains a text string that defines both the file masks and the file mask descriptions that appear
in the file dialog's List Files of Type drop-down list. The first mask is the default selection in the file dialog.

The FilePattern property should contain one or more descriptions followed by their corresponding file masks in the form
description|masks|description|masks. All elements in the string must be delimited by the vertical bar (|). For example, 'all
files *.*|*.*|Clarion source *.clw;*.inc|*.clw;*.inc' defines two selections for the File dialog's List Files of
Type drop-down list. See the extensions parameter to the FILEDIALOG function in the Language Reference for more
information.
378 ABC Library Reference

Title (file dialog title text)

Title CSTRING(256)
The Title property contains a string that sets the title bar text in the Windows file dialog.

Implementation: The EditFileClass (TakeEvent method) uses the Title property as the title parameter to the
FILEDIALOG procedure. See FILEDIALOG in the Language Reference for more information.

See Also: TakeEvent

EditFileClass 379

EditFileClass Methods
EditFileClass Functional Organization--Expected Use
As an aid to understanding the EditFileClass it is useful to organize its methods into two large categories according to
their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EditFileClass methods.

Non-Virtual Methods

The Non-Virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitVI initialize the EditFileClass object
KillVI shut down the EditFileClass object

Mainstream Use:
TakeEventVI handle events for the edit control

Occasional Use:
CreateContolV create the edit (COMBO) control
SetAlertsVI alert keystrokes for the edit control

V These methods are also virtual.

I These methods are inherited from the EditClass

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

InitI initialize the EditFileClass object

CreateContol create the edit (COMBO) control
SetAlertsI alert keystrokes for the edit control
TakeEventI handle events for the edit control
KillI shut down the EditFileClass object
380 ABC Library Reference

CreateControl (create the edit-in-place control:EditFileClass)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method creates the edit-in-place COMBO control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method creates a COMBO
control with an ellipsis button and sets the value of the FEQ property.

Use the Init method or the CreateControl method to set any required properties of the COMBO
control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

EditFileClass 381

TakeEvent (process edit-in-place events:EditFileClass)

TakeEvent( event ), VIRTUAL

TakeEvent Processes an event for the EditFileClass object.

event An integer constant, variable, EQUATE, or expression that contains the event
number (see EVENT in the Language Reference).
The TakeEvent method processes an event for the EditFileClass object and returns a value indicating the user requested
action. Valid actions are none, complete or OK, cancel, next record, previous record, next field, and previous field.

Implementation: The BrowseClass.AskRecord method calls the TakeEvent method. The TakeEvent method
processes an EVENT:AlertKey for the edit-in-place control. On EVENT:DroppingDown, TakeEvent
invokes the Windows file dialog and stores the pathname selection in the edited field specified by the
Init method. Finally, TakeEvent returns a value indicating the user requested action. The
BrowseClass.AskRecord method carries out the user requested action.

Corresponding EQUATEs for the possible edit-in-place actions are declared in ABBROWSE.INC as
follows:
EditAction ITEMIZE(0),PRE
None EQUATE ! no action
Forward EQUATE ! next field
Backward EQUATE ! previous field
Complete EQUATE ! OK
Cancel EQUATE ! cancel
Next EQUATE ! next record
Previous EQUATE ! previous record
Ignore EQUATE ! no action
END

Return Data Type: BYTE

Example:
EditClassAction ROUTINE
CASE SELF.EditList.Control.TakeEvent(EVENT())
OF EditAction:Forward !handle tab forward (new field, same record)
OF EditAction:Backward !handle tab backward (new field, same record)
OF EditAction:Next !handle down arrow (new record, offer to save prior record)
OF EditAction:Previous !handle up arrow (new record, offer to save prior record)
OF EditAction:Complete !handle OK or enter key (save record)
OF EditAction:Cancel !handle Cancel or esc key (restore record)
END

See Also: Init, BrowseClass.AskRecord

382 ABC Library Reference
EditFontClass 383

EditFontClass
EditFontClass Overview
The EditFontClass is an EditClass that supports the Windows Font dialog by way of a dynamic edit-in-place COMBO
control.

EditFontClass Concepts
The EditFontClass creates a COMBO control with an ellipsis button that invokes the Windows Font dialog. The
EditFontClass accepts a font specification from the end user, then returns the specification to the variable specified by the
Init method, typically the variable associated with a specific LIST cell--a field in the LIST control's data source QUEUE.

The EditFontClass also signals the calling procedure whenever significant edit-in-place events occur, such as tabbing to a
new column, cancelling the edit, or completing the edit (moving to a new record or row). The EditFontClass provides a
virtual TakeEvent method to let you take control of significant edit-in-place events.

EditFontClass Relationship to Other Application Builder Classes

EditClass

The EditFontClass is derived from the EditClass. The EditClass serves as the foundation and framework for its derived
classes. These derived classes each provide a different type of input control or input user interface. You can control the
values returned by these derived EditClass objects by using their virtual methods. See the Conceptual Example.

BrowseClass

The EditClass is loosely integrated into the BrowseClass. The BrowseClass depends on the EditClass operating
according to it's documented specifications; however, the EditClass may be called by non-BrowseClass procedures and
objects.

EditFontClass ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditFontClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The BrowseClass
object then calls the registered EditFontClass object's methods as needed. See Control Templates--
BrowseUpdateButtons for more information.

EditFontClass Source Files

The EditFontClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditFontClass source
code and their respective components are contained in:

ABEIP.INC EditFontClass declarations

ABEIP.CLW EditFontClass method definitions
384 ABC Library Reference

EditFontClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditFontClass object and a related BrowseClass object. The example page-loads a LIST of fieldnames and associated
control attributes (such as color, font, icon, etc.), then edits the "Font" items with an EditFontClass object. Note that the
BrowseClass object calls the "registered" EditFontClass object's methods as needed.
PROGRAM

_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)

INCLUDE('ABWINDOW.INC') !declare WindowManager

INCLUDE('ABBROWSE.INC') !declare BrowseClass
INCLUDE('ABEIP.INC') !declare EditInPlace classes

MAP END

Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
Font STRING(40)
ControlType STRING(12)
ApplyTo CSTRING(500)
END
END

PropView VIEW(Property)
END

PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color)
PR:Font LIKE(PR:Font)
PR:ControlType LIKE(PR:ControlType)
PR:Hidden LIKE(PR:Hidden)
PR:IconFile LIKE(PR:IconFile)
PR:ApplyTo LIKE(PR:ApplyTo)
ViewPosition STRING(1024)
END

BRW1 CLASS(BrowseClass) !declare BRW1--a BrowseClass object

Q &PropQ ! that drives the EditClass objects
END

Edit:PR:Font CLASS(EditFontClass) !declare Edit:PR:Font-EIP font dialog

Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
TakeEvent PROCEDURE(UNSIGNED Event),BYTE,VIRTUAL
TypeFace CSTRING(30) !declare font typeface property
FontSize LONG !declare font size property
FontStyle LONG !declare font style property
FontColor LONG !declare font color property
END

PropWindow WINDOW('Browse Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
EditFontClass 385

'60L(2)|_M~Font~@s40@60L(2)|_M~Control Type~@s12@' &|

'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@' &|
'120L(2)|_M~Apply To~L(0)@s25@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END

GlobalErrors ErrorClass
Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END

GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END

CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
?PropList{PROP:LineHeight}=12 !enlarge rows to accomodate EIP icons
BRW1.Q &= PropQ
BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName)
BRW1.AddField(PR:Color,BRW1.Q.PR:Color)
BRW1.AddField(PR:Font,BRW1.Q.PR:Font)
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden)
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile)
BRW1.AddField(PR:ApplyTo,BRW1.Q.PR:ApplyTo)
BRW1.AddEditControl(Edit:PR:Font,3) !Use Edit:PR:Font to edit BRW1 col 3
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
386 ABC Library Reference

BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
RETURN ReturnValue

Edit:PR:Font.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

Comma BYTE(1)
SaveFont CSTRING(100) !indexable hold area for font spec
i USHORT
CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SaveFont=SELF.UseVar !comma separated font attributes
IF SaveFont ! e.g. Arial,14,255,400
LOOP WHILE Comma !parse/separate the font attributes
Comma = INSTRING(',',SaveFont,1,1)
i+=1
IF Comma
EXECUTE i
SELF.TypeFace = SaveFont[1 : Comma-1] !get Typeface
SELF.FontSize = SaveFont[1 : Comma-1] !get FontSize
BEGIN
SELF.FontColor = SaveFont[1 : Comma-1] !get FontColor & Style
SELF.FontStyle = SaveFont[Comma+1 : LEN(SaveFont)]
END
END
SaveFont=SaveFont[Comma+1 : LEN(SaveFont)]
END
END
END

Edit:PR:Font.TakeEvent PROCEDURE(UNSIGNED Event)

ReturnValue BYTE,AUTO
CODE
CASE Event
OF EVENT:DroppingDown !call Font dialog & store result
! in comma separated string
IF FONTDIALOG(SELF.Title,SELF.TypeFace,SELF.FontSize,SELF.FontColor,SELF.FontStyle)
SELF.UseVar = SELF.TypeFace&','&SELF.FontSize&','&SELF.FontColor&','&SELF.FontStyle
DISPLAY(SELF.Feq)
END
RETURN EditAction:Ignore !no I/O action on DroppingDown
ELSE !otherwise, default I/O action:
RETURN PARENT.TakeEvent(Event) ! save, cancel, next field, etc.
END

Access:Property.Init PROCEDURE
CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)
EditFontClass 387

Relate:Property.Init PROCEDURE
CODE
Access:Property.Init
PARENT.Init(Access:Property,1)

Relate:Property.Kill PROCEDURE
CODE
Access:Property.Kill
PARENT.Kill
388 ABC Library Reference

EditFontClass Properties
EditFontClass Properties
The EditFontClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties and
EditClass Concepts for more information.

In addition to the inherited properties, the EditFontClass contains the following properties:

Title (font dialog title text)

Title CSTRING(256)
The Title property contains a string that sets the title bar text in the Windows font dialog.

Implementation: The EditFontClass (TakeEvent method) uses the Title property as the title parameter to the
FONTDIALOG procedure. See FONTDIALOG in the Language Reference for more information.

See Also: TakeEvent

EditFontClass 389

EditFontClass Methods
EditFontClass Methods
The EditFontClass inherits all the methods of the EditClass from which it is derived. See EditClass Methods and EditClass
Concepts.

EditFontClass Functional Organization--Expected Use

As an aid to understanding the EditFontClass it is useful to organize its methods into two large categories according to
their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EditFontClass methods.

Non-Virtual Methods

The Non-Virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitVI initialize the EditFontClass object
KillVI shut down the EditFontClass object

Mainstream Use:
TakeEventV handle events for the edit control

Occasional Use:
CreateContolV create the edit (COMBO) control
SetAlertsVI alert keystrokes for the edit control

V These methods are also virtual.

I These methods are inherited from the EditClass

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

InitI initialize the EditFontClass object

CreateContol create the edit (COMBO) control
SetAlertsI alert keystrokes for the edit control
TakeEvent handle events for the edit control
KillI shut down the EditFontClass object
390 ABC Library Reference

CreateControl (create the edit-in-place control:EditFontClass)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method creates the edit-in-place COMBO control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method creates a COMBO
control with an ellipsis button and sets the value of the FEQ property.

Use the Init method or the CreateControl method to set any required properties of the COMBO
control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

EditFontClass 391

TakeEvent (process edit-in-place events:EditFontClass)

TakeEvent( event ), VIRTUAL

TakeEvent Processes an event for the EditFontClass object.

event An integer constant, variable, EQUATE, or expression that contains the event number (see
EVENT in the Language Reference).
The TakeEvent method processes an event for the EditFontClass object and returns a value indicating the user
requested action. Valid actions are none, complete or OK, cancel, next record, previous record, next field, and previous
field.

Implementation: The BrowseClass.AskRecord method calls the TakeEvent method. The TakeEvent method
processes an EVENT:AlertKey for the edit-in-place control. On EVENT:DroppingDown, TakeEvent
invokes the Windows font dialog and stores the font specification in the edited field specified by the
Init method. Finally, TakeEvent returns a value indicating the user requested action. The
BrowseClass.AskRecord method carries out the user requested action.
Corresponding EQUATEs for the possible edit-in-place actions are declared in ABEIP.INC as follows:
EditAction ITEMIZE(0),PRE
None EQUATE ! no action
Forward EQUATE ! next field
Backward EQUATE ! previous field
Complete EQUATE ! OK
Cancel EQUATE ! cancel
Next EQUATE ! next record
Previous EQUATE ! previous record
Ignore EQUATE ! no action
END

Return Data Type: BYTE

Example:
EditClassAction ROUTINE
CASE SELF.EditList.Control.TakeEvent(EVENT())
OF EditAction:Forward !handle tab forward (new field, same record)
OF EditAction:Backward !handle tab backward (new field, same record)
OF EditAction:Next !handle down arrow (new record, offer to save prior record)
OF EditAction:Previous !handle up arrow (new record, offer to save prior record)
OF EditAction:Complete !handle OK or enter key (save record)
OF EditAction:Cancel !handle Cancel or esc key (restore record)
END
See Also: Init, BrowseClass.AskRecord
392 ABC Library Reference
EditMultiSelectClass 393

EditMultiSelectClass
EditMultiSelectClass Overview
The EditMultiSelectClass is an EditClass that supports a MultiSelect dialog by way of a dynamic edit-in-place COMBO
control.

EditMultiSelectClass Concepts
The EditMultiSelectClass creates a COMBO control with an ellipsis button that invokes the MultiSelect dialog. The
MultiSelect dialog is an interface for selecting and ordering items from a list.

The EditMultiSelectClass provides an AddValue method so you can prime the dialog's Available Items and Selected Items
lists.

The EditMultiSelectClass accepts input (selection actions) from the end user, then signals the calling procedure when
selection actions occur. The EditMultiSelectClass provides a virtual TakeAction method to let you take control of the end
user input.

The EditMultiSelectClass also signals the calling procedure whenever significant edit-in-place events occur, such as
tabbing to a new column, canceling the edit, or completing the edit (moving to a new record or row). The
EditMultiSelectClass provides a virtual TakeEvent method to let you take control of significant edit-in-place events.

EditMultiSelectClass Relationship to Other Application Builder Classes

EditClass

The EditMultiSelectClass is derived from the EditClass. The EditClass serves as the foundation and framework for its
derived classes. These derived classes each provide a different type of input control or input user interface. You can
control the values returned by these derived EditClass objects by using their virtual methods. See the Conceptual
Example.

BrowseClass

The EditClass is loosely integrated into the BrowseClass. The BrowseClass depends on the EditClass operating
according to it's documented specifications; however, the EditClass may be called by non-BrowseClass procedures and
objects.

EditMultiSelectClass ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditMultiSelectClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The
BrowseClass object then calls the registered EditMultiSelectClass object's methods as needed. See Control Templates--
BrowseUpdateButtons for more information.

EditMultiSelectClass Source Files

The EditMultiSelectClass source code is installed by default to the Clarion \LIBSRC folder. The specific
EditMultiSelectClass source code and their respective components are contained in:

ABEIP.INC EditMultiSelectClass declarations

ABEIP.CLW EditMultiSelectClass method definitions
394 ABC Library Reference

EditMultiSelectClass Conceptual Example

The following example shows a sequence of statements to declare, instantiate, initialize, use, and terminate an
EditMultiSelectClass object and a related BrowseClass object. The example page-loads a LIST of fieldnames and
associated control attributes (such as color, font, when-to-apply, etc.), then edits the "when-to-apply" items with an
EditMultiSelectClass object. Note that the BrowseClass object calls the "registered" EditMultiSelectClass object's methods
as needed.
PROGRAM

_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)

INCLUDE('ABWINDOW.INC')
INCLUDE('ABBROWSE.INC')
INCLUDE('ABEIP.INC')

MAP
END

Property FILE,DRIVER('TOPSPEED'),PRE(PR),CREATE,BINDABLE,THREAD
NameKey KEY(PR:FieldName),NOCASE,OPT
Record RECORD,PRE()
FieldName STRING(30)
Color STRING(20)
Hidden STRING(1)
IconFile STRING(30)
Font STRING(40)
ControlType STRING(12)
ApplyTo CSTRING(500)
END
END

PropView VIEW(Property)
END

PropQ QUEUE
PR:FieldName LIKE(PR:FieldName)
PR:Color LIKE(PR:Color)
PR:Font LIKE(PR:Font)
PR:ControlType LIKE(PR:ControlType)
PR:Hidden LIKE(PR:Hidden)
PR:IconFile LIKE(PR:IconFile)
PR:ApplyTo LIKE(PR:ApplyTo)
ViewPosition STRING(1024)
END

BRW1 CLASS(BrowseClass)
Q &PropQ
END
!declare Edit:PR:ApplyTo-EIP multi dialog
Edit:PR:ApplyTo CLASS(EditMultiSelectClass)
Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar),VIRTUAL
TakeAction PROCEDURE(BYTE Action,<STRING Item>,LONG Pos1=0,LONG Pos2=0),VIRTUAL
END

PropWindow WINDOW('Browse Properties'),AT(,,318,137),IMM,SYSTEM,GRAY

LIST,AT(8,4,303,113),USE(?PropList),IMM,HVSCROLL,FROM(PropQ),|
FORMAT( '50L(2)|_M~Field Name~@s30@[70L(2)|_M~Color~@s20@' &|
'60L(2)|_M~Font~@s40@60L(2)|_M~Control Type~@s12@' &|
EditMultiSelectClass 395

'20L(2)|_M~Hide~L(0)@s1@/130L(2)|_M~Icon File~@s30@' &|

'120L(2)|_M~Apply To~L(0)@s25@]|M')
BUTTON('&Insert'),AT(169,121),USE(?Insert)
BUTTON('&Change'),AT(218,121),USE(?Change),DEFAULT
BUTTON('&Delete'),AT(267,121),USE(?Delete)
END

GlobalErrors ErrorClass
Access:Property CLASS(FileManager)
Init PROCEDURE
END

Relate:Property CLASS(RelationManager)
Init PROCEDURE
Kill PROCEDURE,VIRTUAL
END

GlobalRequest BYTE(0),THREAD
GlobalResponse BYTE(0),THREAD
VCRRequest LONG(0),THREAD

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END

CODE
GlobalErrors.Init
Relate:Property.Init
GlobalResponse = ThisWindow.Run()
Relate:Property.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE()
ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue = PARENT.Init()
SELF.FirstField = ?PropList
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
Relate:Property.Open
BRW1.Init(?PropList,PropQ.ViewPosition,PropView,PropQ,Relate:Property,SELF)
OPEN(PropWindow)
SELF.Opened=True
?PropList{PROP:LineHeight}=12 !enlarge rows to accomodate EIP icons
BRW1.Q &= PropQ
BRW1.AddSortOrder(,PR:NameKey)
BRW1.AddField(PR:FieldName,BRW1.Q.PR:FieldName)
BRW1.AddField(PR:Color,BRW1.Q.PR:Color)
BRW1.AddField(PR:Font,BRW1.Q.PR:Font)
BRW1.AddField(PR:ControlType,BRW1.Q.PR:ControlType)
BRW1.AddField(PR:Hidden,BRW1.Q.PR:Hidden)
BRW1.AddField(PR:IconFile,BRW1.Q.PR:IconFile)
BRW1.AddField(PR:ApplyTo,BRW1.Q.PR:ApplyTo)
BRW1.AddEditControl(Edit:PR:ApplyTo,7) !use Edit:PR:ApplyTo to edit BRW1 col 7
396 ABC Library Reference

BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE()
ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill()
Relate:Property.Close
RETURN ReturnValue

Edit:PR:ApplyTo.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)

CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Reset
SELF.AddValue('Browse',INSTRING('Browse',SELF.UseVar,1,1))!set multi-select choice
SELF.AddValue('Form',INSTRING('Form',SELF.UseVar,1,1)) !set multi-select choice
SELF.AddValue('Report',INSTRING('Report',SELF.UseVar,1,1))!set multi-select choice
SELF.AddValue('Window',INSTRING('Window',SELF.UseVar,1,1))!set multi-select choice

Edit:PR:ApplyTo.TakeAction PROCEDURE(BYTE Action,<STRING Item>,LONG Pos1=0,LONG Pos2=0)

HoldIt CSTRING(1024) !indexable string of end user choices
Pos USHORT !index to parse end user selections
Comma USHORT !index to parse end user selections
ItemQ QUEUE !Q to reorder end user selections
Item CSTRING(100)
Ord BYTE
END
CODE
PARENT.TakeAction(Action,Item,Pos1,Pos2)
HoldIt=SELF.UseVar
CASE Action
OF MSAction:Add !end user selected an Item
IF HoldIt
HoldIt=HoldIt&','&Item
ELSE
HoldIt=Item
END
OF MSAction:Delete !end user deselected an Item
Pos=INSTRING(Item,HoldIt,1,1)
CASE Pos
OF 0
MESSAGE(Item&' not found!')
OF 1 !first item
HoldIt=HoldIt[Pos+LEN(Item)+1 : LEN(HoldIt)] !deselect first item
ELSE
IF Pos+LEN(Item) > LEN(HoldIt) !last item
HoldIt=HoldIt[1 : Pos-2] !deselect last item
ELSE !deselect any other item
HoldIt=HoldIt[1 : Pos-1] & HoldIt[Pos+LEN(Item)+1 : LEN(HoldIt)]
END
END
OF MSAction:Move !Selected Item moved up or down
FREE(ItemQ) ! Pos1=Item's "old" position
CLEAR(ItemQ) ! Pos2=Item's "new" position
Comma=1
EditMultiSelectClass 397

LOOP WHILE Comma !build Q of Selected Items

Comma = INSTRING(',',HoldIt,1,1) ! to use for repositioning
ItemQ.Ord+=1
IF Comma
ItemQ.Item = HoldIt[1 : Comma-1]
ADD(ItemQ,ItemQ.Ord)
HoldIt=HoldIt[Comma+1 : LEN(HoldIt)] !comma separated list of user choices
ELSE
ItemQ.Item = HoldIt
ADD(ItemQ,ItemQ.Ord)
END
END
ItemQ.Ord=Pos2
GET(ItemQ, ItemQ.Ord) !get the "bumped" item
ItemQ.Ord=Pos1
PUT(ItemQ) !reposition the "bumped" item
ItemQ.Item=Item
GET(ItemQ, ItemQ.Item) !get the selected item
ItemQ.Ord=Pos2
PUT(ItemQ) !reposition the selected item
SORT(ItemQ,ItemQ.Ord) !reorder Q of selected items
HoldIt=''
LOOP Pos = 1 TO RECORDS(ItemQ) !refill comma separated list
GET(ItemQ,Pos)
IF HoldIt
HoldIt=HoldIt&','&ItemQ.Item
ELSE
HoldIt=ItemQ.Item
END
END
OF MSAction:StartProcess !begin AddAll (>>) or DeleteAll (<<)
SETCURSOR(CURSOR:Wait)
OF MSAction:EndProcess !end AddAll (>>) or DeleteAll (<<)
SETCURSOR()
END
SELF.UseVar=HoldIt
Access:Property.Init PROCEDURE
CODE
PARENT.Init(Property,GlobalErrors)
SELF.FileNameValue = 'Property'
SELF.Buffer &= PR:Record
SELF.Create = 1
SELF.AddKey(PR:NameKey,'PR:NameKey',0)

Relate:Property.Init PROCEDURE
CODE
Access:Property.Init
PARENT.Init(Access:Property,1)
Relate:Property.Kill PROCEDURE
CODE
Access:Property.Kill
PARENT.Kill
398 ABC Library Reference

EditMultiSelectClass Properties
EditMultiSelectClass Properties
The EditMultiSelectClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties and
EditClass Concepts for more information.

In addition to the inherited properties, the EditMultiSelectClass contains the following properties:

Title (font dialog title text:EditMultiSelectClass)

Title CSTRING(256)
The Title property contains a string that sets the title bar text in the MultiSelect dialog.
EditMultiSelectClass 399

EditMultiSelectClass Methods
EditMultiSelectClass Methods
The EditMultiSelectClass inherits all the methods of the EditClass from which it is derived. See EditClass Methods and
EditClass Concepts.

EditMultiSelectClass Functional Organization--Expected Use

As an aid to understanding the EditMultiSelectClass it is useful to organize its methods into two large categories
according to their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is
typical use of the EditMultiSelectClass methods.

Non-Virtual Methods

The Non-Virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitV initialize the EditMultiSelectClass object
AddValue prime the MultiSelect dialog
KillV shut down the EditMultiSelectClass object

Mainstream Use:
TakeActionV handle user actions for the dialog
TakeEventV handle events for the edit control

Occasional Use:
CreateContolV create the edit (COMBO) control
Reset clear the MultiSelect dialog
SetAlertsVI alert keystrokes for the edit control

V These methods are also virtual.

I These methods are inherited from the EditClass
400 ABC Library Reference

Virtual Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are virtual, they are very easy to override. These methods do provide
reasonable default behavior in case you do not want to override them.

Init initialize the EditMultiSelectClass object

CreateContol create the edit (COMBO) control
SetAlertsI alert keystrokes for the edit control
TakeAction handle user actions for the dialog
TakeEvent handle events for the edit control
Kill shut down the EditMultiSelectClass object
EditMultiSelectClass 401

AddValue (prime the MultiSelect dialog)

AddValue( item [ ,selected ] )

AddValue Primes the Available and Selected items lists in the MultiSelect dialog.
item A string constant, variable, EQUATE, or expression that contains the value to
add to the item list.
selected An integer constant, variable, EQUATE, or expression that indicates which list to
update. A value of zero (0 or False) adds the item to the Available Items list; a
value of one (1 or True) adds the item to the Selected Items list. If omitted,
selected defaults to zero and AddValue adds the item to the Available Items list.
The AddValue method primes the Available and Selected items lists in the MultiSelect dialog.

Example:
Edit:PR:ApplyTo.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)
CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Reset
SELF.AddValue('Browse',INSTRING('Browse',SELF.UseVar,1,1)) !set multi-select choice
SELF.AddValue('Form',INSTRING('Form',SELF.UseVar,1,1)) !set multi-select choice
SELF.AddValue('Report',INSTRING('Report',SELF.UseVar,1,1)) !set multi-select choice
SELF.AddValue('Window',INSTRING('Window',SELF.UseVar,1,1)) !set multi-select choice
402 ABC Library Reference

CreateControl (create the edit-in-place control:EditMultiSelectClass)

CreateControl, VIRTUAL, PROTECTED
The CreateControl method creates the edit-in-place COMBO control and sets the FEQ property.

Implementation: The Init method calls the CreateControl method. The CreateControl method creates a read only
COMBO control with an ellipsis button and sets the value of the FEQ property.

Use the Init method or the CreateControl method to set any required properties of the COMBO
control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

Reset (reset the EditMultiSelectClass object)

Reset
The Reset method resets the EditMultiSelectClass object.

Implementation: The Reset method clears the Available and Selected items lists in the MultiSelect dialog. Use the
AddValue method to refill these lists.

Example:
Edit:PR:ApplyTo.Init PROCEDURE(UNSIGNED FieldNumber,UNSIGNED ListBox,*? UseVar)
CODE
PARENT.Init(FieldNumber,ListBox,UseVar)
SELF.Reset
SELF.AddValue('Browse',INSTRING('Browse',SELF.UseVar,1,1)) !set multi-select choice
SELF.AddValue('Form',INSTRING('Form',SELF.UseVar,1,1)) !set multi-select choice
SELF.AddValue('Report',INSTRING('Report',SELF.UseVar,1,1)) !set multi-select choice
SELF.AddValue('Window',INSTRING('Window',SELF.UseVar,1,1)) !set multi-select choice

See Also: AddValue

EditMultiSelectClass 403

TakeAction (process MultiSelect dialog action)

TakeAction( action [, item ] [ ,oldposition ] [ ,newposition ] ), VIRTUAL

TakeAction Processes a MultiSelect dialog action.

action An integer constant, variable, EQUATE, or expression that contains the action to
process. Valid actions are add (select), delete (deselect), move, begin process,
and end process.
item A string constant, variable, EQUATE, or expression that contains the value of the
list item affected by the action. If omitted, the action affects no item. For example
a begin process action is not associated with a list item.
oldposition An integer constant, variable, EQUATE, or expression that contains the ordinal
position of the item (in the Selected Items list) prior to the move action. If omitted,
oldposition defaults to zero (0), indicating a non-move action.
newposition An integer constant, variable, EQUATE, or expression that contains the ordinal
position of the item (in the Selected Items list) after the move action. If omitted,
newposition defaults to zero (0), indicating a non-move action.
The TakeAction method processes a MultiSelect dialog action for the EditMultiSelectClass object. The TakeAction
method is your opportunity to interpret and implement the meaning of the end user's selection.

Tip: The TakeAction processing is immediate and occurs while the MultiSelect dialog is open. The MultiSelect
dialog does not generate an action or an event when the dialog closes.

Implementation: The TakeEvent method (indirectly) calls the TakeAction method each time the end user makes a new
selection or moves a selection in the MultiSelect dialog.

Corresponding EQUATEs for the MultiSelect dialog action are declared in ABEIP.INC as follows:
MSAction ITEMIZE(1),PRE
Add EQUATE !add / select
Delete EQUATE !delete / deselect
Move EQUATE !reposition a selected item
StartProcess EQUATE !begin an add/delete series
EndProcess EQUATE !end an add/delete series
END

Example:
!This implementation of TakeAction converts the end user selections into
!comma separated items in a string.
Edit:PR:ApplyTo.TakeAction PROCEDURE(BYTE Action,<STRING Item>,LONG Pos1=0,LONG Pos2=0)
HoldIt CSTRING(1024) !indexable string of end user choices
Pos USHORT !index to parse end user selections
Comma USHORT !index to parse end user selections
ItemQ QUEUE !Q to reorder end user selections
Item CSTRING(100)
Ord BYTE
END
CODE
PARENT.TakeAction(Action,Item,Pos1,Pos2)
HoldIt=SELF.UseVar
CASE Action
OF MSAction:Add !end user selected an Item
404 ABC Library Reference

HoldIt=CHOOSE(HoldIt,HoldIt&','&Item,Item)
OF MSAction:Delete !end user deselected an Item
Pos=INSTRING(Item,HoldIt,1,1)
IF Pos=1 !first item
HoldIt=HoldIt[Pos+LEN(Item)+1 : LEN(HoldIt)] !deselect first item
ELSE
IF Pos+LEN(Item) > LEN(HoldIt) !last item
HoldIt=HoldIt[1 : Pos-2] !deselect last item
ELSE !deselect any other item
HoldIt=HoldIt[1 : Pos-1] & HoldIt[Pos+LEN(Item)+1 : LEN(HoldIt)]
END
END
OF MSAction:Move !Selected Item moved up or down
FREE(ItemQ) ! Pos1=Item's "old" position
CLEAR(ItemQ) ! Pos2=Item's "new" position
Comma=1
LOOP WHILE Comma !build Q of Selected Items
Comma = INSTRING(',',HoldIt,1,1) ! to use for repositioning
ItemQ.Ord+=1
IF Comma
ItemQ.Item = HoldIt[1 : Comma-1]
ADD(ItemQ,ItemQ.Ord)
HoldIt=HoldIt[Comma+1 : LEN(HoldIt)] !comma separated list of user choices
ELSE
ItemQ.Item = HoldIt
ADD(ItemQ,ItemQ.Ord)
END
END
ItemQ.Ord=Pos2
GET(ItemQ, ItemQ.Ord) !get the "bumped" item
ItemQ.Ord=Pos1
PUT(ItemQ) !reposition the "bumped" item
ItemQ.Item=Item
GET(ItemQ, ItemQ.Item) !get the selected item
ItemQ.Ord=Pos2
PUT(ItemQ) !reposition the selected item
SORT(ItemQ,ItemQ.Ord) !reorder Q of selected items
HoldIt=''

LOOP Pos = 1 TO RECORDS(ItemQ) !refill comma separated list

GET(ItemQ,Pos)
HoldIt=CHOOSE(Holdit,HoldIt&','&ItemQ.Item,ItemQ.Item)
END
OF MSAction:StartProcess !begin AddAll (>>) or DeleteAll (<<)
SETCURSOR(CURSOR:Wait)
OF MSAction:EndProcess !end AddAll (>>) or DeleteAll (<<)
SETCURSOR()
END
SELF.UseVar=HoldIt

See Also: TakeEvent

EditMultiSelectClass 405

TakeEvent (process edit-in-place events:EditMultiSelectClass)

TakeEvent( event ), VIRTUAL

TakeEvent Processes an event for the EditMultiSelectClass object.

event An integer constant, variable, EQUATE, or expression that contains the event number (see
EVENT in the Language Reference).
The TakeEvent method processes an event for the EditMultiSelectClass object and returns a value indicating the user
requested action. Valid actions are none, complete or OK, cancel, next record, previous record, next field, and previous
field.

Implementation: The BrowseClass.AskRecord method calls the TakeEvent method. The TakeEvent method
processes an EVENT:AlertKey for the edit-in-place control. On EVENT:DroppingDown, TakeEvent
invokes the MultiSelect dialog. Finally, TakeEvent returns a value indicating the user requested
action. The BrowseClass.AskRecord method carries out the user requested action.

Corresponding EQUATEs for the possible edit-in-place actions are declared in ABEIP.INC as follows:
EditAction ITEMIZE(0),PRE
None EQUATE ! no action
Forward EQUATE ! next field
Backward EQUATE ! previous field
Complete EQUATE ! OK
Cancel EQUATE ! cancel
Next EQUATE ! next record
Previous EQUATE ! previous record
Ignore EQUATE ! no action
END

Return Data Type: BYTE

Example:
EditClassAction ROUTINE
CASE SELF.EditList.Control.TakeEvent(EVENT())
OF EditAction:Forward !handle tab forward (new field, same record)
OF EditAction:Backward !handle tab backward (new field, same record)
OF EditAction:Next !handle down arrow (new record, offer to save prior record)
OF EditAction:Previous !handle up arrow (new record, offer to save prior record)
OF EditAction:Complete !handle OK or enter key (save record)
OF EditAction:Cancel !handle Cancel or esc key (restore record)
END
See Also: Init, BrowseClass.AskRecord
406 ABC Library Reference
EditTextClass 407

EditTextClass
EditTextClass: Overview
The EditTextClass is an EditClass that supports memo and large string fields by way of an edit-in-place COMBO control.

EditTextClass Concepts

The EditTextClass creates a COMBO control with an ellipsis button that invokes a text dialog.

The EditTextClass also signals the calling procedure whenever significant edit-in-place events occur, such as tabbing to a
new column, cancelling the edit, or completing the edit (moving to a new record or row). The EditTextClass provides a
virtual TakeEvent method to let you take control of significant edit-in-place events.

EditTextClass:Relationship to Other Application Builder Classes

EditClass
The EditTextClass is derived from the EditClass. The EditClass serves as the foundation and framework for its derived
classes. These derived classes each provide a different type of input control or input user interface. You can control the
values returned by these derived EditClass objects by using their virtual methods. See the Conceptual Example.

BrowseEIPManagerClass
The EditClass is managed by the BrowseEIPManagerClass. The BrowseEIPManagerClass depends on the EditClass
operating according to its documented specifications; however, the EditClass may be called by non-BrowseClass
procedures and objects.
408 ABC Library Reference

ABC Template Implementation

You can use the BrowseUpdateButtons control template (Configure EditInPlace) to generate the code to instantiate an
EditTextClass object called EditInPlace::fieldname and register the object with the BrowseClass object. The BrowseClass
object then calls the registered EditTextClass object's methods as needed. See Control Templates—
BrowseUpdateButtons for more information.

EditTextClass Source Files

The EditTextClass source code is installed by default to the Clarion \LIBSRC folder. The specific EditTextClass source
code and their respective components are contained in:

ABEIP.INC EditTextClass declarations

ABEIP.CLW EditTextClass method definitions
EditTextClass 409

EditTextClass Properties
The EditTextClass inherits all the properties of the EditClass from which it is derived. See EditClass Properties and
EditClass Concepts for more information.

In addition to the inherited properties, the EditTextClass contains the following properties:

Title (text dialog title text)

Title CSTRING(256)
The Title property contains a string that sets the title bar text in the dialog containing the text control.

Implementation: The EditTextClass (TakeEvent method) uses the Title property as the title text for the titlebar of the dialog
containing the text control.

See Also: TakeEvent

410 ABC Library Reference

EditTextClass Methods
The EditTextClass inherits all the methods of the EditClass from which it is derived. See EditClass Methods and EditClass
Concepts.

EditTextClass: Functional Organization—Expected Use

As an aid to understanding the EditTextClass it is useful to organize its methods into two large categories according to
their expected use—the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EditTextClass methods.

Non-Virtual Methods
The Non-Virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

InitVI initialize the EditTextClass object
KillVI shut down the EditTextClass object

Mainstream Use:
TakeEventVI handle events for the edit control

Occasional Use:
CreateContolV create the edit (COMBO) control
SetAlertsVI alert keystrokes for the edit control

V These methods are also virtual.

I These methods are inherited from the EditClass

Virtual Methods
Typically you will not call these methods directly—the Non-Virtual methods call them. However, we anticipate you will
often want to override these methods, and because they are virtual, they are very easy to override. These methods do
provide reasonable default behavior in case you do not want to override them.

InitI initialize the EditTextClass object

CreateContol create the edit COMBO control
SetAlertsI alert keystrokes for the edit control
TakeEventI handle events for the edit control
KillI shut down the EditTextClass object
EditTextClass 411

CreateControl (create the edit-in-place control:EditTextClass)

CreateControl, VIRTUAL, PROTECTED

The CreateControl method creates the edit-in-place COMBO control.

Implementation: The Init method calls the CreateControl method. The CreateControl method creates a COMBO control
with an ellipsis button.

Use the Init method or the CreateControl method to set any required properties of the COMBO control.

Example:
EditClass.Init PROCEDURE(UNSIGNED FieldNo,UNSIGNED ListBox,*? UseVar)
CODE
SELF.ListBoxFeq = ListBox
SELF.CreateControl()
ASSERT(SELF.Feq)
SELF.UseVar &= UseVar
SELF.Feq{PROP:Text} = ListBox{PROPLIST:Picture,FieldNo}
SELF.Feq{PROP:Use} = UseVar
SELF.SetAlerts

See Also: FEQ, EditClass.CreateControl

412 ABC Library Reference

TakeEvent (process edit-in-place events:EditTextClass)

TakeEvent( event ), VIRTUAL

TakeEvent Processes an event for the EditTextClass object.

event An integer constant, variable, EQUATE, or expression that contains the event number (see EVENT in the
Language Reference).
The TakeEvent method processes an event for the EditTextClass object and returns a value indicating the user
requested action. Valid actions are none, complete or OK, cancel, next record, previous record, next field, and previous
field.

Implementation: The EIPManager.TakeFieldEvent method calls the TakeEvent method. The TakeEvent method
processes an EVENT:AlertKey for the edit-in-place control. On EVENT:DroppingDown, TakeEvent
invokes a Windwo with a text control. Finally, TakeEvent returns a value indicating the user requested
action.

Corresponding EQUATEs for the possible edit-in-place actions are declared in ABEIP.INC as follows:
EditAction ITEMIZE(0),PRE
None EQUATE ! no action
Forward EQUATE ! next field
Backward EQUATE ! previous field
Complete EQUATE ! OK
Cancel EQUATE ! cancel
Next EQUATE ! next record
Previous EQUATE ! previous record
Ignore EQUATE ! no action
END

Return Data Type: BYTE

Example:
EditClassAction ROUTINE
CASE SELF.EditList.Control.TakeEvent(EVENT())
OF EditAction:Forward !handle tab forward (new field, same record)
OF EditAction:Backward !handle tab backward (new field, same record)
OF EditAction:Next !handle down arrow (new record, offer to save prior record)
OF EditAction:Previous !handle up arrow (new record, offer to save prior record)
OF EditAction:Complete !handle OK or enter key (save record)
OF EditAction:Cancel !handle Cancel or esc key (restore record)
END

See Also: Init

EIPManagerClass 413

EIPManagerClass
EIPManagerClass--Overview
The EIPManagerClass is a WindowManager that displays an edit-in-place dialog, and handles events for that dialog . The
EIPManagerClass is an abstract class--it is not useful by itself, but serves as the foundation and framework for the
BrowseEIPManagerClass. See BrowseEIPManagerClass.

EIPManagerClass Concepts
Each edit-in-place control is created on top of the browse from which it is called. The EIPManager dynamically creates an
edit-in-place object and control upon request (Insert, Change, or Delete) by the end user. When the end user accepts the
edited record the EIPManager destroys the edit-in-place object and control.

EIPManagerClass--Relationship to Other Application Builder Classes

WindowClass

The EIPManager class is derived from the WindowManager class.

BrowseClass

Each BrowseClass utilizing edit-in-place requires an BrowseEIPManager to manage the events and processes that are
used by each edit-in-place field in the browse.

The BrowseClass.AskRecord method is the calling method for edit-in-place functionality.

EditClasses

The EIPManager provides the basic or "under the hood" interface between the Edit classes and the Browse class. The
EIPManager uses the EditQueue to keep track of the fields in the browse utilizing edit-in-place.
414 ABC Library Reference

EIPManagerClass--ABC Template Implementation

The Browse template declares a BrowseEIPManager when the BrowseUpdateButtons control template enables default
edit-in-place support for the BrowseBox.

See Control Templates--BrowseBox and BrowseUpdateButtons for more information.

EIPManagerClass Source Files

The EIPManagerClass source code is installed by default to the Clarion \LIBSRC folder. The specific EIPManagerClass
source code and their respective components are contained in:

ABEIP.INC EditClass declarations

ABEIP.CLW EditClass method definitions
ABEIP.TRN EditClass translation strings
EIPManagerClass 415

EIPManagerClass--Conceptual Example
The following example shows a sequence of statements to declare, and instantiate an EIPManager object. The example
page-loads a LIST of actions and associated priorities, then edits the list items via edit-in-place. Note that the
BrowseClass object references the BrowseEIPManager which is an EIPManager object, as referenced in ABBrowse.INC.
PROGRAM

_ABCDllMode_ EQUATE(0)
_ABCLinkMode_ EQUATE(1)

INCLUDE('ABBROWSE.INC'),ONCE
INCLUDE('ABEIP.INC'),ONCE
INCLUDE('ABWINDOW.INC'),ONCE
MAP
END

Actions FILE,DRIVER('TOPSPEED'),PRE(ACT),CREATE,BINDABLE,THREAD
KeyAction KEY(ACT:Action),NOCASE,OPT
Record RECORD,PRE()
Action STRING(20)
Priority DECIMAL(2)
Completed DECIMAL(1)
END
END

Access:Actions &FileManager
Relate:Actions &RelationManager
GlobalErrors ErrorClass
GlobalRequest BYTE(0),THREAD
ActionsView VIEW(Actions)
END

Queue:Browse QUEUE
ACT:Action LIKE(ACT:Action)
ACT:Priority LIKE(ACT:Priority)
ViewPosition STRING(1024)
END
BrowseWindow WINDOW('Browse Records'),AT(0,0,247,140),SYSTEM,GRAY
LIST,AT(5,5,235,100),USE(?List),IMM,HVSCROLL,MSG('Browsing Records'),|
FORMAT('80L~Action~@S20@8R~Priority~L@N2@'),FROM(Queue:Browse)
BUTTON('&Insert'),AT(5,110,40,12),USE(?Insert),KEY(InsertKey)
BUTTON('&Change'),AT(50,110,40,12),USE(?Change),KEY(CtrlEnter),DEFAULT
BUTTON('&Delete'),AT(95,110,40,12),USE(?Delete),KEY(DeleteKey)
END

ThisWindow CLASS(WindowManager)
Init PROCEDURE(),BYTE,PROC,DERIVED
Kill PROCEDURE(),BYTE,PROC,DERIVED
END

BRW1 CLASS(BrowseClass)
Q &Queue:Browse
Init PROCEDURE(SIGNED ListBox,*STRING Posit,VIEW V,QUEUE Q,RelationManager RM,WindowManager WM)
END

BRW1::EIPManager BrowseEIPManager ! EIPManager for Browse using ?List

CODE
416 ABC Library Reference

GlobalErrors.Init
Relate:Actions.Init
GlobalResponse = ThisWindow.Run()
Relate:Actions.Kill
GlobalErrors.Kill

ThisWindow.Init PROCEDURE

ReturnValue BYTE,AUTO
CODE
SELF.Request = GlobalRequest
ReturnValue =PARENT.Init()
IF ReturnValue THEN RETURN ReturnValue.
SELF.FirstField = ?List
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
SELF.AddItem(Toolbar)
CLEAR(GlobalRequest)
CLEAR(GlobalResponse)
Relate:Actions.Open
FilesOpened = True
BRW1.Init(?List,Queue:Browse.ViewPosition,BRW1::View:Browse,Queue:Browse,Relate:Actions,SELF)
OPEN(BrowseWindow)
SELF.Opened=True
BRW1.Q &= Queue:Browse
BRW1.AddSortOrder(,ACT:KeyAction)
BRW1.AddLocator(BRW1::Sort0:Locator)
BRW1::Sort0:Locator.Init(,ACT:Action,1,BRW1)
BRW1.AddField(ACT:Action,BRW1.Q.ACT:Action)
BRW1.AddField(ACT:Priority,BRW1.Q.ACT:Priority)
BRW1.ArrowAction = EIPAction:Default+EIPAction:Remain+EIPAction:RetainColumn
BRW1.InsertControl=?Insert
BRW1.ChangeControl=?Change
BRW1.DeleteControl=?Delete
BRW1.AddToolbarTarget(Toolbar)
SELF.SetAlerts()
RETURN ReturnValue

ThisWindow.Kill PROCEDURE

ReturnValue BYTE,AUTO
CODE
ReturnValue =PARENT.Kill()
IF ReturnValue THEN RETURN ReturnValue.
IF FilesOpened
Relate:Actions.Close
END
RETURN ReturnValue

BRW1.Init|
PROCEDURE(SIGNED ListBox,*STRING Posit,VIEW V,QUEUE Q,RelationManagerRM,WindowManager WM)

CODE
PARENT.Init(ListBox,Posit,V,Q,RM,WM)
SELF.EIP &= BRW1::EIPManager ! Browse object's reference to the BrowseEIPManager
EIPManagerClass 417

EIPManagerClass Properties

Again (column usage flag)

Again BYTE, PROTECTED
The Again property contains a value that indicates whether or not the current edit-in-place column has been selected by
the user during an edit-in-place process.

The TakeEvent method is where the Again property receives a value.

Arrow (edit-in-place action on arrow key)

Arrow &BYTE
The Arrow property is a reference to a BYTE which indicates the action to take when the end user presses the up or
down arrow key during an edit-in-place process.

Note: The Arrow property should be treated as a PROTECTED property except during initialization.

Implementation: When the EIPManager is instantiated from a browse the Arrow property will point to the
BrowseClass.ArrowAction.

See Also: BrowseClass.ArrowAction

Column (listbox column)

Column UNSIGNED
The Column property contains a value that indicates the column number of the listbox field which currently has focus in
an edit-in-place process.
418 ABC Library Reference

Enter (edit-in-place action on enter key)

Enter &BYTE
The Enter property is a reference to the BrowseClass.EnterAction property, and indicates the action to take when the end
user presses the ENTER key during an edit-in-place process.

Note: The Enter property should be treated as a PROTECTED property except during initialization.

See Also: BrowseClass.EnterAction

EQ (list of edit-in-place controls)

EQ &EditQueue
The EQ property is a reference to a structure containing a list of browse list columns that will not utilize the default edit-in-
place control. This list includes columns that will not utilize edit-in-place.

Implementation: The AddControl method adds browse list columns to the EQ property. An entry without an associated
control indicates a column that has been specified as non-edit-in-place.

You do not need to initialize this property to implement the default edit-in-place controls. The EQ property
supports custom edit-in-place controls.

The EQ property is a reference to a QUEUE declared in ABEdit.INC as follows:

EditQueue QUEUE,TYPE
Field UNSIGNED
FreeUp BYTE
Control &EditClass
END

Note: The EQ property should be treated as a PROTECTED property except during initialization.

See Also: AddControl

EIPManagerClass 419

Fields (managed fields)

Fields &FieldPairsClass, PROTECTED

The Fields property is a reference to the FieldPairsClass object that moves and compares data between the BrowseClass
object's FILE and the EditClasses.

Note: The Fields property should be treated as a PROTECTED property except during initialization.

See Also: BrowseClass.TabAction

FocusLoss ( action on loss of focus)

FocusLoss &BYTE
The FocusLoss property is a reference to the BrowseClass.FocusLossAction property, and indicates the action to take
with regard to pending changes when the edit control loses focus during an edit-in-place process.

Note: The FocusLoss property should be treated as a PROTECTED property except during initialization.

See Also: BrowseClass.TabAction, BrowseClass.FocusLossAction

420 ABC Library Reference

Insert (placement of new record)

Insert BYTE
The Insert property indicates where in the list a new record will be added when the end user inserts a new record. The
default placement is below the selected record.

Implementation: There are three places a new record can be placed in a list when using edit-in-place: above the selected
record; below the selected record (the default); or appended to the bottom of the list.

Note: This does not change the sort order. After insertion, the list is resorted and the new record appears in the
proper position within the sort sequence.

The specified placements are implemented by the BrowseEIPManager.Init method. Set the record insertion point by
assigning, adding, or subtracting the following EQUATEd values to Insert. The following EQUATEs are in ABEdit.INC:
ITEMIZE,PRE(EIPAction)
Default EQUATE(0)
Always EQUATE(1)
Never EQUATE(2)
Prompted EQUATE(4)
Save EQUATE(7)
Remain EQUATE(8)
Before EQUATE(9) ! insert before/above selected record
Append EQUATE(10) ! insert at the bottom of the list
RetainColumn EQUATE(16)
END

See Also: BrowseEIPManager.Init

EIPManagerClass 421

ListControl (listbox control number)

ListControl SIGNED
The ListControl property contains the control number of the LIST control that is utilizing edit-in-place.

Note: The ListControl property should be treated as a PROTECTED property except during initialization.

See Also: BrowseClass.TabAction

LastColumn (previous edit-in-place column)

LastColumn BYTE, PROTECTED

The LastColumn property contains the column number of the previously used edit-in-place control to facilitate the
appropriate processing of a NewSelection.

Implementation: The LastColumn method is assigned the value of the Column property in the ResetColumn method.
422 ABC Library Reference

Repost (event synchronization)

Repost UNSIGNED, PROTECTED

The Repost property indicates the appropriate event to post to the edit-in-place control based on events posted from the
browse procedure window.

Implementation: The TakeEvent and TakeFieldEvent methods assign the appropriate value to the Repost property. The
Kill method posts the specified event to the appropriate edit-in-place control based on the value contained
in the RepostField property.

See Also: RepostField

RepostField (event synchronization field)

RepostField UNSIGNED, PROTECTED

The RepostField property contains the field control number of the listbox field that is being edited.

Implementation: The TakeFieldEvent method assigns the appropriate value to the RepostField property. The Kill method
posts the specified event to the appropriate edit-in-place control based on the value contained in the
RepostField property.

See Also: Repost

EIPManagerClass 423

Req (database request)

Req BYTE, PROTECTED

The Req property indicates the database action the procedure is handling. The EIPManager uses this property to make
appropriate processing decisions with regard to priming records, saving or abandoning changes, etc.

Implementation: The Run method is passed a parameter which contains the value assigned to the Req property.

See Also: WindowManager.Request

SeekForward (get next field flag)

SeekForward BYTE, PROTECTED

The SeekForward property indicates that the end user has pressed the TAB key during an edit-in-place process.

Implementation: The TakeAction method conditionally assigns a value of one (1) to the SeekForward property based on
the actions of the end user.

See Also: Next

Tab (action on a tab key)

Tab &BYTE
The Tab property is a reference to the BrowseClass.TabAction property that indicates the action to take when the end
user presses the TAB key during an edit-in-place process.

Note: The Tab property should be treated as a PROTECTED property except during initialization.

See Also: BrowseClass.TabAction

424 ABC Library Reference

EIPManagerClass Methods
EIPManagerClass--Functional Organization--Expected Use
As an aid to understanding the EIPManagerClass, it is useful to organize its methods into two large categories according
to their expected use--the Non-Virtual and the virtual methods. This organization reflects what we believe is typical use of
the EIPManagerClass methods.

Non-Virtual Methods

The Non-Virtual methods, which you are likely to call fairly routinely from your program, can be further divided into three
categories:

Housekeeping (one-time) Use:

Run run this procedure
InitD initialize the EditClass object
InitControls initialize edit-in-place controls
KillD shut down the EditClass object

Mainstream Use:
TakeAcceptAll handle all validation settings
TakeEventD handle events for the edit control
TakeNewSelectionD handle Event:NewSelection

Occasional Use:
AddControl register edit-in-place controls
ClearColumnV reset column property values
CreateContolV a virtual to create the edit control
GetEditV identify edit-in-place field
Next get the next edit-in-place field
ResetColumnV reset edit-in-place object to selected field
SetAlertsV alert appropriate keystrokes for the edit control
TakeActionV process end user actions
TakeCompletedV process completion of edit
TakeFocusLossV process loss of focus
TakeFieldEventD handle field specific events

D These methods are also derived.

V These methods are also virtual.
EIPManagerClass 425

Virtual and Derived Methods

Typically you will not call these methods directly--the Non-Virtual methods call them. However, we anticipate you will often
want to override these methods, and because they are either derived or virtual, they are very easy to override. These
methods do provide reasonable default behavior in case you do not want to override them.

InitD initialize the EditClass object

Kill D shut down the EditClass object
TakeEventD handle events for the edit control
TakeNewSelectionD handle Event:NewSelection
ClearColumnV reset column property values
CreateContolV a virtual to create the edit control
GetEditV identify edit-in-place field
ResetColumnV reset edit-in-place object to selected field
SetAlertsV alert appropriate keystrokes for the edit control
TakeActionV process end user actions
TakeCompletedV process completion of edit
TakeFocusLossV process loss of focus
TakeFieldEventD handle field specific events
426 ABC Library Reference

AddControl (register edit-in-place controls)

AddControl([EditClass], Column, AutoFree)

AddControl Specifies an edit-in-place control.

EditClass The label of the EditClass. If omitted, the specified column is not editable.
Column An integer constant, variable, EQUATE, or expression that indicates the browse
list column to edit with the specified editclass object.

AutoFree A numeric constant, variable, EQUATE, or expression that indicates whether the
BrowseClass.Kill method DISPOSEs of the editclass object. A zero (0) value
leaves the object intact. A non-zero value DISPOSEs the object.

The AddControl method specifies the editclass that defines the edit-in-place control for the browse column. Use autofree
with caution; you should only DISPOSE of memory allocated with a NEW statement. See the Language Reference for
more information on NEW and DISPOSE.

The AddControl method also registers fields which will not be editable via edit-in-place. In this instance the EditClass
parameter is omitted.

Implementation: The InitControls and BrowseClass.AddEditControl methods call the AddControl method. The
BrowseClass.AddEditControl method defines the editclass for a column not utilizing the default editclass.

The AddControl method ADDs a record containing the values of EditClass, Column, and AutoFree, to the
EditQueue which is declared in ABEdit.INC as follows:
EditQueue QUEUE,TYPE
Field UNSIGNED
FreeUp BYTE
Control &EditClass
END

Example:
BrowseClass.AddEditControl PROCEDURE(EditClass EC,UNSIGNED Id,BYTE Free)
CODE
SELF.CheckEIP
SELF.EIP.AddControl(EC,Id,Free)

See Also: EQ, InitControls, BrowseClass.AddEditControl

EIPManagerClass 427

ClearColumn (reset column property values:EIPManagerClass)

ClearColumn, VIRTUAL
The ClearColumn method checks for a value in the LastColumn property and conditionally sets the column values to zero
(0).

The TakeAction and TakeNewSelection methods call the ClearColumn method.

Example:
EIPManager.TakeNewSelection PROCEDURE ! Must be overridden to handle out -of-row clicks
CODE
IF FIELD() = SELF.ListControl AND KEYCODE() = MouseLeft ! An in-row mouse click
SELF.ClearColumn
SELF.Column = SELF.ListControl{PROPLIST:MouseUpField}
SELF.ResetColumn
END
RETURN Level:Benign

See Also: Column, TakeAction, TakeNewSelection

428 ABC Library Reference

GetEdit (identify edit-in-place field)

GetEdit, VIRTUAL, PROTECTED

The GetEdit method checks for a value in the Control field of the EditQueue.

Implementation: GetEdit is called by the Next method, and returns one (1) if any value is in the Control field of the
EditQueue, otherwise it returns zero (0).

Return Data Type: BYTE

Example:
EIPManager.Next PROCEDURE
CODE

GET(SELF.EQ,RECORDS(SELF.EQ))
? ASSERT(~ERRORCODE())
LastCol=SELF.EQ.Field

LOOP
CLEAR(SELF.EQ)
SELF.EQ.Field = SELF.Column
GET(SELF.EQ,SELF.EQ.Field)
IF ~ERRORCODE() AND SELF.GetEdit()
BREAK
END
!executable code

See Also: EQ, Next

EIPManagerClass 429

Init (initialize the EIPManagerClass object)

Init, DERIVED, PROC
The Init method initializes the EIPManagerClass object.

Implementation: The BrowseEIPManager.Init method calls the Init method. The Init method primes variables and calls the
InitControls method which then initializes the appropriate edit-in-place controls.

Return Data Type: BYTE

Example:
BrowseEIPManager.Init ! initialize BrowseEIPManagerClass object
!program code
RETURN PARENT.Init() ! call to the EIPManager.Init

See Also: BrowseEIPManager.Init, InitControls

InitControls (initialize edit-in-place controls)

InitControls, VIRTUAL
The InitControls method registers the default edit-in-place controls with the EIPManager by calling the AddControl
method, and initializes each added control.

Implementation: The Init method calls the InitControls method. The InitControls method checks for custom edit-in-place
controls in the EditQueue before adding a default edit-in-place control.

Example:
EIPManager.Init PROCEDURE
CODE
IF SELF.Column = 0 THEN SELF.Column = 1.
SELF.LastColumn = 0
SELF.Repost = 0
SELF.RepostField = 0
ASSERT(~SELF.EQ &= NULL)
SELF.EQ.Field = 1

SELF.InitControls
SELF.ResetColumn
RETURN Level:Benign

See Also: Init, EQ, AddControl

430 ABC Library Reference

Kill (shut down the EIPManagerClass object)

Kill, DERIVED, PROC

The Kill method frees any memory allocated during the life of the object and performs any other required termination
code. The Kill method must leave the object in a state in which an Init can be called.

Implementation: The BrowseEIPManager.Kill method calls the Kill method with a PARENT call. The Kill method destroys
the edit-in-place controls created by the InitControls method.

Return Data Type: BYTE

Example:
BrowseEIPManager.Kill PROCEDURE
CODE
SELF.BC.ResetFromAsk(SELF.Req,SELF.Response)
RETURN PARENT.Kill()

See Also: BrowseEIPManager.Kill

EIPManagerClass 431

Next (get the next edit-in-place field)

Next, PROTECTED
The Next method gets the next edit-in-place control in the direction specified (forward or backward) by the end user.

Implementation: The Next method loops through the EditQueue and gets the next edit-in-place control based on the
RETURN value of the GetEdit method.

Example:
EIPManager.ResetColumn PROCEDURE
CODE
SETKEYCODE(0)
SELF.Next
IF SELF.Column <> SELF.LastColumn
SELF.ListControl{PROP:Edit,SELF.EQ.Field} = SELF.EQ.Control.Feq
SELECT(SELF.EQ.Control.Feq)
SELF.LastColumn = SELF.Column
END

See Also: GetEdit, SeekForward, Column, EQ

432 ABC Library Reference

ResetColumn (reset edit-in-place object to selected field)

ResetColumn, VIRTUAL, PROTECTED

The ResetColumn method selects the appropriate edit-in-place control based on the selected listbox field.

Implementation: The ResetColumn method resets the FEQ to the selected ListControl field.

Example:
EIPManager.TakeCompleted PROCEDURE(BYTE Force)
CODE
SELF.Column = 1
IF SELF.Again
SELF.ResetColumn
END

See Also: EditClass.FEQ

Init, ListControl, TakeAction, TakeCompleted, TakeNewSelection
EIPManagerClass 433

Run (run the EIPManager)

Run( request )

Run Run the EIPManager.

request An integer constant, variable, EQUATE, or expression identifying the database action (insert, change,
delete) requested.
The Run method assigns the passed value to the Req property and executes the EIPManager.

Implementation: Return value EQUATEs are declared in \LIBSRC\TPLEQU.CLW as follows:

RequestCompleted EQUATE (1) !Update Completed
RequestCancelled EQUATE (2) !Update Cancelled

Return Data Type: BYTE

Example:
BrowseClass.AskRecord PROCEDURE(BYTE Req)
CODE
SELF.CheckEIP
RETURN SELF.EIP.Run(Req)

See Also: Req

434 ABC Library Reference

SetColumnEditType (set column's EditClass)

SetColumnEditType(ColumnNumber,<EditClass>)

SetColumnEditType Change EditClass used for a column.

ColumnNumber An integer constant or variable that contains the column number to process.

EditClass The label of the EditClass. If omitted, the specified columnnumber is disabled for EIP operations.

SetColumnEditType allows you to change the EditClass used for a column at runtime. If the EditClass parameter is
omitted, then that column will be disabled on EIP actions.

Implementation: SetColumnEditType should be called prior to the BrowseClass AskRecord parent call.

Example:
BRW1.AskRecord PROCEDURE(BYTE Request)

ReturnValue BYTE,AUTO

CODE
IF GLO:AccessLevel < Level:Supervisor !If not a supervisor
self.eip.SetColumnEditType(1) !Disable edit of 1st column
ELSE
!for docs only (not really needed here):
self.eip.SetColumnEditType(1,EditInPlace::PUB:PubID)
END
ReturnValue = PARENT.AskRecord(Request)
RETURN ReturnValue

See Also: AddControl

EIPManagerClass 435

TakeAcceptAll (validate completed row)

TakeAcceptAll ( ), VIRTUAL

TakeAcceptAll Processes edit-in-place validation.

When an Edit-in-Place row is completed, the TakeAcceptAll method will validate and reselect any column that is required
and empty, or any column that returns an EditAction:Cancel equate by the EditClass:TakeAccepted method, with the
exception of any cancel action performed during an Insert or Change session. If all columns are successfully validated,
TakeAcceptAll returns TRUE (1).

Return Value: BYTE

436 ABC Library Reference

TakeAction (process edit-in-place action)

TakeAction( action ), VIRTUAL

TakeAction Processes edit-in-place action.

action An integer constant, variable, EQUATE, or expression that contains the action to process. Valid
EQUATEs are forward, backward, next, previous, complete, and cancel.
The TakeAction method processes an EIPManager dialog action. The TakeAction method is your opportunity to interpret
and implement the meaning of the end user's selection.

Implementation: The TakeFieldEvent conditionally calls the TakeAction method.

Corresponding EQUATEs are declared in ABEIP.INC as follows:

EditAction ITEMIZE(0),PRE
None EQUATE
Forward EQUATE ! Next field
Backward EQUATE ! Previous field
Complete EQUATE ! OK
Cancel EQUATE ! Cancel
Next EQUATE ! Focus moving to Next record
Previous EQUATE ! Focus moving to Previous record
Ignore EQUATE
END

Example:
EIPManager.TakeFieldEvent PROCEDURE
I UNSIGNED(1)
CODE
IF FIELD() = SELF.ListControl THEN RETURN Level:Benign .
LOOP I = 1 TO RECORDS(SELF.EQ)+1
! Optimised to pick up subsequent events from same field
IF ~SELF.EQ.Control &= NULL AND SELF.EQ.Control.Feq = FIELD()
SELF.TakeAction(SELF.EQ.Control.TakeEvent(EVENT()))
RETURN Level:Benign
END
GET(SELF.EQ,I)
END
! Code to handle an unknown field

See Also: TakeFieldEvent

EIPManagerClass 437

TakeCompleted (process completion of edit:EIPManagerClass)

TakeCompleted( force ), VIRTUAL

TakeCompleted Determines the edit-in-place dialog's action after either a loss of focus or an end user action.
action An integer constant, variable, EQUATE, or expression that indicates an end user requested action.
The TakeCompleted method conditionally calls the ResetColumn method. The BrowseEIPManager.TakeCompleted
provides the bulk of the process completion functionality, and is derived from the TakeCompleted method.

Implementation: The BrowseEIPManager.TakeCompleted method calls the TakeCompleted method via PARENT syntax.
TakeFocusLoss and TakeAction also call the TakeCompleted method.

Note: TakeCompleted does not override the WindowManager.TakeCompleted method.

Example:
EIPManager.TakeFocusLoss PROCEDURE
CODE
CASE CHOOSE(SELF.FocusLoss&=NULL,EIPAction:Default,BAND(SELF.FocusLoss,EIPAction:Save))
OF EIPAction:Always OROF EIPAction:Default
SELF.TakeCompleted(Button:Yes)
OF EIPAction:Never
SELF.TakeCompleted(Button:No)
ELSE
SELF.TakeCompleted(0)
END

See Also: BrowseEIPManager.TakeCompleted, TakeFocusLoss, TakeAction

438 ABC Library Reference

TakeEvent (process window specific events)

TakeEvent, DERIVED, PROC

The TakeEvent method processes window specific events and returns Level:Notify for an EVENT:Size, EVENT:Iconize,
or EVENT:Maximize; it returns a Level:Fatal for an EVENT:CloseDown, EVENT:CloseWindow, or EVENT:Sized; all other
window events return a Level:Benign.

Implementation: The TakeFieldEvent method calls the TakeEvent method. The TakeEvent method calls the
TakeFocusLoss method subsequent to returning a Level:Fatal.

Return Data Type: BYTE

Example:
EIPManager.TakeFieldEvent PROCEDURE
I UNSIGNED(1)
CODE
IF FIELD() = SELF.ListControl THEN RETURN Level:Benign .
LOOP I = 1 TO RECORDS(SELF.EQ)+1
! Optimised to pick up subsequent events from same field
IF ~SELF.EQ.Control &= NULL AND SELF.EQ.Control.Feq = FIELD()
SELF.TakeAction(SELF.EQ.Control.TakeEvent(EVENT()))
RETURN Level:Benign
END
GET(SELF.EQ,I)
END
! Code to handle an unknown field

See Also: TakeFieldEvent, TakeFocusLoss

EIPManagerClass 439

TakeFieldEvent (process field specific events)

TakeFieldEvent, DERIVED, PROC

The TakeFieldEvent method processes all field-specific/control-specific events for the window. It returns a value
indicating whether edit-in-place process is complete and should stop.

TakeFieldEvent returns Level:Benign to indicate processing of this event should continue normally; it returns Level:Notify
to indicate processing is completed for this event and the ACCEPT loop should CYCLE; it returns Level:Fatal to indicate
the event could not be processed and the ACCEPT loop should BREAK.

Implementation: The WindowManager.TakeEvent method calls the TakeFieldEvent method.

Return value EQUATEs are declared in ABERROR.INC.

Return Data Type: BYTE

Example:
MyWindowManager.TakeEvent PROCEDURE
RVal BYTE(Level:Benign)
I USHORT,AUTO
CODE
IF ~FIELD()
RVal = SELF.TakeWindowEvent()
IF RVal THEN RETURN RVal.
END
CASE EVENT()
OF EVENT:Accepted; RVal = SELF.TakeAccepted()
OF EVENT:Rejected; RVal = SELF.TakeRejected()
OF EVENT:Selected; RVal = SELF.TakeSelected()
OF EVENT:NewSelection; RVal = SELF.TakeNewSelection()
OF EVENT:Completed; RVal = SELF.TakeCompleted()
OF EVENT:CloseWindow OROF EVENT:CloseDown
RVal = SELF.TakeCloseEvent()
END
IF RVal THEN RETURN RVal.
IF FIELD()
RVal = SELF.TakeFieldEvent()
END
RETURN RVal
440 ABC Library Reference

TakeFocusLoss (a virtual to process loss of focus)

TakeFocusLoss, VIRTUAL
The TakeFocusLoss method determines the appropriate action to take when the EIPManager window loses focus, and
calls the TakeCompleted method with the appropriate parameter.

Implementation: TakeEvent and TakeFieldEvent methods conditionally call the TakeFocusLoss method.

Example:
EIPManager.TakeFieldEvent PROCEDURE
I UNSIGNED(1)
CODE
IF FIELD() = SELF.ListControl THEN RETURN Level:Benign .
LOOP I = 1 TO RECORDS(SELF.EQ)+1
! Optimized to pick up subsequent events from same field
IF ~SELF.EQ.Control &= NULL AND SELF.EQ.Control.Feq = FIELD()
SELF.TakeAction(SELF.EQ.Control.TakeEvent(EVENT()))
RETURN Level:Benign
END
GET(SELF.EQ,I)
END
! Code to handle an unknown field

See Also: TakeCompleted

EIPManagerClass 441

TakeNewSelection (reset edit-in-place column:EIPManagerClass)

TakeNewSelection, DERIVED, PROC

The TakeFieldEvent method resets the edit-in-place column selected by the end user.

Implementation: TakeNewSelection is called by the BrowseEIPManager.TakeNewSelection method.

TakeNewSelection calls ResetColumn, and returns a Level:Benign.

Return Data Type: BYTE

Example:
BrowseEIPManager.TakeNewSelection PROCEDURE
CODE
IF FIELD() = SELF.ListControl
IF CHOICE(SELF.ListControl) = SELF.BC.CurrentChoice
RETURN PARENT.TakeNewSelection()
ELSE
! Code to handle Focus change to different record
END
END

See Also: ResetColumn

442 ABC Library Reference
EntryLocatorClass 443

EntryLocatorClass
EntryLocatorClass Overview
The EntryLocatorClass is a LocatorClass with an input control (ENTRY, COMBO, or SPIN). An Entry Locator is a multi-
character locator that activates when the locator control is accepted (not upon each keystroke).

Use an Entry Locator when you want a multi-character search on numeric or alphanumeric keys and you want to delay
the search until the user accepts the locator control. This delayed search reduces network traffic and provides a smoother
search in a client-server environment.

EntryLocatorClass Concepts

The EntryLocatorClass lets you specify a locator control and a sort field on which to search (the free key element) for a
BrowseClass object. The BrowseClass object uses the EntryLocatorClass to locate and scroll to the nearest matching
item.

When the end user places one or more characters in the locator control, then accepts the control by pressing TAB,
pressing a locator button, or selecting another control on the screen, the EntryLocatorClass object advances the
BrowseClass object's LIST to the nearest matching record.

EntryLocatorClass Relationship to Other Application Builder Classes

The BrowseClass uses the EntryLocatorClass to locate and scroll to the nearest matching item. Therefore, if your
program's BrowseClass objects use an Entry Locator, your program must instantiate the EntryLocatorClass for each use.
Once you register the EntryLocatorClass object with the BrowseClass object (see BrowseClass.AddLocator), the
BrowseClass object uses the EntryLocatorClass object as needed, with no other code required. See the Conceptual
Example.

EntryLocatorClass ABC Template Implementation

The ABC BrowseBox template generates code to instantiate the EntryLocatorClass for your BrowseBoxes. The
EntryLocatorClass objects are called BRWn::Sort#:Locator, where n is the template instance number and # is the sort
sequence (id) number. As this implies, you can have a different locator for each BrowseClass object sort order.

You can use the BrowseBox's Locator Behavior dialog (the Locator Class button) to derive from the EntryLocatorClass.
The templates provide the derived class so you can modify the locator's behavior on an instance-by-instance basis.
444 ABC Library Reference

EntryLocatorClass Source Files

The EntryLocatorClass source code is installed by default to the Clarion \LIBSRC folder. The specific EntryLocatorClass
source code and their respective components are contained in:

ABBROWSE.INC EntryLocatorClass declarations

ABBROWSE.CLW EntryLocatorClass method definitions

EntryLocatorClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a
BrowseClass object and related objects, including an EntryLocatorClass object. The example initializes and page-loads a
LIST, then handles a number of associated events, including scrolling, updating, and locating records.

Note that the WindowManager and BrowseClass objects internally handle the normal events surrounding the locator.

PROGRAM
INCLUDE('ABWINDOW.INC') !declare WindowManager class
INCLUDE('ABBROWSE.INC') !declare BrowseClass and Locator
MAP
END
State FILE,DRIVER('TOPSPEED'),PRE(ST),THREAD
StateCodeKey KEY(ST:STATECODE),NOCASE,OPT
Record RECORD,PRE()
STATECODE STRING(2)
STATENAME STRING(20)
END
END
StView VIEW(State) !declare VIEW to process
END
StateQ QUEUE !declare Q for LIST
ST:STATECODE LIKE(ST:STATECODE)
ST:STATENAME LIKE(ST:STATENAME)
ViewPosition STRING(512)
END
Access:State CLASS(FileManager) !declare Access:State object
Init PROCEDURE
END
Relate:State CLASS(RelationManager) !declare Relate:State object
Init PROCEDURE
END
VCRRequest LONG(0),THREAD

StWindow WINDOW('Browse States'),AT(,,123,152),IMM,SYSTEM,GRAY

PROMPT('Find:'),AT(9,6)
ENTRY(@s2),AT(29,4),USE(ST:STATECODE)
LIST,AT(8,5,108,124),USE(?StList),IMM,HVSCROLL,FROM(StateQ),|
FORMAT('27L(2)|M~CODE~@s2@80L(2)|M~STATENAME~@s20@')
END

ThisWindow CLASS(WindowManager) !declare ThisWindow object

Init PROCEDURE(),BYTE,PROC,VIRTUAL
Kill PROCEDURE(),BYTE,PROC,VIRTUAL
END
EntryLocatorClass 445

BrowseSt CLASS(BrowseClass) !declare BrowseSt object

Q &StateQ
END

StLocator EntryLocatorClass !declare StLocator object

StStep StepStringClass !declare StStep object

CODE
ThisWindow.Run() !run the window procedure

ThisWindow.Init PROCEDURE() !initialize things

ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Init() !call base class init
IF ReturnValue THEN RETURN ReturnValue.
Relate:State.Init !initialize Relate:State object
SELF.FirstField = ?ST:STATECODE !set FirstField for ThisWindow
SELF.VCRRequest &= VCRRequest !VCRRequest not used
Relate:State.Open !open State and related files
!Init BrowseSt object by naming its LIST,VIEW,Q,RelationManager & WindowManager
BrowseSt.Init(?StList,StateQ.ViewPosition,StView,StateQ,Relate:State,SELF)
OPEN(StWindow)
SELF.Opened=True
BrowseSt.Q &= StateQ !reference the browse QUEUE
StStep.Init(+ScrollSort:AllowAlpha,ScrollBy:Runtime)!initialize the StStep object
BrowseSt.AddSortOrder(StStep,ST:StateCodeKey) !set the browse sort order
BrowseSt.AddLocator(StLocator) !plug in the browse locator
StLocator.Init(?ST:STATECODE,ST:STATECODE,1,BrowseSt) !initialize locator object
BrowseSt.AddField(ST:STATECODE,BrowseSt.Q.ST:STATECODE) !set a column to browse
BrowseSt.AddField(ST:STATENAME,BrowseSt.Q.ST:STATENAME) !set a column to browse
SELF.SetAlerts() !alert any keys for ThisWindow
RETURN ReturnValue

ThisWindow.Kill PROCEDURE() !shut down things

ReturnValue BYTE,AUTO
CODE
ReturnValue = PARENT.Kill() !call base class shut down
IF ReturnValue THEN RETURN ReturnValue.
Relate:State.Close !close State and related files
Relate:State.Kill !shut down Relate:State object
GlobalErrors.Kill !shut down GlobalErrors object
RETURN ReturnValue
446 ABC Library Reference

EntryLocatorClass Properties
EntryLocatorClass Properties
The EntryLocatorClass inherits all the properties of the LocatorClass from which it is derived. See LocatorClass Properties
and LocatorClass Concepts for more information.

In addition to the inherited properties, the EntryLocatorClass also contains the following property:

Shadow (the search value)

Shadow CSTRING(40)
The Shadow property contains the search value for the entry locator.

The TakeKey method adds to the search value based on the end user's keyboard input. The
BrowseClass.TakeAcceptedLocator method implements the search for the specified value.

See Also: TakeKey, BrowseClass.TakeAcceptedLocator

EntryLocatorClass 447

EntryLocatorClass Methods
The EntryLocatorClass inherits all the methods of the LocatorClass from which it is derived. See LocatorClass Methods
and LocatorClass Concepts for more information.

GetShadow(return shadow value)

GetShadow, DERIVED
The GetShadow method returns the value of the Shadow property. The Shadow property is set based on the users
keyboard input into the entry locator field.

Return Data Type: STRING

See Also: EntryLocatorClass.SetShadow, EntryLocatorClass.Shadow

448 ABC Library Reference

Init (initialize the EntryLocatorClass object)

Init( [control] , freeelement [,ignorecase] [,browseclass ] )

Init Initializes the EntryLocatorClass object.

control An integer constant, variable, EQUATE, or expression that sets the locator control for the locator. If
omitted, the control number defaults to zero (0) indicating there is no locator control.
freeelement The fully qualified label of a component of the sort sequence of the searched data set. The ABC
Templates further require this to be a free component of a key. A free component is one that is not range
limited to a single value. Typically this is also the USE variable of the locator control.
ignorecase An integer constant, variable, EQUATE, or expression that determines whether the locator does case
sensitive searches or ignores case. A value of one (1) or True does case insensitive searches; a value of
zero (0) or False ignores case. If omitted, nocase defaults to 0.
browseclass The label of the BrowseClass object for the locator. If omitted, the LocatorClass object has no direct
access to the browse QUEUE or it's underlying VIEW.
The Init method initializes the EntryLocatorClass object.

Implementation: The Init method sets the values of the Control, FreeElement, NoCase, and ViewManager properties. The
Shadow property is the control's USE variable.

By default, only the StepLocatorClass and FilterLocatorClass use the browseclass. The other locator
classes do not.

Example:
BRW1::Sort1:Locator.Init(,CUST:StateCode,1) !without locator control
BRW1::Sort2:Locator.Init(?CUST:CustMo,CUST:CustNo,1) !with locator control

See Also: Control, FreeElement, NoCase, ViewManager

EntryLocatorClass 449

Set (restart the locator:EntryLocatorClass)

Set, DERIVED
The Set method prepares the locator for a new search.

Implementation: The Set method clears the FreeElement property and the Shadow property.

Example:
MyBrowseClass.TakeScroll PROCEDURE(SIGNED Event) !process a scroll event
CODE
!handle the scroll
SELF.PostNewSelection !post EVENT:NewSelection to list
IF ~SELF.Sort.Locator &= NULL !if locator is present
SELF.Sort.Locator.Set ! clear it
END
IF SELF.Sort.Thumb &= NULL !if thumb is present
SELF.UpdateThumbFixed ! reposition it
END

See Also: FreeElement, Shadow

450 ABC Library Reference

SetShadow(set shadow value)

SetShadow(shadow), DERIVED

SetShadow Set the Shadow property.

shadow A string constant, variable, EQUATE, or expression that contains the value to give to the Shadow
property.
The SetShadow property sets the Shadow property with the passed value.

See Also: EntryLocatorClass.GetShadow, EntryLocatorClass.Shadow

TakeAccepted (process an accepted locator value:EntryLocatorClass)

TakeAccepted, DERIVED
The TakeAccepted method processes the accepted locator value and returns a value indicating whether the browse list
display should change.

A locator value is accepted when the end user changes the locator value, then TABS off the locator control or otherwise
switches focus to another control on the same window.

Implementation: The TakeAccepted method primes the FreeElement property with the entered search value, then returns
one (1 or True) if a new search is required or returns zero (0 or False) if no new search is required.

Return Data Type: BYTE

Example:
MyBrowseClass.TakeAcceptedLocator PROCEDURE
CODE
IF ~SELF.Sort.Locator &= NULL !if locator is present
IF SELF.Sort.Locator.TakeAccepted() !if locator value requires a search
SELF.Reset(1) !reposition the view
SELECT(SELF.ListControl) !focus on the list control
SELF.ResetQueue( Reset:Done ) !reset the browse queue
SELF.Sort.Locator.Reset !reset the locator USE variable
END
END

See Also: FreeElement

EntryLocatorClass 451

TakeKey (process an alerted keystroke:EntryLocatorClass)

TakeKey, DERIVED
The TakeKey method processes an alerted keystroke for the LIST control that displays the data to be searched and
returns a value indicating whether the browse list display should change. By default, all alphanumeric keys are alerted
for LIST controls.

Implementation: The BrowseClass.TakeKey method calls the locator TakeKey method. The TakeKey method stuffs the
keystroke detected by the LIST into the locator's input control and returns zero (0 or False).

Return Data Type: BYTE

Example:
MyBrowseClass.TakeKey PROCEDURE
CODE
IF RECORDS(SELF.ListQueue)
CASE KEYCODE()
OF InsertKey OROF DeleteKey OROF CtrlEnter OROF MouseLeft2 ;!handle keys
ELSE
DO CheckLocator !handle all other keystrokes
END
END
RETURN 0

CheckLocator ROUTINE
IF ~(SELF.Sort.Locator &= NULL)
IF SELF.Sort.Locator.TakeKey() !add keystroke to locator input control
SELF.Reset(SELF.GetFreeElementPosition()) !and refresh browse if necessary
SELF.ResetQueue(Reset:Done)
DO HandledOut
ELSE
IF RECORDS(SELF.ListQueue)
DO HandledOut
END
END
END

HandledOut ROUTINE
SELF.UpdateWindow
SELF.PostNewSelection
RETURN 1

See Also: BrowseClass.TakeKey

452 ABC Library Reference

Update (update the locator control and free elements)

Update, PROTECTED, VIRTUAL

The Update method redraws the locator control and updates the free key elements in the record buffer with the current
locator value.

Implementation: The Update method primes the FreeElement property with the current search value (the Shadow
property), then calls the UpdateWindow method to redraw the locator control.

Example:
MyBrowseClass.UpdateWindow PROCEDURE !update browse related controls
CODE
IF ~(SELF.Sort.Locator &= NULL) !if locator is present
SELF.Sort.Locator.UpdateWindow !redraw locator control
END

See Also: FreeElement, Shadow, UpdateWindow

UpdateWindow (redraw the locator control)

UpdateWindow, DERIVED
The UpdateWindow method redraws the locator control with the current locator value.

Implementation: The Update method calls the UpdateWindow method to redraw the locator control with the current locator
contents.

Example:
MyBrowseClass.UpdateWindow PROCEDURE !update browse related controls
CODE
IF ~(SELF.Sort.Locator &= NULL) !if locator is present
SELF.Sort.Locator.UpdateWindow ! redraw locator control
END

See Also: Update

ErrorClass 453

ErrorClass
ErrorClass Overview
The ErrorClass declares an error manager which consistently and flexibly handles any errors. That is, for a given program
scope, you define all possible errors by ID number, severity, and message text, then when an error or other notable
condition occurs, you simply pass the appropriate ID to the error manager which processes it appropriately based on its
severity level.

The defined "errors" may actually include questions, warnings, notifications, messages, benign tracing calls, as well as
true errors. The ErrorClass comes with about forty general purpose database errors already defined. You can expand this
list to include additional general purpose errors, your own application-specific errors, or even field specific data validation
errors. Your expansion of the errors list may be "permanent" or may be done dynamically at runtime.

Overview of ErrorClass changes after Clarion version 6.1

In Clarion version 5.5 and prior, the Error Class was designed to be a Global class, using just one instance of the class in
a program (EXE or EXE with multi DLL) that would be used by the entire application. This was possible because the
previous thread model did not allow two different threads to use the global ErrorClass at the same time. With the
incorporation of the new thread model in Clarion 6, this limitation disappears, and it is now possible that the global
ErrorClass can be used by two different threads at the same time.

In the first release (Clarion 6.0), the ErrorClass was changed to a THREADed Class. This change made it safe to be
used in a preemptive thread environment.

There are other possible designs that could have been used. Another approach that could have been taken would be to
add thread synchronization to the class. Yet another design approach is to divide the class into two classes: one class
contains thread dependent data and the other contains thread independent data. This is the design approach that has
been implemented in version 6.1.

If a class has some data that needs to be thread specific and other data that does not, there are several design options
that need to be considered.

For thread independent data, a solution is to add some kind of synchronization to the class (e.g., CriticalProcedure) in
order to prevent two different threads from accessing these values at the same time. Of course, care must be used in that
the data and scope where we use it should maintain this synchronization.

For the thread dependent data, one solution is to move the threaded data to a synchronized queue that stores the data,
using the thread number as the queue's key. Another solution (and the one used with Clarion 6.1) is to create a new class
(ErrorStatusClass) that is specifically used as a container for the thread dependent data. This second option is equivalent
to working with only one class (the ErrorClass) that has threaded and non-threaded parts. The thread dependent part will
create and destroy a new instance for each thread and the thread independent part stores the "thread independent ID" of
the thread dependent part so it can use it with the associated thread number in order to get the correct reference to the
threaded class for a specific thread.

Because any access to the threaded class parts will need to be done using some function that first retrieves the correct
class reference, the changes made in the ErrorClass for version 6.1 emulates this implementation, where all access to the
key property attributes are now done through an associated pair of GETpropertyname and SETpropertyname methods,
where propertyname is the property that is affected.

Sometimes these GET/SET methods are used to wrap the synchronized object, and other times they control the access to
the specific threaded class‘ properties or queues.

Also, these changes to the ErrorClass simplify its use in multi DLL applications, because the global ErrorClass is
consistent for each thread, and synchronization is straightforward.
454 ABC Library Reference

Also, this change maintains the ability to customize errors in only one place and use them throughout the application. A
single queue is used to store the error list, so extra memory is not required by additional threads. All methods are
declared in the non-threaded class, so only a single instance of these methods is loaded in memory. Access to the global
class is implemented in such a way that the addition of the synchronization methods will not slow down the application‘s
performance.

ErrorClass Source Files

The ErrorClass source code is installed by default to the Clarion \LIBSRC. The specific ErrorClass source code and their
respective components are contained in:

ABERROR.INC ErrorClass declarations

ABERROR.CLW ErrorClass method definitions
ABERROR.TRN ErrorClass default error definitions

Multiple Customizable Levels of Error Treatment

Six Levels of Treatment

By default, the error manager recognizes six different levels of error severity. The default actions for these levels range
from no action for benign errors to halting the program for fatal errors. The error manager also supports the intermediate
actions of simply notifying the user, or of notifying the user and letting the user decide whether to continue or abort.

Customizable Treatments

These various levels of treatment are implemented with virtual methods so they are easy to customize. The error manager
calls a different virtual method for each severity level, so you can override the default error actions with your own
application specific error actions. See the various Take methods for examples.

The recognized severity EQUATEs are declared in ABERROR.INC. These severity levels and their default actions are:

Level:Benign no action, returns Level:Benign

Level:User displays message, returns Level:Benign or Level:Cancel
Level:Notify displays message, returns Level:Benign
Level:Fatal displays message, halts the program
Level:Program treated as Level:Fatal
Level:Cancel used to confirm no action taken by User
any other value treated as Level:Program

You may define your own additional severity levels and their associated actions.
ErrorClass 455

Predefined Windows and Database Errors

A list of common database errors are defined in ABERROR.TRN for your use and for the ABC Templates. The defined
"errors" include questions, warnings, messages, notifications, benign tracing calls, as well as true errors.

You may edit these error definitions to suit your own requirements. That is, you may add new error definitions, change the
wording of the error message text, or even translate the English text to another language.

Note: If you use the ABC Templates you should not remove any of the default error definitions or change their
ID numbers.

Dynamic Extensibility of Errors

You may add new error definitions, override default error definitions, and modify default error definitions at runtime with
the methods provided for these purposes:

AddErrors Adds new errors, overrides errors, or both.

RemoveErrors Removes errors, restores overridden errors, or both.
SetFatality Modifies the severity level of an error.

ErrorClass ABC Template Implementation

The ABC Templates instantiate a global ErrorClass object called GlobalErrors. All template recognized errors are defined
at program startup and almost every generated procedure then relies on the GlobalErrors object to handle known error
conditions. You can use the Application Template's Global Properties dialog to specify a different class to instantiate as
GlobalErrors--providing complete flexibility for error handling in your template generated procedures.

ErrorClass Relationship to Other Application Builder Classes

All the classes that access files (ASCIIFileClass, ASCIIViewerClass, FileManager, RelationManager, ViewManager, and
BrowseClass) use the ErrorClass. Therefore, if your program instantiates any of these classes, it must also instantiate the
ErrorClass.
456 ABC Library Reference

ErrorClass Macro Expansion

The following ErrorClass methods allow runtime customization of error message text through expansion of macro
symbols:

SetField Names the field that produced the error.

SetFile Names the file that produced the error.
ThrowFile Names the file that produced the error, then handles the error.
ThrowMessage Modifies error text, then handles the error.

Each error has associated message text. The error message text may contain macro symbols recognized by the
ErrorClass object. The ErrorClass object expands these macro symbols to their current runtime values before displaying
the message. Supported macros and their runtime substitution values are:

%File The ErrorClass.FileName property

%Field The ErrorClass.FieldName property
%Message The ErrorClass.MessageText property
%Error Value returned by ERROR()
%ErrorCode Value returned by ERRORCODE()
%FileError Value returned by FILEERROR()
%FileErrorCode Value returned by FILEERRORCODE()
%ErrorText %Error(%ErrorCode) or %FileError(%FileErrorCode)
%Previous Text from prior defined error with the same id

The %ErrorText macro uses %FileError(%FileErrorCode)--the more specific backend server error information--when it is
available, otherwise it uses %Error(%ErrorCode).

This macro expansion capability is a feature of the ErrorClass and is not a feature of the Clarion language in general.

Tip: You do not need to specify two percent signs (%%) to display a percent sign (%) in your message text.
ErrorClass 457

ErrorClass Multi-Language Capability

Because all error message text is defined in one place (ABERROR.TRN), it is easy to implement non-English error
messages. For static (permanent) language translation, simply translate the English text in ABERROR.TRN to the
language of your choice. Alternatively, for dynamic language translation, you may add an error definition block to
ABERROR.TRN for each supported language. For example in ABERROR.TRN declare:
DefaultErrors GROUP !English error messages
END
GermanErrors GROUP !German error messages
END

Then at runtime, initialize the error manager with the appropriate error definition block. For example, you could override
the Init method (defined in ABERROR.CLW) with something like this:
INCLUDE('ABERROR.INC') !declare ErrorClass
MyErrorClass CLASS(ErrorClass) !declare derived class
Init PROCEDURE(BYTE PreferredLanguage)
END

GlobalErrors MyErrorClass !declare GlobalErrors object

Language BYTE !Language Flag
Language:English EQUATE(0) !English equate
Language:German EQUATE(1) !German equate

CODE
Language = GETINI('Preferences','Language',0) !get language preference
GlobalErrors.Init(Language) !GlobalErrors initialization
!with preferred language

MyErrorClass.Init PROCEDURE(BYTE PreferredLanguage) !New Init method

CODE
SELF.Errors &= NEW ErrorEntry !allocate new Errors list
CASE PreferredLanguage !which language was selected
OF Language:German !if German
SELF.AddErrors(GermanErrors) !add German errors to list
ELSE !otherwise...
SELF.AddErrors(DefaultErrors) !add default (English) errors
END

Alternatively, you could call the AddErrors method to define additional errors for the selected language as shown in the
following example.
458 ABC Library Reference

ErrorClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate an
ErrorClass object.

PROGRAM
INCLUDE('ABERROR.INC') !include ErrorClass declarations

AppErrors GROUP !declare app specific errors

Number USHORT(2) !number of errors in this group
USHORT(Msg:DuplicateKey) !first error ID
BYTE(Level:Notify) !severity level
PSTRING('Duplicate Key') !window title
PSTRING('%File key is invalid.') !message text with macro
USHORT(Msg:FieldOutOfRange) !second error ID
BYTE(Level:Notify) !severity level
PSTRING('Range Error') !window title
PSTRING('%Field must be between %Message.') !message text
END

GlobalErrors ErrorClass !declare GlobalErrors object

CODE
GlobalErrors.Init !initialize (add default errors)
GlobalErrors.AddErrors(AppErrors) !add app specific errors
GlobalErrors.SetFatality(Msg:DuplicateKey,Level:Fatal) !modify severity of an error
!
!program code
!
!user attempts to enter invalid month value...
GlobalErrors.SetField('Month') !set %Field for macro expansion
GlobalErrors.ThrowMessage(Msg:FieldOutOfRange,'1 and 12')!pass error to errormanager
!
!user attempts to insert a duplicate key...
GlobalErrors.SetFile('Customer') !set %File for macro expansion
GlobalErrors.Throw(Msg:DuplicateKey) !pass error to errormanager
!program code
!
GlobalErrors.Kill !shut down GlobalErrors object
ErrorClass 459

ErrorClass Properties
ErrorClass Properties
There are two types of ErrorClass properties, the Errors list and the macro substitution values. The most important
property is the Errors list--the list of errors recognized by ErrorClass. The defined "errors" may actually include questions,
warnings, notifications, benign tracing calls, as well as true errors. This list is established by the ErrorClass initialization
method, ErrorClass.Init. The list may be modified thereafter by methods provided for this purpose, allowing application
specific errors (such as field specific invalid data messages).

The other three ErrorClass properties support the error text "macros" recognized by the error manager. The error
manager expands these macro symbols to their current runtime values before displaying the message.

DefaultCategory (error category)

DefaultCategory ASTRING, PRIVATE

The DefaultCategory is a string that is a classification of the type of error. This property is set by the SetCategory. The
Init method sets the DefaultCategory to 'ABC'. When the category is changed by SetCategory, the new category becomes
the default category.

This property is private, but can be accessed through the SetDefaultCategory and GetDefaultCategory methods.
See Also:
ErrorClass.Init, ErrorClass.SetCategory, ErrorClass.GetCategory, SetDefaultCategory, GetDefaultCategory
460 ABC Library Reference

ErrorLog (errorlog interface)

ErrorLog &ErrorLogInterface, PROTECTED

The ErrorLog property is a reference to the errorlog interface that manages the error log file.

Errors (recognized error definitions)

Errors &ErrorEntry, PRIVATE

The Errors property is a reference to the data structure that holds all errors recognized by the ErrorClass. The defined
"errors" may actually include questions, warnings, messages, notifications, benign tracing calls, as well as true error
conditions.

The default errors are defined in ABERROR.TRN. You may edit ABERROR.TRN to customize the default error list. The
Init method adds these default error definitions to the Errors property at runtime. You may also use the SetFatality
method, the AddErrors method, and the RemoveErrors method to customize the Errors property at runtime.

The SetFatality method changes the severity level of a specified error.

The AddErrors method lets you add more error definitions, override existing error definitions, or both. The Errors property
may have more than one error with the same ID. Error definitions added later "override" any earlier definitions with the
same IDs. The "overridden" definitions are preserved for substitution into the %Previous macro symbol.

The RemoveErrors method lets you remove error definitions, restore previously overridden errors, or both.

The error message text may contain "macros" recognized by the error manager. The error manager expands these macro
symbols to their current runtime values before displaying the message. See Macro Expansion for more information.

Implementation: Errors is a reference to a queue declared in ABERROR.INC as follows. For each recognized error, the
Errors property includes an ID number, error message text, window title text, and a severity indicator.
ErrorEntry QUEUE,TYPE !List of all error definitions
Id USHORT !Error message identifier
Message &STRING !Message text
Title &STRING !Error window caption bar text
Fatality BYTE !Severity of error
END

See Also: AddErrors, Init, RemoveErrors, SetFatality

FieldName (field that produced the error)

FieldName CSTRING(MessageMaxlen), PRIVATE
The FieldName property contains the name of the field that produced the error. The SetField method sets the value of the
FieldName PRIVATE property, which is now part of the ErrorStatusGroup. The FieldName value replaces any %Field
symbols within the error message text.

MessageMaxlen is a constant EQUATE declared in ABERROR.INC.

See Also: SetField

ErrorClass 461

FileName (file that produced the error)

FileName CSTRING(MessageMaxlen), PRIVATE
The FileName property contains the name of the file that produced the error. The SetFile and ThrowFile methods both set
the value of the FileName PRIVATE property, which is now part of the ErrorStatusGroup. The FileName value then
replaces any %File symbols within the error message text.

MessageMaxlen is a constant EQUATE declared in ABERROR.INC.

See Also: SetFile, ThrowFile

History (error history structure)

History &ErrorHistoryList,PROTECTED
The History property is a reference to the ErrorHistoryList structure that holds the history for errors that have previously
occurred. The error History is determined based on the HistoryThreshold and HistoryResetOnView properties.
462 ABC Library Reference

HistoryResetOnView(clear error history log file)

HistoryResetOnView BYTE, PRIVATE
The HistoryResetOnView property determines if the error history view structure should be cleared upon viewing an error
message. If this property is set to one (1 or True), the History structure will be reset after each error is viewed. Setting this
property to zero (0 or False) will cause the errors to be queued in the History structure.

This property is now private, and is set through the SetHistoryResetOnView and GetHistoryResetOnView ErrorClass
methods.

HistoryThreshold (determine size of error history)

HistoryThreshold LONG, PRIVATE
The HistoryThreshold property sets the number of items to store in the error log file. Setting this property to -1 keeps all
errors. Setting this property to 0 switches off error history logging.

This property is now private, and is set through the SetHistoryThreshold and GetHistoryThreshold methods.

HistoryViewLevel (trigger error history)

HistoryViewLevel LONG, PRIVATE
The HistoryViewLevel property sets the error level which triggers error history viewing. This property is only valid with a
HistoryThreshold other than 0.

Use the following equates to set the error level. You can also set this property in the Application Generator Global Classes
dialog:
Level:Benign no action, returns Level:Benign
Level:User displays message, returns Level:Benign or Level:Cancel
Level:Notify displays message, returns Level:Benign
Level:Fatal displays message, halts the program
Level:Program treated as Level:Fatal
Level:Cancel used to confirm no action taken by User

This property is now private, and is set through the SetHistoryViewLevel and GetHistoryViewLevel methods.

KeyName (key that produced the error)

KeyName CSTRING(MessageMaxlen), PRIVATE
The KeyName property contains the name of the key that produced the error. The SetKey method sets the value of the
KeyName PRIVATE property, which is not part of the ErrorStatusGroup. The KeyName value then replaces any %Key
symbols within the error message text.

MessageMaxlen is a constant EQUATE declared in ABERROR.INC.

See Also: SetKey

ErrorClass 463

LogErrors (turn on error history logging)

LogErrors BYTE, PRIVATE
The LogErrors property turns the error history logging on or off. Setting this property to one (1 or True) turns on the error
logging. Setting this property to zero (0 or False) turns off the error logging.

This property is now private, and is set through the SetLogErrors and GetLogErrors methods.

MessageText (custom error message text)

MessageText CSTRING(MessageMaxlen), PRIVATE
The MessageText property contains text to substitute for any %Message symbols within the error message text. The
ThrowMessage method sets the value of the MessageText PRIVATE property, which is now a part of the
ErrorStatusGroup. The MessageText value then replaces any %Message symbols within the error message text.

MessageMaxlen is a constant EQUATE declared in ABERROR.INC.

See Also: ThrowMessage

Silent (silent error flag)

Silent BYTE, PRIVATE

The Silent property determines whether an error will be displayed to the screen. If Silent is set to one (1 or True), the
error message box will not be displayed to the screen; however it will be added to the error log file. If Silent is set to zero,
(0 or False) the error is displayed to the screen as well as added to the error log file.

This property is now private, and is set through the SetSilent and GetSilent methods.
464 ABC Library Reference

ErrorClass Methods
ErrorClass Functional Organization--Expected Use
As an aid to understanding the ErrorClass, it is useful to organize