Visual 1

Visual PRO/5®
CONFIGURATOR
DDBUILDER®
USING THE GRID CONTROL IN VISUAL PRO/5
GUIBUILDER™
GUI CONTROLS AND EVENTS
RESBUILDER™
RESCOMPILER
RESOURCE PROPERTY INDEX
SENDMSG() FUNCTIONS
BASIS International Ltd.

November 1, 1999
Copyright Notice
This manual is copyrighted by BASIS International Ltd., Albuquerque, New Mexico © 1999. All rights reserved. Portions © 1986 by
the University of Toronto. Written by Henry Spencer. Not derived from licensed software. © 1980 The Regents of the University of
California. All rights reserved. Portions © Informix Software, Inc. All rights reserved. No part of this manual may be reproduced by
electronic, digital, or mechanical methods without the express written permission of BASIS International Ltd. Information
contained in this document is subject to change without notice.
BASIS International Ltd. BASIS Technical Support email: support@basis.com
5901 Jefferson Street NE BASIS Technical Support telephone: 505.345.5021
Albuquerque, NM 87109-3432 BASIS Technical Support fax: 505.344.9057
Main Telephone: 505.345.5232
Main Fax: 505.345.5082
Email: info@basis.com
Web site: www@basis.com
Trademarks
BBX®, Visual PRO/5®, PRO/5®, PRO/5 Data Server®, The BASIS ODBC Driver® and DDBuilder® are registered trademarks of
BASIS International Ltd. ResBuilder™ and GUIBuilder™ are trademarks of BASIS International Ltd. All other product names and
brand names are service marks and/or trademarks or registered trademarks of their respective companies.
Contacting BASIS
If you purchased your BASIS product from a Distributor, Reseller, OEM, or any company outside the United States, you need to
contact your dealer for technical support. These BASIS dealers will either answer your question or will contact us on your behalf.
All customers who purchase products from BASIS automatically receive thirty days of free telephone support, beginning with your
first call to our department. After thirty days, you can either receive technical support for US$ 35.00 per topic (charged to your
American Express, VISA, or MasterCard), or purchase a technical support contract from our Sales Department. You can also
receive technical support via fax or e-mail for free.
Requests that come to us by phone or voice mail receive the highest priority. A higher priority is assigned to requests with
complete information. Faxed and e-mailed requests receive a lower priority than phoned requests; as with voice mail, priority is
given to requests with complete information. For informal support needs, you can use our online discussion forums to share your
question or information with hundreds of other BASIS product users around the world.
When contacting BASIS for technical support, be prepared to provide the following:
Contact information Your name, name of your company, telephone and/or fax number.
Serial Number Even though a product's serial number may not be required for support, the number is used to log
and track the call. By tracking all calls, we can see the types of questions we receive and then use
this information to determine how we may improve our service to you. Serial numbers also provide a
reliable method for retrieving key pieces of information about a particular product, such as the BASIS
part number, media type, revision level, activation key/license number and customer update history
The name of the product and the product's revision number are two other key pieces of information
because new revisions interact differently with hardware equipment
PRO/5 Error and TCB(10) A complete description of the problem, including the PRO/5 error and the TCB(10) value is helpful
when available. When a specific error is available, include the PRO/5 line or function in which the
error occurred and the values of all variables used in the line. The value for TCB(10) gives us an
indication of where the problem is originating.
Operating system name, When we know the operating system you are using, we occasionally find a mismatch between the
level, and revision BASIS product and that system or can identify oddities peculiar to a specific operating system.
Other Information When pertinent to the problem, answers to the following questions help Technical Support correctly
identify a problem:
Is the error consistently reproducible, or is it sporadic?
Is the error isolated to a specific machine or user?
Is this a new install or has the system been in place and working for a long time?
Is the problem network related/specific?
To help you organize this information, we have created a faxable technical support request form that lists information we need to
start working on your question. You can either call us and have us fax the form to you, or download it from the BASIS web site.
Table of Contents
CONFIGURATOR 1
Introduction 1
The Configurator Interface 1
Getting Started 1
Creating New Configuration Files 1
Opening Existing Configuration Files 1
Saving Configuration Files 2
Printing Configuration Files 2
Exiting Configurator 2
Setting Configuration File Options 2
Setting DSKSYN, SYSGUI, and Limits Configuration Options 2
Setting PREFIX and Global String Options 3
Setting SYSWINDOW Options 3
Setting SYSPRINTER Options 4
Setting Printer Options 5
Setting Plotter Properties 8
Setting TCP Socket Options 9
Setting UDP Socket Options 9
Setting SETOPTS Options 9
Setting SQL Options 10
Setting Novell-Specific Options 11
DDBUILDER 15
Introduction 15
What is a Data Dictionary? 15
Using DDBuilder 15
Setup Files 17
The DDBuilder Interface 18
Getting Started 18
Creating a New Data Dictionary 18
Opening an Existing Data Dictionary 19
Saving a Data Dictionary 20
Printing the DDBuilder Tree View 21
Closing a Data Source 21
Exiting DDBuilder 21
Modifying Data Dictionary Elements 22
Adding Elements to a Data Dictionary 22
Inserting Columns into a Data Dictionary 22
Copying Data Dictionary Elements to the Clipboard 22
Pasting Data Dictionary Elements from the Clipboard 22
Deleting Elements from a Data Dictionary 23
Reversing/Reinstating the Last Modification 23
Renaming Data Dictionary Elements 23
DDBuilder Naming Conventions and Reserved Words 23
Defining General Data Dictionaries 24
Defining General Data Sources 24
Defining General Table Attributes 24
Defining General Column Attributes 25
Defining Indices 26
Defining Data Dictionaries for Use with TAOS 26
i
Defining General Rules 26
Defining Typedefs 27
Defining General Typedef Attributes 27
Defining Typedef Input Attributes 28
Defining Typedef Output Attributes 29
Defining Application-Specific Typedef Attributes 29
Selecting Rules for Typedefs 30
Editing Typedef Rules 31
Defining Table Form and Process Attributes 32
Defining Application-Specific Table Attributes 32
Selecting Tables Rules 33
Editing Table Rules 34
Defining Column Input Attributes 35
Defining Column Output Attributes 36
Defining Application-Specific Column Attributes 36
Selecting Rules for Columns 37
Editing Column Rules 38
Creating and Defining Views 39
Defining Views for Use with Non-Normalized Data 44
USING THE GRID CONTROL IN VISUAL PRO/5 49
Introduction 49
Standard and Data-Aware Grids 49
Standard Grid Control Tutorial 1: Display-Only Grid 50
Defining the Window and Menu 50
Creating the Grid Control 51
Defining the Event Loop 55
Standard Grid Tutorial 2: User-Modifiable Grid 60
Data-Aware Grid Tutorial 63
Creating the Resource 63
Starting the Program in GUIBuilder 64
Making the Grid Data-Aware 65
GUIBUILDER 75
Introduction 75
GUIBuilder Features 75
GUIBuilder Glossary 75
GUI Design 75
The GUIBuilder Interface 76
Getting Started 77
Creating New GUIBuilder Files 77
Opening Existing GUIBuilder Files 78
Saving GUIBuilder Files 78
Printing GUIBuilder Files 78
Exiting GUIBuilder 78
Working with Blocks of Code: Defining Code Blocks 78
Defining Event Handler Code Blocks 78
Defining Initialization Code 80
Defining End of Job Code 80
Defining Subroutines/Functions 80
Working with Blocks of Code: Miscellaneous Features 81
Checking Code Blocks for Errors 81
Deleting Code Blocks 81
Getting External Code 81
Using an External Editor in GUIBuilder 82
ii
Pulling it all Together: The Completed Program 82
Checking Resources 82
Setting Program Options 83
Building Programs in GUIBuilder 83
Viewing GUIBuilder Programs 84
Running GUIBuilder Programs 84
Generated Program Variables 84
Preparing GUIBuilder Programs for End Users 85
Using Other Programs from the GUIBuilder Workbench 85
Invoking ResBuilder from GUIBuilder 85
Invoking DDBuilder from GUIBuilder 86
Invoking a Visual PRO/5 Console Window in GUIBuilder 86
Helper Functions 86
Functions for Reading and Updating the Screen 86
Functions for Setting Screen Focus 89
Functions for Retrieving Window Information 89
gb_func Code Library 90
fngb__get_code (gb_func) - Retrieve .gbf String Data or Chunks of Code 90
fngb__put_code - Insert Chunks of Code or Data into a .gbf String 91
fngb__del_code (gb_func) - Delete .gbf String Data or Chunk of Code 92
gb_func::gb__val_data - Validate a .gbf String 93
gb_func::gb__get_file - Get Text File into a .gbf String 93
gb_func::gb__build_program - Build and Tokenize Program using .gbf Data 94
fngb__get_event_desc$ (gb_func) - Get Event Description for a Given Event Code 98
fngb__get_event_label$ (gb_func) - Get Event Label for a Given Event Code 99
fngb__get_event_list$ (gb_func) - Get Event Codes for a Given Control Type 99
fngb__get_control_desc$ (gb_func) - Get Control Description for a Given Control Type 99
fngb__event_visible (gb_func) - Determine Event Visibility 99
gb_func::gb__make_gbf - Generate Framework .gbf String 99
gb_func::gb__get_block - Get Initial Code Block from gb_def.cod File 100
gb_func::gb__run_program - Run Generated Program 100
_qres Code Library 100
_qres::Enumerate_Sysgui_Forms - Get All Forms for a Given SYSGUI Channel 100
_qres::Enumerate_Sysgui_Child_Windows - Get All Child Windows for a Given Context 101
_qres::Enumerate_Sysgui_Controls - Get All Controls for a Given Context 101
_qres::Enumerate_Res_Forms - Get All Forms for a Given Resource 102
_qres::Enumerate_Res_Child_Windows - Get All Child Windows for a Given Top Level
Window 102
_qres::Enumerate_Res_Controls - Get All Controls for a Given Form 103
Conversions and File Formats 104
Character-GUI Conversions Using Batch Procedures 104
gb.ini File Parameters 104
.gbf File Format 106
Called Programs 108
gb_rec - Copy Fields Between Records 108
_label Utility - Convert Line Numbers to Line Labels 108
Mini-Tutorial 108
Creating a New .gbf File 109
Moving to ResBuilder 109
Opening a Resource File in ResBuilder 112
Resource File Properties 113
Returning to GUIBuilder 115
Object List 117
Control List 117
Event List 118
iii
Event Handler Code 119
Running the Program 121
Checking for Errors 122
GUI CONTROLS AND EVENTS 126
SYSGUI Device 126
GUI Controls 130
Button Controls 130
Check Box Controls 130
Child Windows 131
Custom Edit Controls 131
Edit Controls 132
Group Box Controls 133
Horizontal Scroll Bar Controls 133
Images 134
Graphical Edit (INPUTE) Controls 134
Numeric Edit (INPUTN) Controls 134
List Box Controls 135
List Button Controls 136
List Edit Controls 136
Menus 137
Radio Button Controls 140
Status Bar Controls 140
Tab Controls 141
Tool Button Controls 141
Vertical Scroll Bar Controls 142
SYSGUI Event Queue 143
SYSGUI Events 143
Activation Event 143
Push Button Event 144
Check/Uncheck Event 144
Close Box Event 144
Control Focus Gained/Lost Event 145
Edit Control Modify Event 145
Keypress Event 145
List Item Click Event 146
Menu Selection Event 147
Mouse Button Down Event 147
Mouse Button Up Event 148
Mouse Double-Click Event 148
Mouse Move Event 149
Notify Events 149
Scrollbar Move Event 151
System Color Change Event 151
Tool Button Push Event 152
Window Focus Gained/Lost Event 152
Window Resize Event 153
Grid Control Notify Events 153
Event Types 153
COLUMNSIZED Grid Notify Event 154
COLCHANGE Grid Notify Event 155
DCLICKED Grid Notify Event 155
DRAGDROP Grid Notify Event 156
EDITCHANGE Grid Notify Event 156
EDITKEY Grid Notify Event 157
iv
EDITKILL Grid Notify Event 157
EDITSET Grid Notify Event 158
ENTER Grid Notify Event 158
HITBOTTOM Grid Notify Event 159
HITTOP Grid Notify Event 159
KEYBOARD Grid Notify Event 160
KILLFOCUS Grid Notify Event 160
LCLICKED Grid Notify Event 160
LCLICKED2 Grid Notify Event 161
LEFTCOLCHANGE Grid Notify Event 162
MOUSECAPTURE Grid Notify Event 162
RCLICKED Grid Notify Event 163
ROWCHANGE Grid Notify Event 163
SETFOCUS Grid Notify Event 164
TOPROWCHANGE Grid Notify Event 164
TABLEUPDATE Grid Notify Event 165
ROWINSERT Grid Notify Event 165
ROWDELETE Grid Notify Event 165
ROWCANCEL Grid Notify Event 166
ROWUPDATE Grid Notify Event 166
EDITSTART Grid Notify Event 166
ERROR Grid Notify Event 167
Tab Control Notify Events 169
Keypress Notify Event 169
Tab Selection Notify Event 171
Tab Deselection Notify Event 171
RESBUILDER 173
Introduction 173
Using ResBuilder 173
The ResBuilder Interface 173
Getting Started 174
Starting ResBuilder 174
Creating New ResBuilder Files 174
Opening Existing .brc Resource Files 174
Saving Files 175
Exiting ResBuilder 176
Forms and Child Windows 176
Creating Forms and Child Windows 176
Using the Layout Grid 176
Sizing Forms and Child Windows 177
Aligning Child Windows 177
Defining Form and Child Window Properties 177
Defining the Status Bar 179
Attaching Child Windows to Forms 179
Setting Form and Child Window Display Options 181
Hiding and Redisplaying Forms and Child Windows 181
Deleting Forms and Child Windows 181
Controls 181
Creating Single Controls 181
Creating Multiple Controls 181
Sizing Controls 182
Moving Controls 182
Aligning Controls 182
Distributing Controls 182
v
Grouping and Ungrouping Controls 183
Defining Control Properties 183
Modifying the Tab Order of Controls 185
Deleting Controls 186
Menus 186
Creating a Menu Bar 186
Adding Menus to the Menu Bar 187
Adding Menu Items to Menus 187
Attaching Menus to Forms 187
Image Lists 188
Creating Image Lists 188
Defining Image Lists 188
Printing 188
ResBuilder Print Preview 188
Print Setup 188
Printing 188
RESCOMPILER 190
Introduction 190
Using ResCompiler 190
Resource File Contents and Structure 190
Defining Windows 194
Windows and Dialogs 194
Defining Menus 196
Menu Bars 196
Menus 199
Defining Child Windows 200
Directly-Defined Child Windows 200
Indirectly-Defined Child Windows 201
Example 201
Defining Controls 202
Mandatory Control Properties 202
Button Controls 202
Check Box Controls 203
Custom Edit Controls 204
Edit Controls 204
Grid Controls 205
Group Box Controls 206
Image Elements 207
INPUTE Controls 207
INPUTN Controls 208
Line Elements 209
List Box Controls 209
List Button Controls 210
List Edit Controls 211
Radio Button Controls 211
Scroll Bar Controls 213
Static Text Controls 213
Tab Controls 214
Tool Button Controls 216
Preprocessor Commands and Predefined Constants 216
Preprocessor Commands 216
Predefined Constants 217
Accelerator Key Constants 217
Character Set Constants 218
vi
Color Name Constants 219
Current Unit Constants 219
Event Mask Constants 219
Scroll Bar Orientation Constants 219
Text Justification Constants 220
Running ResCompiler 220
Command Line Guidelines 220
Command Line Options 220
Example 221
ResCompiler Error Messages 221
RESOURCE PROPERTY INDEX 223
Always Place Window on Top 223
Set Background Color 223
Sound Beep for Invalid Data Entry 223
Create Border Around Control 223
Create Child Window Without Border 223
Display Tabs as Buttons 223
Checkable Menu Item 223
Set Control to be Initially Checked 224
Draw Client Edge Around Control 224
Create Close Box 224
Use a Managed Grid Control as Column Heading 224
Set Initial Number of Columns 224
Copy Commas in Input 224
Set Current Units 225
Allow Custom Color Palette 225
Replace Decimal Characters 225
Set Default Font 225
Make Window Behave as Dialog 225
Create Border around Dialog 225
Set Control to be Initially Disabled 225
Dock to Parent Frame 226
Set Child Window Docking Position 226
Use <Enter> as <Tab> 226
Set Event Mask 226
Set Fixed Tab Widths 226
Prevent Focus 226
Receive Focus on Button Down 226
Set Control Font 227
Force Icons to Left Margin 227
Force Labels to Left Edge of Tabs 227
Set Foreground Color 227
Set Child Window Gravity 227
Group Controls Together 227
Set Non-mouse Events to Highlight Text 227
Draw Horizontal Grid Lines 228
Set Additional Horizontal Spacing Between Tabs 228
Include Horizontal Scroll Bar 228
Define Icon File 228
Ignore Tabs in Text Input 228
Define Image List 228
Set INPUTN Input Mask 229
Set Initial Contents 229
Set Initial Cursor Position 229
Set Scroll Bar Proportion 229
vii
Set Initial Thumb Size 229
Set Initial Tab 229
Set Space Between Grid Rows 229
Set Control to be Initially Invisible 230
Set Text Justification 230
Activate Keyboard Navigation 230
Maximum Number of Paragraphs 230
Set Status Bar (Longcue) Text 230
Automatically Manage SYSCOLOR Events 230
Set Control Margin 230
Set INPUTE Input Mask 231
Set Maximum Number of Columns 231
Allow Maximized Window 231
Set Window to be Initially Maximized 231
Maximum Input String Length 231
Include Menu Bar 231
Allow Minimized Window 231
Set Window to be Initially Minimized 232
Display all Tab Rows 232
Allow Multiple Selections 232
Set Window/Control Name 232
Prevent Automatic Management of Tab Item Display and Sizing 232
Do Not Include Title Bar 232
Prevent Text Wrapping 233
Set INPUTN Output Mask 233
Allow Only One Paragraph 233
Set Option String 233
Set Scroll Bar Orientation 233
Initially in Overstrike Mode 233
Set INPUTE Pad Character 233
Pass <Enter> to Parent Window 234
Pass <Home> and <Delete> as Keypress Notify Events 234
Pass <Tab> to Parent Window 234
Replace Input Text with Asterisks 234
Prevent Full Tab Justification 234
Draw Raised Edge Around Control 234
Set Text as Read-only 234
Set Restore String 235
Set INPUTN to Behave as INPUTE if First Character is Non-numeric 235
Set Full Tab Justification 235
Enter Data from Right Side 235
Use a Managed Grid Control as Row Heading 235
Set Initial Number of Grid Rows 235
Insert Separation Line After Menu Item 235
Share Image Lists with Other Tab Controls 236
Set Tool Tip (Shortcue) Text 236
Allow Window Resizing 236
Set Status Bar Definition 236
Set Tab Height 236
Display Tabs as Tabs/Draw Border Around Display 236
Set Tab Width 237
Place Text to Left of Check Box or Radio Button 237
Set Title 237
Create Toggle On/Off Button 237
Create Window as Tool Window 237
Allow Column Resizing 237
viii
Set Additional Vertical Tab Spacing 237
Draw Vertical Lines Between Columns 238
Include Vertical Scroll Bar 238
Wrap Text to Next Line 238
SENDMSG() FUNCTIONS 239
Grid Control SENDMSG() Functions 239
GRID SENDMSG() Functions Listed by Functional Grouping 239
Get Grid Information Block - GRID SENDMSG() Function 20 241
Set Multiple Cells - GRID SENDMSG() Function 21 242
Set Single Cell - GRID SENDMSG() Function 22 243
Set Heading Titles - GRID SENDMSG() Function 23 243
Set Best Fit - GRID SENDMSG() Function 24 244
Drag Start - GRID SENDMSG() Function 25 245
End Edit - GRID SENDMSG() Function 26 246
Set Extended Text Options - GRID SENDMSG() Function 27 246
Set Heading Spacing - GRID SENDMSG() Function 28 246
Fit Columns to Window - GRID SENDMSG() Function 29 247
Set Up Grid - GRID SENDMSG() Function 30 247
Start Edit - GRID SENDMSG() Function 31 248
Deselect All Cells - GRID SENDMSG() Function 32 250
Set Drag Accept - GRID SENDMSG() Function 33 251
Get Edit Text - GRID SENDMSG() Function 34 251
Set Edit Text - GRID SENDMSG() Function 35 251
Set Column Width - GRID SENDMSG() Function 36 252
Get Average Character Width - GRID SENDMSG() Function 37 252
Get Column Width - GRID SENDMSG() Function 38 252
Get Font - GRID SENDMSG() Function 39 253
Get Number of Columns - GRID SENDMSG() Function 40 253
Get Number of Rows - GRID SENDMSG() Function 41 253
Get Row Height - GRID SENDMSG() Function 42 254
Get Number of Visible Rows - GRID SENDMSG() Function 43 254
Get Selected Column - GRID SENDMSG() Function 44 254
Get Selected Row - GRID SENDMSG() Function 45 255
Get Top Row - GRID SENDMSG() Function 46 255
Goto Column - GRID SENDMSG() Function 47 255
Goto Row - GRID SENDMSG() Function 48 256
Set Cell/Row Highlight - GRID SENDMSG() Function 49 256
Redraw Row - GRID SENDMSG() Function 50 256
Set Heading Shadow Height - GRID SENDMSG() Function 51 257
Set Heading Dark Shadow Color - GRID SENDMSG() Function 52 257
Set Heading Light Shadow Color - GRID SENDMSG() Function 53 258
Draw Cell - GRID SENDMSG() Function 54 258
Set Default Background Color - GRID SENDMSG() Function 55 260
Set Default Text Color - GRID SENDMSG() Function 56 261
Set Highlight Method - GRID SENDMSG() Function 57 262
Set Horizontal Lines - GRID SENDMSG() Function 58 262
Set Horizontal Scroll Mode - GRID SENDMSG() Function 59 262
Set Interspace - GRID SENDMSG() Function 60 263
Set Line Color - GRID SENDMSG() Function 61 263
Set Margin - GRID SENDMSG() Function 62 263
Set Margin Mode - GRID SENDMSG() Function 63 264
Set Mouse Capture Mode - GRID SENDMSG() Function 64 264
Set Mouse Scrolling Mode - GRID SENDMSG() Function 65 265
Set Number of Columns - GRID SENDMSG() Function 66 265
Set Number of Rows - GRID SENDMSG() Function 67 266
ix
Set Row Height - GRID SENDMSG() Function 68 266
Set Thumb Update Mode - GRID SENDMSG() Function 69 267
Set Top Row - GRID SENDMSG() Function 70 267
Set Vertical Scroll Mode - GRID SENDMSG() Function 71 268
Set Vertical Lines - GRID SENDMSG() Function 72 268
Get String Width - GRID SENDMSG() Function 73 268
Set User Resize - GRID SENDMSG() Function 74 269
Set Image List ID - GRID SENDMSG() Function 75 269
Redraw Grid - GRID SENDMSG() Function 76 269
Set Current Heading Mode - GRID SENDMSG() Function 77 270
Set Cursor - GRID SENDMSG() Function 78 270
Set Edit Mask - GRID SENDMSG() Function 79 270
Set Channel and Template - GRID SENDMSG() Function 80 271
Perform Data-Aware Function - GRID SENDMSG() Function 81 274
Set Continue Message - GRID SENDMSG() Function 82 274
Set Default Style - GRID SENDMSG() Function 83 275
Set Default Alignment - GRID SENDMSG() Function 84 276
Seek Last Record - GRID SENDMSG() Function 85 276
Set Last Record Dialog - GRID SENDMSG() Function 86 277
Set Multiple Rows - GRID SENDMSG() Function 87 277
Status Bar SENDMSG() Functions 278
Set Text - Status Bar SENDMSG() Function 20 278
Get Text - Status Bar SENDMSG() Function 21 278
Get Text Length - Status Bar SENDMSG() Function 22 279
Get Rectangle - Status Bar SENDMSG() Function 23 279
Get Borders - Status Bar SENDMSG() Function 24 279
Set Minimum Height - Status Bar SENDMSG() Function 25 280
Get Parts - Status Bar SENDMSG() Function 26 280
Set Parts - Status Bar SENDMSG() Function 27 281
INPUTE SENDMSG() Functions 281
Get Title - INPUTE SENDMSG() Function 20 281
Set Title - INPUTE SENDMSG() Function 21 281
Get Mask - INPUTE SENDMSG() Function 22 282
Set Mask - INPUTE SENDMSG() Function 23 282
Get Position - INPUTE SENDMSG() Function 24 282
Set Position - INPUTE SENDMSG() Function 25 283
Get Pad Character - INPUTE SENDMSG() Function 26 283
Set Pad Character - INPUTE SENDMSG() Function 27 283
Get Restore String - INPUTE SENDMSG() Function 28 284
Set Restore String - INPUTE SENDMSG() Function 29 284
Set Left Margin - INPUTE SENDMSG() Function 30 284
Set Text Color - INPUTE SENDMSG() Function 31 285
Set Background Color - INPUTE SENDMSG() Function 32 285
Set !EDIT Value - INPUTE SENDMSG() Function 33 285
Set Length - INPUTE SENDMSG() Function 34 286
Get Error - INPUTE SENDMSG() Function 35 286
Set Insert Mode - INPUTE SENDMSG() Function 36 286
Set !CTYPE Value - INPUTE SENDMSG() Function 37 287
INPUTN SENDMSG() Functions 287
Get Title - INPUTN SENDMSG() Function 20 287
Set Title - INPUTN SENDMSG() Function 21 287
Get OMask - INPUTN SENDMSG() Function 22 288
Set Output Mask - INPUTN SENDMSG() Function 23 288
Get Position - INPUTN SENDMSG() Function 24 288
Get Error - INPUTN SENDMSG() Function 25 289
Get Restore String - INPUTN SENDMSG() Function 26 289
x
Set Left Margin - INPUTN SENDMSG() Function 27 289
Set Text Color - INPUTN SENDMSG() Function 28 289
Set Background Color - INPUTN SENDMSG() Function 29 290
Set Position - INPUTN SENDMSG() Function 30 290
Set Restore String - INPUTN SENDMSG() Function 31 290
Set !EDIT Value - INPUTN SENDMSG() Function 32 291
Set Insert Mode - INPUTN SENDMSG() Function 33 291
TABCTRL SENDMSG() Functions 291
SENDMSG() Syntax Legend 291
Get/Set Display Rectangle - TABCTRL SENDMSG() Function 20 292
Get Bounding Rectangle - TABCTRL SENDMSG() Function 21 293
Get Number of Tab Rows - TABCTRL SENDMSG() Function 22 293
Set Tab Width and Height - TABCTRL SENDMSG() Function 23 293
Set Tab Icon/Label Padding - TABCTRL SENDMSG() Function 24 294
Remove All Tabs - TABCTRL SENDMSG() Function 25 294
Remove a Tab - TABCTRL SENDMSG() Function 26 294
Get Tab Information - TABCTRL SENDMSG() Function 27 295
Get Tab Index - TABCTRL SENDMSG() Function 29 295
Get Tab Image List ID - TABCTRL SENDMSG() Function 30 295
Get Tab Count - TABCTRL SENDMSG() Function 31 296
Perform Point Hit Test - TABCTRL SENDMSG() Function 32 296
Insert Tab - TABCTRL SENDMSG() Function 33 296
Select Tab - TABCTRL SENDMSG() Function 34 297
Set Tab Image List ID - TABCTRL SENDMSG() Function 35 297
Set Tab Attributes - TABCTRL SENDMSG() Function 36 297
Ignore/Process Selection Change Notice - TABCTRL SENDMSG() Function 37 298
Get Current Tab - TABCTRL SENDMSG() Function 38 298
Set Tab Index Focus - TABCTRL SENDMSG() 39 298
xi
CONFIGURATOR
Introduction
Configurator is a utility that allows you to visually create and edit a Visual PRO/5 configuration file, which is an ASCII text file that
contains parameters that govern the behavior of Visual PRO/5.
Using Configurator simplifies the editing process by allowing interactive selection of configuration parameters and eliminates the
need for you to remember the specific syntax of parameter settings.
Configurator operates under Windows 95 and 98, and Windows NT 3.51 and 4.0.
The Configurator Interface

The following illustrates the Configurator interface.
Getting Started
Creating New Configuration Files

To create a new configuration file do one of the following:
• On the File menu, select New.
• On the toolbar, click the New button.
• Press <Ctrl>+ N.
Opening Existing Configuration Files

To open an existing configuration file, do the following:
1 Do one of the following to display the VPRO/5 Configuration File dialog, which allows you to select the file:
• On the toolbar, click the Open button.
1
• Press <Ctrl>+ O.
2 Move to the directory that contains the file, select it, and click Open.
Saving Configuration Files

To save a configuration file, do one of the following:
• On the File menu, select Save.
• On the toolbar, click the Sa ve button.
• Press <Ctrl>+ S.
To save a file under a new name and/or path, do the following:
1 On the File menu, select Save As.
2 Move to the directory that will contain the file, enter the filename and click Save. The new file becomes the current file.
Printing Configuration Files

To print the current configuration file, do the following:
1 On the File menu, select Print Setup to display the standard Windows Print Setup dialog that contains printer properties,
paper size and source, and print orientation settings.
2 Do one of the following to display the standard Print dialog:
• On the File menu, select Print.
• On the toolbar, click the Print button.
• Press <Ctrl>+P.
3 Select the number of pages and click Print.
Exiting Configurator
To exit Configurator, on the File menu, select Exit. If you are working on a file and have modified it since the last time you saved
it, Configurator will prompt you to save or discard the changes before exiting.
Setting Configuration File Options
Setting DSKSYN, SYSGUI, and Limits Configuration Options

The DSKSYNs/Limits configuration page provides settings for DSKSYN, SYSGUI, and Limits configuration parameters.
DSKSYN (Disable)
The DSKSYN group is used to disable logical disk drives and remove them from the list of drives searched by Visual PRO/5.
• To disable a drive, click the check box to the left of the drive letter to insert a check mark.
• To enable a drive, click the check box to clear the check mark.
SYSGUI
In the SYSGUI group, define a graphical device name by selecting the SYSGUI device name (available values are X0 through
X9). To enable SYSGUI channels to remain open through the execution of the BEGIN verb, click the Persist thru BEGIN check
box.
Limits
The Limits group box contains the following six configuration values: DEVS, FCBS, CIBS, STBLEN, HANDLES, and FCBCACHE.
To change the values of any of these limits, click the row and type in the new value. FCBCACHE is a check box that can be
clicked on and off.
Limit name Description and Range Visual PRO/5 Default
DEVS Number of terminals and/or printers that can be accessed simultaneously by Visual 4
PRO/5.
2
FCBS Number of disk files that can be accessed simultaneously by Visual PRO/5. 10
CIBS Number of I/O channels that can be accessed simultaneously by Visual PRO/5. (This 16
is not the total for the system.) Visual PRO/5 associates an I/O channel with either a
file or device. There is not necessarily a one-to-one relationship between CIBS and
DEVS or between CIBS and FCBS. For example, 2 channels opened to 2 different
devices will require 2 CIBS and 2 DEVS; but 2 channels opened to the same device
will require 2 CIBS but only 1 DEV.
STBLEN Size (in bytes) of an internal list of ALIAS names and disk names. The Configurator 1024
will update the STBLEN value based on the size of the configuration file.
HANDLES Maximum number of file handles to be used by each invocation of Visual PRO/5. OS Limit
(This is not the total for the system.) Entering a large number causes Visual PRO/5
to retain a large number of open files (if FCBCACHE is enabled), or allows the user
to open a large number of files (if FCBCACHE is disabled).
FCBCACHE Directs Visual PRO/5 to maintain at the system level all files opened and closed by Off
the user during the current session. Files maintained at the system level can be
reopened very quickly.
Setting PREFIX and Global String Options

The Prefix/Globals configuration page provides a form for entering both PREFIX paths and global string assignments.
PREFIX
The PREFIX is a list of directories and is used by Visual PRO/5 to initialize the file search sequence.
The total prefix length cannot exceed 1024 bytes. When a new directory is added, it is placed at the
end of the prefix list. To add a directory to the PREFIX list, do the following:
1 Click Add.
2 Type in the directory. Use forward slashes (/) only and include the disk designator. Do not include embedded spaces in the
path, and be sure to include a trailing forward slash.
To remove a directory from the PREFIX list, do the following:
1 Select the directory to remove.
2 Click Remove.
GLOBAL
The Global strings group is used for setting global string values in the Visual PRO/5 configuration file.
To add a global string value, do the following:
1 Click Add.
2 Type in the global string name in the first column of the grid.
3 Type in the global string value in the second column of the grid.
To remove a global string value, do the following:
1 Select the global string to remove.
2 Click Remove.
Setting SYSWINDOW Options

The SYSWINDOW configuration page provides for creating and removing SYSWINDOW definitions.
• To add a new SYSWINDOW device, click Add.
• To remove an existing SYSWINDOW device, click anywhere in the column, then click Remove.
Row Description
Alias name Enter an alias name for the device. The alias must start with “T” and contain between 2 to 6
characters.
Description Enter a text description of the device. Do not use quotation marks.
3
Clipboard Enter a clipboard flag for the device. Setting the clipboard flag causes the SYSWINDOW device to
enable Cut (Ctrl+X), Copy (Ctrl+C), and Paste (Ctrl+V) functionality.
Columns Enter the number of columns for the device. Default number of columns is 80. Windows will not allow
any Visual PRO/5 terminal window to be larger than the display screen. The maximum is 255.
Conditional expr Enter a conditional expression for the device. It should be in the format T? and will cause this
SYSWINDOW device to be valid during a Visual PRO/5 session only if FID(0) = T?.
Font name Enter a font name for the device. The default font is Courier New. Valid choices are any fixed pitch
font installed on your system.
Font size Enter a font size (in points) for the device. The default is 10 points. Valid choices are any point size
supported by the font specified in Font Name.
Invert Enter the invert flag for the device, which causes the Invert light/dark check box in the Print menu to
be initially checked. The invert flag causes print screen output generated from this SYSWINDOW
device to be black with white text. If the flag is not set and you do a print screen from SYSWINDOW
console mode, the output will be black with white text.
Invisible If checked, the SYSWINDOW device will be initially invisible.
Lock file Enter the name of the lock file (if any) to be created when the device is activated.
Lock mode Select the lock mode settings from the following:
• No lock mode – Lock mode options are not available.
• Normal - Locks the screen to set the number of columns and rows (default).
• Varyfonts - Causes Visual PRO/5 to resize the font to enable all data to appear on the screen.
• Scrollbars - Causes Visual PRO/5 to use scroll bars to enable the user to view all data.
Initial state Select the initial window display settings from the following:
• Default state – Initially displays the window according to the default x, y, width, and height
settings.
• Maximized - Initially displays the window as maximized.
• Minimized - Initially displays the window as minimized.
Menu Checking the box causes the menu for the clipboard operations and the screen print to be added to
this SYSWINDOW device.
Persist through Checking the box prevents the close of an opened SYSWINDOW when a BEGIN is encountered in a
BEGIN program.
Rows Set the number of rows for the device. The default is 25, and the maximum is 255.
Title Enter the window title. The default is Visual PRO/5.
X position Enter the X position in pixels from the left of the client area. The default is 100 pixels.
Y position Enter the Y position in pixels from the top of the client area. The default is 100 pixels.
Setting SYSPRINTER Options

The Sysprinter configuration page is used to define print devices that are accessible through the Windows Print Manager. To
print directly to a printer port, use the Printers configuration page.
Row Description
Alias name Enter an alias name for the printer. The alias name must begin with an L or a P in order for Visual
PRO/5 to recognize the device as a printer. The minimum length of the alias name is 2 characters.
Description Enter the description for the printer. This text is not used by Visual PRO/5 but may be accessed by
an application program via the TSK() function.
Columns Enter the number of columns for the printer.
Conditional expr Enter a conditional expression for the printer in the form T?. It allows this device to be accessible
only by Visual PRO/5 processes with a FID(0)=T?.
CP columns Enter the number of columns that the printer can print when in compressed print mode. The
maximum is 255.
CP lines Enter the number of lines per page that the printer can print when in compressed print mode.
4
Dialog/Setup Click the Options button to display the dialog for defining the Dialog/Setup options.
• No initial dialog – Accesses the default printer (as selected from Control Panel) when this
printer is selected.
• Dialog - Displays the Windows Print dialog when this printer is selected. Execution of the Visual
PRO/5 program is paused until a printer and page setup are selected and confirmed.
• Setup - Displays the Windows Print Setup dialog when this printer is selected. Execution of the
Visual PRO/5 program is paused until a printer and page setup are selected and confirmed.
End of line Click the Options button to display the dialog for defining the end of line settings and select one of
the following:
• Default EOL Handling - An attempt to print a line that is longer than the defined width of the
printer will generate an ERROR=1 at runtime. To recover from this error, you must reset the print
buffer by issuing the command: PRINT (prtr)"".
• Error - Similar to the EOL handling behavior, but there is no need to reset the print buffer to
recover from this error. The next line printed after receiving the ERROR=1 will overprint the line
that caused the error.
• Wrap - Causes the text to wrap to the next line.
• Truncate - Causes the text to be truncated at the defined width of the printer.
Font name Enter the font name for the printer. If no font is selected, then Visual PRO/5 will use the best
available device font based on the desired ROW and COLUMN selection.
Job ID Enter the job ID name for the print jobs in the Print Manager’s queue. The default is “Visual PRO/5
Document.”
Lock file Enter the name of the lock file to be created whenever this printer device is opened by Visual
PRO/5. This file prevents more than one process from opening the device.
Persist through Checking the box sets the persist flag for the printer, which causes the device to remain open on a
begin BEGIN.
Preview Checking the box sets the preview flag for the printer, which causes the device to be opened as a
preview to the screen.
Rows Enter the number of rows for the printer.
SP columns Enter the number of columns that the printer can print when in standard print mode. The maximum is
255.
SP lines Enter the number of lines per page that the printer can print when in standard print mode. The
maximum is 255.
Setting Printer Options

The Printers configuration page is used to define Visual PRO/5 printers that bypass the Windows Print Manager and print directly
to a printer port. To define Visual PRO/5 printers that use the Windows Print Manager, use the Sysprinters configuration page.
• To add a new printer device, click Add.
• To remove an existing printer device, click anywhere in the column, then click Remove.
Row Description
PRO/5 to recognize the device as a printer. The minimum length of the alias name is 2 characters
and the maximum length is 6.
Device Enter the device name for the printer. This refers to the operating system device (for example:
/dev/lpt1, or /dev/com1) to be used for this printer.
Description Enter a description for the printer. This text is not used by Visual PRO/5 but may be accessed by
an application program via the TSK() function.
Backspace Click the Options button to display the dialog for defining the backspace character(s).
• If the printer does not support any backspace character, click the drop down arrow and select
NO BS.
• If the printer supports the ASCII backspace character ($08$), click the drop down arrow and
select ASCII BS.
5
• To define a string sequence to send to the printer whenever a backspace character is sent by
Visual PRO/5, click the drop down arrow and select BS=. Select ASCII, Decimal, or Hex to
display the desired characters. You can either select the desired characters by clicking them in
the grid, or by entering them into the BS= box.
• When you have finished selecting all desired characters, click OK.
Conditional expr Enter a conditional expression for the printer in the form T?. This allows the device to be accessible
Number of copies If the printer supports a specification of the number of copies to be printed, define the default
number of copies. This value may be overridden within an application by using the MODE= option
on the OPEN of the printer.
Compressed Print Click the Options button to display the dialog for defining the compressed print settings.
• If the printer does not support compressed print, click the drop down arrow and select NO CP.
• To define a string sequence to send to the printer whenever a ‘CP’ mnemonic is sent by Visual
PRO/5, click the drop down arrow and select CP=. Select ASCII, Decimal, or Hex to display the
desired characters. You can either select the desired characters by clicking them in the grid, or
by entering them into the CP= box.
When you have finished selecting all desired characters, click OK.
CP columns Enter the number of columns the printer can print when in compressed print mode. The maximum
is 255.
CP lines Enter the number of lines that the printer can print when in compressed print mode. The maximum
is 255.
Carriage return Click the Options button to display the dialog for defining the carriage return settings.
• If the printer does not support carriage return, click the drop down arrow and select NO CR.
• If the printer supports the ASCII carriage return character ($0D$), click the drop down arrow and
select ASCII CR.
• To define a string sequence to send to the printer whenever a carriage return is sent by Visual
PRO/5, click the drop down arrow and select CR=. Select ASCII, Decimal, or Hex to display the
by entering them into the CR= box.
the following:
printer will generate an ERROR=1 at runtime. To recover from this error, you must reset the
print buffer by issuing the command: PRINT (prtr)"".
that caused the error
Expanded Print on Click the Options button to display the dialog for defining the expanded print settings, as follows:
• If the printer does not support expanded print, click the drop down arrow and select NO EPON.
• To define a string sequence to send to the printer whenever an ‘EP’ mnemonic is sent by Visual
PRO/5, click the drop down arrow and select EPON=. Select ASCII, Decimal, or Hex to display
the desired characters. You can either select the desired characters by clicking them in the grid,
or by entering them into the EPON= box.
Expanded Print off Click the Options button to display the dialog for defining the expanded print settings, as follows:
• If the printer does not require special code to turn expanded print off, click the drop down arrow
and select NO EPOFF.
• To define a string sequence to send to the printer when it is in ‘EP’ mode and a new mnemonic
6
(‘SP’, ‘CP’) has been sent by Visual PRO/5, click the drop down arrow and select EPOFF=.
Select ASCII, Decimal, or Hex to display the desired characters. You can either select the
desired characters by clicking them in the grid, or by entering them into the EPOFF= box.
EP columns Enter the number of columns that an expanded print character will consume. For example, if EP
columns is 2, then each character printed in expanded print will count as two characters.
EP lines Enter the number of lines that an expanded print character will consume. For example, if EP lines
is 2, then each line of expanded print will count as two lines.
Execute on OPEN Enter a command to be executed on the first output command to the device. For example, this
command might be used to execute an operating system command to load fonts on a device.
Execute on CLOSE Enter a command to be executed at the close of the device. For example, this command might be
used to execute an operating system command to return the device to some known state.
Formfeed Click the Options button to display the dialog for defining the formfeed settings, as follows:
• If the printer does not support formfeed, click the drop down arrow and select NO FF.
• If the printer supports the ASCII form feed character ($0C$), click the drop down arrow and
select ASCII FF.
• To define a string sequence to send to the printer whenever a formfeed is sent by Visual PRO/5,
click the drop down arrow and select FF=. Select ASCII, Decimal, or Hex to display the desired
characters. You can either select the desired characters by clicking them in the grid, or by
entering them into the FF= box.
Form number If the printer supports a specification of the form number to be used in printing, define the default
number here. This value may be overridden within an application by using the MODE= option on
the OPEN of the printer.
Linefeed Click the Options button to display the dialog for defining the linefeed settings.
• If the printer does not support linefeeds, click the drop down arrow and select NO LF.
• If the printer supports the ASCII linefeed character ($0A$), click the drop down arrow and select
ASCII LF.
• To define a string sequence to send to the printer whenever a ‘LF’ mnemonic is sent by Visual
PRO/5, click the drop down arrow and select LF=. Select ASCII, Decimal, or Hex to display the
by entering them into the LF= box.
Lock file Enter the name of the lock file you want created whenever this printer device is opened by Visual
PRO/5. This prevents more than one process from opening the device.
Print on OPEN Click the Options button to display the dialog for defining the string sequence sent to the printer
upon its first OPEN.
• If it is not necessary to send any initializing character string to the printer upon its first OPEN,
click the drop down arrow and select NO PTON.
• To define a string sequence to send to the printer upon its first OPEN, click the drop down arrow
and select PTON=. (However, no data is actually sent to the printer until the first PRINT
statement, upon which the Print on OPEN string is sent, followed by the ‘SP’ mnemonic.) Select
ASCII, Decimal, or Hex to display the desired characters. You can either select the desired
characters by clicking them in the grid, or by entering them into the PTON= box.
Print on CLOSE Click the Options button to display the dialog for defining the string sequence sent to the printer
upon its CLOSE.
• If it is not necessary to send any initializing character string to the printer upon its CLOSE, click
the drop down arrow and select NO PTOFF.
• To define a string sequence to send to the printer upon its CLOSE, click the drop down arrow
and select PTOFF=. Select ASCII, Decimal, or Hex to display the desired characters. You can
either select the desired characters by clicking them in the grid, or by entering them into the
PTOFF= box.
7
Standard Print Click the Options button to display the dialog box for defining the string sequence to send to the
printer before the first PRINT statement, and whenever a 'SP' mnemonic is detected.
• To disable sending any string sequence to the printer before the first PRINT statement and
anytime the ‘SP’ mnemonic is sent by Visual PRO/5, click the drop down arrow and select NO
SP.
• To define a string sequence to send to the printer at the first PRINT statement, and whenever a
‘SP’ mnemonic is sent by Visual PRO/5, click the drop down arrow and select SP=. Select
characters by clicking them in the grid, or by entering them into the SP= box.
SP columns Enter the number of columns that the printer can print when in standard print mode. The maximum
is 255.
maximum is 255.
Wait on timeout Specify the number of seconds for Visual PRO/5 to wait before reporting printer timeouts. The valid
range is 0 to 255. Setting the value to 0 disables printer timeouts. The default timeout is 10
seconds.
Setting Plotter Properties

The Plotters configuration page is used to define Visual PRO/5 plotters.
• To add a new plotter device, click Add.
• To remove an existing plotter device, click anywhere in the column, then click Remove.
Row Description
Alias name Enter an alias name for the plotter. The name must begin with “D” and contain between 2 and 6
characters.
Device Enter the operating system name of the device, such as /dev/lpt1, /dev/com1, or sysplot.
Description Enter a description for the plotter. This text is not used by Visual PRO/5 but may be accessed by an
application program via the TSK() function.
Type If the plotter is a direct device (/dev/lpt1, or /dev/com1), enter the entry in the termcap file you wish to
reference for this plotter. Visual PRO/5 supplies its own termcap file that you may want to use.
Aspect ratio Enter the aspect ratio for the plotter. The aspect ratio allows square plotting on a non-square surface.
• To apply a specified aspect ratio to the device, and shrink the longer of the two axes until the
longer axis is fully on the screen, enter an aspect ratio less than 0.
• To apply the default aspect ratio, enter an aspect ratio of 0.
• To prevent any attempt by Visual PRO/5 to correct for non-square plotting surfaces, enter an
aspect ratio of 1.
• To apply the specified aspect ratio to the device, stretching the shorter of the two axes ‘off’ the
screen, enter an aspect ratio greater than 0.
Conditional expr Enter a conditional expression for the printer in the form T?, which allows this device to be accessible
Font name Enter the font name for the plotter. Valid fonts are:
• simplex.sft
• triplex.sft
• symbols.sft
• script.sft
• olde.sft
Window height Enter the window height in pixels for the plotter. (Valid only for SYSPLOT device.)
Lock file Enter a name for the plotter lock file that will be created whenever this plotter device is opened by
8
Visual PRO/5, which prevents other processes from opening the device.
Window X position Enter the X position in pixels from the left of the client area. The default is 100 pixels. (Valid only for
SYSPLOT device.)
Window Y position Enter the Y position in pixels from the top of the client area. The default is 100 pixels. (Valid only for
SYSPLOT device.)
Window width Enter the window width in pixels for the plotter. (Valid only for SYSPLOT device.)
Setting TCP Socket Options

The TCP Sockets configuration page provides for creating and removing TCP socket definitions.
• To add a new TCP socket, click Add.
• To remove an existing TCP socket, click anywhere in the column, then click Remove.
Row Description
Alias name Enter an alias name for the socket. The alias must start with “N” and contain tcp
Description Enter a text description of the socket. Do not use quotation marks.
Conditional expr Enter a conditional expression for the socket. It should be in the format T? and will cause it to be
valid during a Visual PRO/5 session only if FID(0) = T?.
Do not route Checking the box causes the socket to bypass standard routing.
Host Enter the name of the host.
Keep alive Checking the box enables the periodic transmission of messages.
Linger on CLOSE Checking the box causes the close to be blocked until all data has been sent.
No Delay Checking the box prevents the wait for a full send buffer before sending.
Port Enter the number of the port. If Host is specified, enter the host to connect to. . If Host is not
specified, enter the number of the port upon which to start the server
Setting UDP Socket Options

The UDP Sockets configuration page provides for creating and removing UDP socket definitions.
• To add a new UDP socket, click Add.
• To remove an existing UDP socket, click anywhere in the column, then click Remove.
Row Description
Alias name Enter an alias name for the socket. The alias must start with “N” and contain udp
Description Enter a text description of the socket. Do not use quotation marks.
Broadcast messages Checking the box enables the transmission of broadcast messages.
Conditional expr Enter a conditional expression for the socket. It should be in the format T? and will cause it to be
valid during a Visual PRO/5 session only if FID(0) = T?.
Do not route Checking the box causes the socket to bypass standard routing.
Host Enter the name of the host.
Port Enter the number of the port. If Host is specified, enter the host to send packets to. . If Host is not
specified, enter the number of the port to listen to.
Reuse local addrs Checking the box allows the reuse of local addresses.
Setting SETOPTS Options

The SETOPTS tab allows you to define the values to be stored in the SETOPTS line in the configuration file. These values affect
several behaviors of PRO/5. For more information, refer to the documentation for the SETOPTS verb in the Commands Manual
Description Byte,Bit/Entry
Issue an error on uninitialized variables 1,$80$
Turn off all error traps 1,$40$
9
Place EDIT window in insert mode 1,$20$
Disable pause for LIST and DUMP 1,$10$
Enable console mode in public programs 1,$08$
List variable names in lower case 1,$02$
List commands and keywords in lower case 1,$01$
Use non-destructive cursor advance for @(X) 2,$80$
Output an LF on a PRINT with no IOLIST 2,$40$
Round intermediate results of math functions 2,$20$
Strip spaces from NUM() string argument 2,$10$
Ignore mask overflows in PRINT, WRITE, STR() 2,$08$
Issue error on WRITE without KEY= 2,$04$
Don’t use math coprocessor 2,$02$
Update the length of a dynamic file after any growth 2,$01$
Allow program loading from the public workspace 3,$80$
Disable hash check on the loading of a program 3,$08$
Disable access to files with non-zero access count 3,$04$
Allow replacing mask characters in PRINT, CVS() 3,$02$
Scan diskless PREFIX entries with the current disk only 4,$80$
Use a floating lockbyte for access of files across a network 4,$40$
Allow access to the PRO/5 Data Server 4,$20$
Force templates and keys to use 14 digit precision 4,$08$
Replace trailing mask # characters with zeros in STR() 4,$04$
Adjust the number of leading spaces for EP lines 4,$02$
Place leading zero on numeric output before decimal 4,$01$
Replacement character of numeric mask character “,” 5,All
Replacement character of numeric mask character “.” 6,All
Allow a SYSGUI channel to persist through a BEGIN 7,$02$
Enable FCB reuse 7,$01$
Use advisory locking 3,$40$
Allow multiple reads and block writes on file keys 3,$20$
Operating system supports only advisory locking 3,$10$
Setting SQL Options

The Edit SQL configuration page is used to enable SQL, define the path to the SQL.INI file, edit and print the SQL.INI file, and
enter Data Source properties.
To enable the Visual PRO/5 SQL engine, click the Enable SQL check box. SQL must be enabled before you can access the other
controls on this configuration page.
Defining the SQL.INI file path

• To enter the location of the SQL.INI file, click the Path field and specify the location. If the path is not specified, PRO/5
assumes that the sql.ini file is located in the current directory.
• To open the SQL.INI file for viewing, click Open. A standard Windows file open dialog will be presented for selecting the
SQL.INI file to open.
• To print the current SQL.INI file, click Print. A standard Windows print dialog box will be presented.
10
• To preview the current SQL.INI file, click Print Preview. A standard Windows print preview dialog box will be presented.
• To save edits to the current SQL.INI file, click Save.
Defining the Data Source Name and Configuration File

To add BASIS data sources to the SQL.INI file, use the Data Source group. BASIS data sources are databases that have been
defined in the BASIS Data Dictionary. Each BASIS data source must have an associated config.TPM file. The Data Source group
will be disabled until an SQL.INI value has been filled in.
The Data Source group box contains a two column dynamic grid control for entering data source properties.
• To Add a data source, click Add.
• To Remove a data source, click the row that contains the data source name, then click Remove.
• To edit an existing data source, click on the row that contains the data source name.
• To set the data source name, click in the column Data Source Name column and enter the name.
• To set the location of the data source configuration file, do the following:
1 Click in the Configuration file column.
2 Enter the location of the configuration file that contains parameters for this data source.
3 The configuration file for each data source indicates where the physical dictionary and the logical data for that data
source exist. Lines that begin with a “#” are comments. Ensure that the DICTIONARY value points to the physical
location of the BASIS Data Dictionary. Often, to resolve the location of the file paths defined in the dictionary, it is
necessary to establish a global path to that data. If this is the case, then you should also define all the globals in your
dictionary configuration file that are required to resolve the physical path to your data. This is typically the DATA value.
• To search system for a configuration file, click Browse to display a standard open dialog box.
• If modifications have been made to the Data Source group box and the user changes focus from the configuration page without
having pressed the Save button, a confirmation message will be presented to save changes.
Setting Novell-Specific Options

The Novell configuration page provides a form for setting Novell-specific options and defining Novell NSPOOL devices.
Enabling Transaction Tracking

The Novell NetWare operating system provides a transaction tracking function to guarantee that either all or none of the pieces of
a single transaction will be written to the disk. If the server should go down part way through a transaction, all updates are backed
out until the database is restored to its state prior to the start of the transaction.
The Novell version of Visual PRO/5 can take advantage of this service to ensure that all of the information pertaining to a given
record, included both its content and its index entry, are updated on the disk in lock step. In order to provide this protection for a
Visual PRO/5 file, the user must enable NOVELL_TTS.
• To enable NOVELL_TTS, click the Transaction Tracking check box.
Enabling Locks
The record locking functions provided by MS-DOS permit only one user access to a record at a time, whether reading or writing.
Novell NetWare provides different levels of locks so Visual PRO/5 can allow many users to read a record simultaneously while still
limiting updates to one at a time. A record can even be read that is currently extracted by the same user on a different channel.
Visual PRO/5 uses the configuration flag NOVELL_LOCKS to implement this functionality.
• To enable NOVELL_LOCKS, click the Locks check box.
Creating NSPOOL Devices

Row Description
PRO/5 to recognize the device as a printer. The minimum length of the alias name is 2 characters
and the maximum length is 6.
Description Enter a description for the printer. This text is not used by Visual PRO/5 but may be accessed by an
application program via the TSK() function.
Banner To cause Novell to print a banner before print jobs, check this box.
11
Banner text To replace the default banner text of LST:, enter new banner text.
Banner name To replace the current login name on the banner, enter a name.
Backspace Click the Options button to display the dialog for defining the backspace character(s).
• If the printer does not support any backspace character, click the drop down arrow and select NO
BS.
• If the printer supports ASCII backspace character ($08$), click the drop down arrow and select
ASCII BS.
• To define a string sequence to send to the printer whenever a backspace character is sent by
Visual PRO/5, click the drop down arrow and select BS=. Select ASCII, Decimal, or Hex to
display the desired characters. You can either select the desired characters by clicking them in
the grid, or by entering them into the BS= box.
Conditional expr Enter a conditional expression for the printer, in the form T?, which allows this device to be
accessible only by Visual PRO/5 processes with a FID(0)=T?.
Number of copies Enter the number of copies. (The default is 1.) This value may be overridden within an application by
using the MODE= option on the OPEN of the printer.
Compressed Print Click the Options button to display the dialog for defining the compressed print settings.
• If the printer does not support compressed print, click the drop down arrow and select NO CP.
• To define a string sequence to send to the printer whenever a ‘CP’ mnemonic is sent by Visual
PRO/5, click the drop down arrow and select CP=. Select ASCII, Decimal, or Hex to display the
by entering them into the CP= box.
CP columns Enter the number of columns that the printer can print when in compressed print mode. The
maximum is 255.
CP lines Enter the number of printable lines when the printer is in compressed print mode.
Carriage return Click the Options button to display the dialog for defining the carriage return settings.
• If the printer does not support carriage return, click the drop down arrow and select NO CR.
• If the printer supports the ASCII carriage return character ($0D$), click the drop down arrow and
select ASCII CR.
• To define a string sequence to send to the printer whenever a carriage return is sent by Visual
PRO/5, click the drop down arrow and select CR=. Select ASCII, Decimal, or Hex to display the
by entering them into the CR= box.
the following:
printer will generate an ERROR=1 at runtime. To recover from this error, you must reset the print
buffer by issuing the command: PRINT (prtr)"".
that caused the error
Expanded Print on Click the Options button to display the dialog for defining the expanded print settings, as follows:
• If the printer does not support expanded print, click the drop down arrow and select NO EPON.
• To define a string sequence to send to the printer whenever an ‘EP’ mnemonic is sent by Visual
PRO/5, click the drop down arrow and select EPON=. Select ASCII, Decimal, or Hex to display
the desired characters. You can either select the desired characters by clicking them in the grid,
or by entering them into the EPON= box.
12
Expanded Print off Click the Options button to display the dialog for defining the expanded print settings, as follows:
• If the printer does not require special code to turn expanded print off, click the drop down arrow
and select NO EPOFF.
• To define a string sequence to send to the printer when it is in ‘EP’ mode and a new mnemonic
(‘SP’, ‘CP’) has been sent by Visual PRO/5, click the drop down arrow and select EPOFF=.
Select ASCII, Decimal, or Hex to display the desired characters. You can either select the
desired characters by clicking them in the grid, or by entering them into the EPOFF= box.
EP columns Enter the number of columns that an expanded print character will consume. For example, if EP
columns is 2, then each character printed in expanded print will count as two characters.
EP lines Enter the number of lines that an expanded print character will consume. For example, if EP lines is
2, then each line of expanded print will count as two lines.
Execute on OPEN Enter a command to be executed on the first print to the device. For example, this command might
be used to execute an operating system command to load fonts on a device.
Execute on CLOSE Enter a command to be executed at the close of the device. For example, this command might be
used to execute an operating system command to return the device to some known state.
Formfeed Click the Options button to display the dialog for defining the formfeed settings, as follows:
• If the printer does not support formfeed, click the drop down arrow and select NO FF.
• If the printer supports the ASCII form feed character ($0C$), click the drop down arrow and select
ASCII FF.
• To define a string sequence to send to the printer whenever a formfeed is sent by Visual PRO/5,
click the drop down arrow and select FF=. Select ASCII, Decimal, or Hex to display the desired
characters. You can either select the desired characters by clicking them in the grid, or by
entering them into the FF= box.
Form number If the printer supports a specification of the form number to be used in printing, define the default
number here. This value may be overridden within an application by using the MODE= option on the
OPEN of the printer.
Keep To cause a print job to remain in the queue even if the workstation printing it has hung up, click the
check box.
Linefeed Click the Options button to display the dialog for defining the linefeed settings.
• If the printer does not support linefeeds, click the drop down arrow and select NO LF.
• If the printer supports the ASCII linefeed character ($0A$), click the drop down arrow and select
ASCII LF.
• To define a string sequence to send to the printer whenever a ‘LF’ mnemonic is sent by Visual
PRO/5, click the drop down arrow and select LF=. Select ASCII, Decimal, or Hex to display the
by entering them into the LF= box.
Local printer To capture a local LPT port, enter the number of the port here. Valid entries are 1, 2, or 3. The
default value is 1.
Lock file Enter the name of the lock file you want created whenever this printer device is opened by Visual
PRO/5. This prevents more than one process from opening the device.
Login Enter the login name that must be provided if the workstation is not already logged into the server
containing the print queue. (Not used if Directory Services is available.)
Password Enter the password for the login name that must be provided if the workstation is not already logged
into the server containing the print queue. (Not used if Directory Services is available.)
Print on OPEN Click the Options button to display the dialog for defining the string sequence to send to the printer
upon its first OPEN.
• If it is not necessary to send any initializing string to the printer upon its first OPEN, click the drop
down arrow and select NO PTON.
13
• To define a string sequence to send to the printer upon its first OPEN, click the drop down arrow
and select PTON=. (However, no data is actually sent to the printer until the first PRINT
statement, upon which the Print on OPEN string is sent, followed by the ‘SP’ mnemonic.) Select
characters by clicking them in the grid, or by entering them into the PTON= box.
Print on CLOSE Click the Options button to display the dialog for defining the string sequence to send to the printer
upon its CLOSE.
• If it is not necessary to send any string to the printer upon its CLOSE, click the drop down arrow
and select NO PTOFF.
• To define a string sequence to send to the printer upon its CLOSE, click the drop down arrow and
select PTOFF=. Select ASCII, Decimal, or Hex to display the desired characters. You can either
select the desired characters by clicking them in the grid, or by entering them into the PTOFF=
box.
Queue name Enter the name of the queue for spooling. (This is a required parameter.)
Server name Enter the name of the file server on which the print queue is stored. (Not used if Directory Services is
available.)
Standard Print Click the Options button to display the dialog for defining the string sequence to send to the printer
at the first PRINT statement, and whenever a ‘SP’ mnemonic is sent by Visual PRO/5.
• To disable sending any string sequence to the printer before the first PRINT statement and
anytime the ‘SP’ mnemonic is sent by Visual PRO/5, click the drop down arrow and select NO
SP.
• To define a string sequence to send to the printer at the first PRINT statement, and whenever a
‘SP’ mnemonic is sent by Visual PRO/5, click the drop down arrow and select SP=. Select ASCII,
Decimal, or Hex to display the desired characters. You can either select the desired characters
by clicking them in the grid, or by entering them into the SP= box.
SP columns Enter the number of columns that the printer can print when in standard print mode. The maximum is
255.
maximum is 255.
Tabs To cause the Novell spooler to change tabs into spaces, with tab stops positioned at the requested
intervals, enter a numeric value between 0 and 18. The main reason for this capability is that some
print server utilities, such as REWIND, require that the file be in text format instead of byte stream
format.
(The default behavior is to send tab characters to the spooler without change.)
Wait on timeout Specify the number of seconds for Visual PRO/5 to wait before reporting printer timeouts. The valid
range is 0 to 255. Setting the value to 0 disables printer timeouts. The default timeout is 10 seconds.
14
DDBUILDER
Introduction
DDBuilder is a utility that can quickly and easily define and create new BASIS data dictionaries, modify existing data
dictionaries for use with PRO/5, Visual PRO/5, BBxPROGRESSION/4, and TAOS: The Developer’s Workbench, and
define SQL Views for use by the BASIS ODBC Driver.
Data dictionaries are organized, formal descriptions of data files that store physical and logical file attributes.
Applications can be designed to query the data dictionary at run time, which eliminates the reliance on hard-coded
program data structures. Because the application code can be data independent, data dictionaries can eliminate the
necessity of changing I/O lists and string references in numerous programs. Rather, one change is made to the data
dictionary, and a simple file update program is run.
Although many software packages, including those written in PRO/5 and Visual PRO/5, include their own data
dictionaries, DDBuilder lets developers exploit the power and convenience of a data dictionary without having to spend
time and resources creating a custom data dictionary utility.
DDBuilder runs under Windows 95 and Windows NT 4.0 and can be used to:
• Create and define data structures, including file layouts.
• Define data dictionaries created in other applications, and modify them for use with BASIS products.
• Print a representation of the database structure and contents.
• Fully exploit the functionality of the BASIS ODBC Driver and TAOS.
What is a Data Dictionary?

A data dictionary is an organized, formal description of data files. A data dictionary describes physical file attributes,
such as record lengths and file types, and logical file attributes, such as column names and output masks.
Many software packages, including packages written in PRO/5 and Visual PRO/5, include their own data dictionaries.
Using the BASIS Data Dictionary allows developers to exploit the power and convenience of a data dictionary without
writing their own data dictionary utilities from scratch. These are some of the advantages of describing an application's
data in a BASIS Data Dictionary:
• Using the data dictionary can make it much easier to upgrade when file structures change because the application
code can be data independent. When a file format changes, it is not necessary to change IOLISTs and string
references in numerous programs. Instead, the change is made once in the data dictionary. Modifying the data
dictionary does not automatically rebuild data files, but the data dictionary does provide the ease of access
necessary for a simple file update program to do the job.
• The data dictionary provides immediate documentation of data structures, including file layouts and data types.
• The BASIS ODBC Driver® and TAOS: The Developer's Workbench® access PRO/5 data files through the BASIS
Data Dictionary. These products require a BASIS Data Dictionary for full functionality.
Using DDBuilder
Creating PRO/5, ODBC Driver, and BBX PROGRESSION/4 Data Dictionaries
To create a new data dictionary for use with PRO/5, the BASIS ODBC Driver, or BBX PROGRESSION/4, do the
following:
1 Follow the Creating a New Data Dictionary procedures to establish the data and dictionary files location, create
data directories and paths, establish a configuration file, and, optionally, create a SQL.INI file.
2 Add tables, columns, and, optionally, indices, to the structure.
3 Save the data dictionary (see Saving a Data Dictionary).
4 Define each table and its attributes in the General Table property page (see Defining General Table Attributes ).
5 Define the attributes for each column in the table in the General Column property page (see Defining General
Column Attributes).
6 If you have defined an MKEYED, DIRECT, C-ISAM, or SORT table, define at least one index in the General Index
property page (see Defining the Index Structure).
15
7 Define views for ODBC data dictionaries (see Defining Views ).
8 Save the data dictionary again.
9 Make the data files (see Making Data Files). This creates the data files described by the dictionary definition.
Modifying PRO/5, ODBC Driver, and BBX PROGRESSION/4 Data Dictionaries

To modify an existing data dictionary for use with PRO/5, BBX PROGRESSION/4, or the BASIS ODBC Driver, do the
following:
1 Proceed to the one of the Opening an Existing Data Dictionary sections, as follows:
• To open a data source that is defined in an SQL.INI file, use the Opening a Data Source dialog.
• To open a data source that is not defined in an SQL.INI file, use the Opening a Configuration File dialog.
2 In the tree view, do any of the following to modify the data dictionary:
• Add, insert, rename, copy, paste, and delete elements.
• Redefine tables and their attributes in the General Table property page (see Defining General Table Attributes).
• Redefine the attributes for each column in the table in the General Column property page (see Defining General
Column Attributes).
• Redefine indices for MKEYED, DIRECT, C-ISAM, or SORT tables (see Defining Indices).
• Redefine views for ODBC data dictionaries (see Defining Views).
3 Save the data dictionary (see Saving a Data Dictionary ).
Creating Data Dictionaries for Use with TAOS

To create a new data dictionary for use with TAOS, do the following:
1 Follow the Creating a New Data Dictionary procedures to establish the data and dictionary files location, create
data directories and paths, establish a configuration file, and, optionally, create a SQL.INI file. This creates the data
dictionary files.
2 Add tables, columns, and, optionally, indices, to the structure.
4 Define the data source rules in the General Rules property page (see Defining Rules).
5 Define the data source typedef in the Typedef property pages (see Defining Typedefs).
6 Define tables and attributes in the General Table property page (see Defining General Table Attributes).
7 Define the remaining table properties (see Defining Advanced Table Option).
8 Define the attributes for each table’s column in the General Column property page (see Defining General Column
Attributes).
9 Define the remaining column properties (see Defining Advanced Column Options).
10 If you have defined an MKEYED, DIRECT, C-ISAM, or SORT table, define at least one index in the General Index
property page (see Defining Indices).
11 Save the data dictionary again.
12 Make the data files (see Making Data Files). This creates the data files described by the dictionary definition.
Modifying Data Dictionaries for Use with TAOS

To modify an existing data dictionary for use with TAOS, do the following:
To open a data source that is defined in an SQL.INI file, use the Opening a Data Source dialog.
To open a data source that is not defined in an SQL.INI file, use the Opening a Configuration File dialog.
1 Proceed to the one of the Opening an Existing Data Dictionary sections, as follows:
• To open a data source that is defined in an SQL.INI file, use the Opening a Data Source dialog.
• To open a data source that is not defined in an SQL.INI file, use the Opening a Configuration File dialog.
2 In the tree view, do any of the following to modify the data dictionary:
16
• Add, insert, rename, copy, paste, and delete elements.
• Redefine the data source rules in the General Rules property page (see Defining Rules).
• Redefine the data source typedef in the Typedef property pages (see Defining Typedefs).
• Redefine tables and attributes in the General Table property page (see Defining General Table Attributes).
• Redefine the attributes for each column in the table in the General Column property page (see Defining General
Column Attributes).
• Redefine indices for MKEYED, DIRECT, C-ISAM, or SORT tables (see Defining Indices).
Setup Files
SQL.INI and CONFIG.TPM are two setup files used by DDBuilder to keep track of data source information.
SQL.INI File
The SQL.INI file identifies the native BASIS databases that are available to the BASIS SQL Engine. The file gives
DDBuilder instant access to the list of databases, which provides quick access to data sources and data files.
The SQL.INI file lists the name and configuration file path for each data source. The data source names appear in the
Open Data Source dialog. An SQL.INI file can be created in any ASCII text editor. The following is an example of a
typical SQL.INI file:
BASIS Data Sources]
TAOS Demo Data
Chile Company
Class Reunion
[TAOS Demo Data]
CONFIG=c:/basis/ddbuild/examples/taosdemo/config.tpm
[Chile Company]
CONFIG=c:/basis/ddbuild/examples/chile/config.tpm
[Class Reunion]
CONFIG=c:/basis/ddbuild/examples/reunion/config.tpm
Either forward slashes (/) or back slashes (\) can be used to designate the directory paths. The SQL.INI file must be
installed in the BASIS home directory and must be listed in the win.ini file, as follows:
[BASIS]
home=path_to_BASIS_directory
CONFIG.TPM File
The DDBuilder configuration file, most commonly named CONFIG.TPM, tells DDBuilder where to find the data and
dictionary files. The file must contain the paths to the DICTIONARY and DATA directories but can also contain global
path and login information. The following is an example of a standard CONFIG.TPM file:
# Taos Demo Database Configuration
DICTIONARY=c:\basis\ddbuild\examples\taosdemo\bbdict\
DATA=c:\basis\ddbuild\examples\taosdemo\data\
Either forward slashes (/) or back slashes (\) can be used to designate the directory paths. DDBuilder recognizes a line
that starts with the “#” character as a comment.
If global path definitions are added to the config.tpm file, it is easier to update the paths to accommodate directory
structure changes. The following example illustrates possible global path definitions for the preceding CONFIG.TPM file:
# Taos Demo Database Configuration
PROJECT=c:\basis\ddbuild\examples\taosdemo\
DICTIONARY=(PROJECT)bbdict\
17
DATA=(PROJECT)data\
To use DDBuilder with the PRO/5 Data Server, provide user login information by adding the following line to the
CONFIG.TPM file:
USERID=loginname
The DDBuilder Interface

The following illustrates the DDBuilder interface.
Getting Started
Creating a New Data Dictionary

Creating a new data dictionary involves creating a data source and making data files.
Creating a Data Source

Creating a new data source involves designating directories for the dictionary and data storage files, creating a
configuration file, and, optionally, naming the data dictionary. To create a data source, do the following:
1 On the File menu, select New to display the Create New Data Source dialog:
18
2 Move to the directory where the configuration file and DATA and DICTIONARY subdirectories should be installed.
3 Enter a name for the configuration file (the standard is config.tpm) into the File name field.
4 Create the DATA and DICTIONARY subdirectories by clicking the standard Windows Create New Folder button,
which is the third button from the right in the upper right-hand corner of the dialog.
5 Enter the path to the DATA and DICTIONARY directories in the appropriate fields. If the data source will be
accessed from a network, enter the user ID in the USERID field.
6 Enter a data source name into the Data Source Name field. This name will appear in the SQL.INI file.
7 Once the path and data source information has been entered, navigate to the base directory and click Create.
DDBuilder will then create the configuration file and the base files in the DICTIONARY directory. The tree view then
appears, displaying the base Tables, typedef, Rules, and Views entries. Add tables to the data source.
Making Data Files

Making data files involves creating empty PRO/5 files for use in applications after table, column, and index information
has been defined.
The Make command creates empty data files. Do not use this command on pre-existing data files, except to
remove all file records.
To make data files, do the following:
1 In the tree view, click on the icon of a table to select it.

2 On the Edit menu, select Make to create the data files in the path specified in the General Table properties page’s
Path field.
3 Save the data dictionary (see Saving a Data Dictionary ).
Opening an Existing Data Dictionary

Opening an existing data dictionary involves opening a data source and opening a configuration file.
19
Opening a Data Source
To open an existing data source, do the following:
1 On the File menu, select Open Data Source to bring up the Open Data Source dialog.
2 The Open Data Source dialog displays an icon for each available data source. To open a data source, either
double-click its icon, or click the icon and then click Open.
3 The tree view then appears and displays the structure of the selected data source.
Opening a Configuration File

To open a data source that is not defined in the SQL.INI file, locate its configuration file, as follows:
1 On the File menu, select Open Config to bring up the Open dialog.
2 Browse through the Open dialog to locate the configuration file. Select the file and click Open.
3 The tree view then appears, and displays the structure of the data dictionary.
Saving a Data Dictionary

To save a data dictionary, on the File menu, select Save.
To save an existing data dictionary under a new name, do the following:
1 On the File menu, select Save As to bring up the Save As dialog:
2 If necessary, create a directory structure for the new files, which includes creating the base directory and the DATA
and DICTIONARY subdirectories.
DDBuilder for Windows NT 3.51 does not provide the capability to create folders in this dialog. If you are
using DDBuilder for Windows NT 3.51, move to the Windows Program Manager and create the DATA and
DICTIONARY subdirectories before proceeding.
3 Modify the paths in the DICTIONARY and DATA fields to reflect the new structure. Click Display to show the
current values shown in the configuration file.
20
4 Modify the text in the Data Source Name field to provide a unique name for the new data dictionary. If the data
source will be accessed from a network, enter a user ID in the USERID field.
5 Click Save to create the files in the DICTIONARY subdirectory.
6 On the Edit menu, select Make to create data files for the new data dictionary. Selecting Save from the File menu
saves all changes made to the BASIS data dictionary.
Printing the DDBuilder Tree View

Printing the tree view allows you to create a hardcopy representation of the database structure and contents.
Print Setup
To set the paper size, source, and orientation printing options, do the following:
1 On the File menu, select Print Setup to display the Print Setup dialog.
2 Select the desired paper size, source, and orientation settings, then click OK.
Print Preview
To display the tree view image to be printed, do the following:
1 On the File menu, select Print Preview. To move to additional print preview pages or change the print preview
resolution, choose from the following print preview buttons:
Command Description
Print Prints the current document.
Next Page Displays the next page of the structure.
Prev Page Displays the previous page of the structure.
One Page Displays one page on the screen.
Two Page Displays two pages on the screen.
Zoom In Alters the scale of the view by magnifying a particular element in the structure.
Zoom Out Expands the view to display the entire structure and background.
2 To return to the tree view, click Close.
Closing a Data Source

To close a data source at any time, do the following:
1 On the File menu, select Close.
2 If all changes have been saved, DDBuilder will close the data source automatically. Otherwise, DDBuilder will
prompt you to either save or discard the changes before closing the data source.
3 Open another data source or exit DDBuilder.
Exiting DDBuilder
To exit DDBuilder, do the following:
1 On the File menu, select Exit.
2 If all changes have been saved, DDBuilder will shut down automatically. Otherwise, DDBuilder will prompt you to
either save or discard the changes before shutting down.
21
Modifying Data Dictionary Elements
Adding Elements to a Data Dictionary

To add a table, column, index segment, typedef , rule, or view to the data dictionary, do the following:
1 In the tree view, select the input position by doing one of the following:
• For tables, typedef, rules, and views (which by nature are not order-specific), click the Tables, Typedefs, Rules, or
Views icon.
• For columns and index segments (which by nature are order-specific), click the preceding element of the same type.
2 Do one of the following to add the element:
• On the Edit menu, select Add.
• Right-click to display the context-sensitive menu, and select Add.
• On the toolbar, click the Add button.
3 The new element appears at the bottom of the list of identical elements, displaying a default name that consists of
the element type and a number. For example, the first table added will automatically be given the default name
TABLE1.
4 To enter a new name, click the element, enter a name that complies with the DDBuilder naming conventions, then
either press <Enter> or click the mouse outside of the tree view.
5 The next time the data dictionary is opened, the tables, typedef, rules, and views will be listed in alphabetical order,
but the order of columns and index segments will not change.
Inserting Columns into a Data Dictionary

To insert a column into the data dictionary, do the following:
1 In the tree view, click the column that occupies the position above the location for the new column.
2 Insert the new column by doing one of the following:
• On the Edit menu, select Insert.
• Right-click to display the context-sensitive menu, and select Insert.
3 The column then appears, displaying a default name such as COLUMN2. To enter a new name, click the element,
enter a name that complies with the DDBuilder naming conventions, then either press <Enter> or click the mouse
outside of the tree view.
Copying Data Dictionary Elements to the Clipboard

To copy a table, column, index segment, typedef, rule, or view to the Windows clipboard, do the following:
1 In the tree view, click the element to be copied.
2 Do one of the following to copy the element:
• On the Edit menu, select Copy.
• Right-click to display the context-sensitive menu, and select Copy.
• On the toolbar, click the Copy button
Elements can be pasted from the clipboard to other data dictionaries, which is a way to create an element in one data
dictionary for use by other data dictionaries.
Pasting Data Dictionary Elements from the Clipboard

To paste a table, column, index segment, typedef, rule, or view from the Windows clipboard, do the following:
1 In the tree view, select the paste position by doing one of the following:
2 Do one of the following to paste the element:
• On the Edit menu, select Paste Item.
• Right-click to display the context-sensitive menu, and select Paste.
22
3 The new element appears, displaying a default name that consists of the element type and a number. For example,
the first table pasted will automatically be given the default name TABLE1. To enter a new name, click the element
and enter a name that complies with the DDBuilder naming conventions, then either press <Enter> or click the
mouse outside of the tree view.
4 The next time the data dictionary is opened, the list of tables, typedefs, rules, and views will be listed in
alphabetical order, but column and index segment orders will not change. An element of one type cannot be pasted
into a group of a different type. For example, a column element cannot be pasted into a rules list because they are
not similar elements.
Deleting Elements from a Data Dictionary

To delete a table, column, index segment, typedef, rule, or view from the data dictionary, do the following:
1 Click the element to be deleted.
2 Do one of the following to delete the element:
• On the Edit menu, select Delete.
• On the toolbar, click the Delete button
3 The highlighted element is deleted from the list. To retrieve the deleted element, select the Undo/Redo command,
as explained in the following paragraph. If the file is saved after an element is deleted, the Undo/Redo command is
disabled.
Reversing/Reinstating the Last Modification

The Undo/Redo command reverses the most recent modification. The Undo command can be performed only once,
followed by a Redo command that can be performed only once.
1 To reverse the last modification, do one of the following:
• On the Edit menu, select Undo/Redo.
• On the toolbar, click the Undo/Redo button
2 To reinstate (redo) the modification, repeat the previous step. If the file has been saved, the Undo/Redo command
becomes disabled.
Renaming Data Dictionary Elements

To rename a table, column, index segment, rule, or view, click its name in the tree view, then click it again to draw the
standard Windows 95 naming box around it. To enter a new name, click the element and enter a name that complies
with the DDBuilder naming conventions, then either press <Enter> or click the mouse outside of the tree view.
DDBuilder Naming Conventions and Reserved Words

Each element in the data dictionary must comply with the following naming conventions:
The element’s name must:
• Start with a letter, but not with “DD_”.
• Contain only letters, numbers, and underscores.
• Not be a TAOS reserved word, as listed below:
ABORT ACCUMULATE ACROSS ADD ALL

ALTER AND ASCEND ASCENDING AVERAGE
BETWEEN BLOCK BREAK CALL CASE
CHAR CHARACTER CHOOSE COLUMN CONSTRAINT
CONTINUE COUNT CREATE DEC DECIMAL
DEFAULT DELETE DESCEND DESCENDING DISPLAY
DISTINCT DOMAIN DOUBLE DROP EACH
ELSE END ENTER EXEC EXIT
23
FILE FIND FLOAT FOREACH FROM
GLOBAL GOSUB GOTO GRANT GRAPH
HIDE HIGHEST IF IN INDEX
INIT INSERT INT INTEGER INTO
LIKE LOWEST MAXIMUM MESSAGE MINIMUM
NOBOX NONDISTINCT NOT NUM NUMERIC
OF OR PAUSE PRECISION REAL
REPEAT RULE RUN SAYWARN SELECT
SHOW SMALLINT SQL SUBMENU SUBROUTINE
SUBTOTAL SWITCH TABLE TEMPLATE TEMPORARY
THEN THROUGH THRU TOTAL TVALIDATE
TYPEDEF UNIQUE UNSIGNED UPDATE USING
VARCHAR VARYING VIEW WARN WHERE
Defining General Data Dictionaries
Defining General Data Sources

This section explains how to create general data sources. It describes how to define the general attributes for tables,
and columns, and explains how to create table indices. By entering all the necessary information for each table, column,
and index, data sources can be created for use with PRO/5, BBxPROGRESSION/ 4, TAOS, and the BASIS ODBC
Driver.
To define a data source, first define the table attributes, then define the required column attributes, and finally define at
least one index for MKEYED, DIRECT, C-ISAM, and SORT files.
Defining General Table Attributes

To define the attributes (i.e, file type, name, and physical table attributes) for a table, do the following:
1 In the tree view, select the desired table to display the General Table properties page.
2 Enter data into the appropriate fields. (In the Windows Help or HTML Help version of this document, click a field in
the image below to display its description.)
24
Defining General Column Attributes
To define the attributes (i.e., data type, column length, and numeric precision) for each column in a table, do the
following:
1 In the tree view, select the desired column to display the General Column properties page.
25
Defining Indices
Although multiple indices can be defined for multi-keyed MKEYED and C-ISAM file tables, only one index should be
defined for DIRECT, SORT, or single-keyed MKEYED tables.
Although the initial index is the primary unique key of the file, DDBuilder can be used to define as many indices as
needed. However, PRO/5 and TAOS limit multi-keyed MKEYED files to 16 keys and a total of 48 segments within those
keys. A segment can consist of a single column or portion of a column.
Up to 16 indices can be defined for an MKEYED table. The total size of an index cannot exceed 120 bytes. Each index
must contain one or more segments, but the table cannot contain more than 48 segments. Each segment can be made
up of a single column or part of a column. The indices must appear within the first 1024 bytes of the record.
To define the index, or key structure for a table, do the following:
1 In the tree view, select the desired index.
2 Select the index segment to display the General Index properties page.
Defining Data Dictionaries for Use with TAOS
Defining General Rules

To define the rules that apply to the data dictionary, do the following:
1 In the tree view, double-click the Rules icon to display the available rules.
2 Click the desired rule to display the General Rules properties page.
26
Defining Typedefs
A typedef (also known as a data type definition) defines a set of default parameters for data fields. Defining a typedef is
an efficient way to standardize data with similar format, precision, masking, and other parameters. You can use
typedefs to define default column characteristics, which is helpful when you want to standardize the characteristics for
a number of columns at the same time. Then, when you select the typedef as the base type in the General Column
property page, the column will inherit all of the typedef’s attributes.
Defining General Typedef Attributes

To define general typedef attributes (i.e., data type, column length, and numeric precision), do the following:
1 In the tree view, select the desired typedef to display the General Typedef properties page.
27
Defining Typedef Input Attributes
To define typedef input attributes, do the following:
2 Click the Input tab to display the Input properties page.
28
Defining Typedef Output Attributes
To define typedef output attributes (i.e., report title, output mask, and the default column value), do the following:
2 Click the Format tab to display the Format properties page.
Defining Application-Specific Typedef Attributes

To define application-specific typedef information for use in applications, do the following:
2 Click the Application tab to display the Application properties page.
3 Enter information to be stored for use by the application in the Application-defined fields. Each field can contain
up to 128 characters. TAOS does not modify any of this information.
29
Selecting Rules for Typedefs
Once the data dictionary general rules have been defined (see Defining General Rules ), they can be selected for use
with typedef, as follows:
2 Click the Select Validation tab to display the Select Validation properties page.
3 The All rules field displays all rules defined by the data dictionary. Do one of the following to select a rule in the All
rules field and copy it to the Current rules field:
• Double-click a rule.
• Click a rule and then click the Add button.
4 The Current rules field displays all of the rules currently active for the typedef.( A typedef can use the same rule
more than once.) Rules are executed according to the order specified in this field. To move a rule up or down the
list, click the rule, then use the Move up and Move down buttons to move it to the desired location.
5 To remove a rule from the Current rules field, either double-click the rule, or select it and then click the Remove
button.
30
Editing Typedef Rules
Once typedef rules have been selected, they can be customized without affecting the general rules definitions, as
follows:
2 Click the Edit Validation tab to display the Edit Validation properties page.
3 The Current rules field displays all defined rules that have been selected for this column. Click a rule to select it
and display the default values in the Error message, Error procedure, and Success procedure fields.
4 Edit the values in the Error message, Error procedure, and Success procedure fields, to customize the rules for
the selected typedef:
31
Defining Table Form and Process Attributes
A "form" is a front-end program that can be used by TAOS-developed programs to control most aspects of the user
interface. For more information about TAOS forms, see the Introduction to Forms and Form Generator Reference
chapters in the TAOS Developer’s Guide, Volume 2.
To define table form and process attributes (i.e., default form, report options, and open and close process code), do the
following:
2 Click the Options tab to display the Options properties page.
Defining Application-Specific Table Attributes

To define application-specific table information for use in applications, do the following:
32
Selecting Tables Rules
Once data dictionary general rules have been defined, they can be selected for individual tables, as follows:
2 Click the Select Rules tab to display the Select Rules properties page.
3 In the Rule type field, click one of the following rule types
• Update - Defines the criteria that must be met before existing records can be updated.
• Insert - Defines the criteria that must be met before new records can be created.
• Delete - Defines the criteria that must be met before existing records can be deleted.
• Drop table - Defines the criteria that must be met before TAOS code can be used to delete the table from the data
dictionary.
4 The Current rules field displays all of the rules currently active for the table.( A table can use the same rule more
than once.) Rules are executed according to the order specified in this field. To move a rule up or down the list,
click the rule, then use the Move up and Move down buttons to move it to the desired location.
button.
33
Editing Table Rules
Once table rules have been selected, they can be customized without affecting the general rules definitions, as follows:
2 Click the Edit Rules tab to display the Edit Rules properties page.
3 In the Rule type field, click one of the following rule types:
• Update - Defines the criteria that must be met before existing records can be updated.
• Insert - Defines the criteria that must be met before new records can be created.
• Delete - Defines the criteria that must be met before existing records can be deleted.
• Drop table - Defines the criteria that must be met before TAOS code can be used to delete the table from the data
dictionary.
4 The Current rules field displays all defined rules that have been selected for this table. Click a rule to select it and
display the default values in the Error message, Error procedure, and Success procedure fields.
the selected typedef:
34
Defining Column Input Attributes
To define the TAOS form input attributes for a selected column, do the following:
2 Click the Input tab to display the Input properties page.
35
Defining Column Output Attributes
To define output attributes (i.e., report title, output mask, and the default column value), do the following:
2 Click the Format tab to display the Format properties page.
Defining Application-Specific Column Attributes

To define application-specific column information for use in applications, do the following:
36
Selecting Rules for Columns
Once data dictionary general rules (see Defining General Rules) have been defined, they can be selected for individual
columns, as follows:
2 Click the Select Validation tab to display the Select Validation properties page.
3 The All rules field displays all rules defined by the data dictionary. Do one of the following to select a rule in the All
rules field and copy it to the Current rules field:
• Double-click a rule.
• Click a rule and then click the Add button.
4 The Current rules field displays all of the rules currently active for the column.( A column can use the same rule
more than once.) Rules are executed according to the order specified in this field. To move a rule up or down the
list, click the rule, then use the Move up and Move down buttons to move it to the desired location.
button.
37
Editing Column Rules
Once column rules have been selected, they can be customized without affecting the general rules definitions, as
follows:
2 Click the Edit Validation tab to display the Edit Validation properties page.
3 The Current rules field displays all defined rules that have been selected for this column. Click a rule to select it
and display the default values in the Error message, Error procedure, and Success procedure fields.
the selected column:
38
Creating and Defining Views
Using DDBuilder, you can add views to the data dictionary, select the inputs to the view, and define custom expressions
that govern the information displayed. Views are virtual queries that do not contain table data. Rather, they retrieve
columns from selected tables and previously-defined views at runtime and display them as part of a single normalized
data file. Views enable you to retain existing multiple record data files without creating new files and rewriting existing
code.
Do the following to add and define a view:
1 In the tree view, click on the Views icon to highlight it, then do one of the following:
• On the Edit menu, select Add.
• On the toolbar, click Add.
• Press <Ctrl> + A.
2 The view then appears in the tree view. The first view added to a data dictionary is given the default name VIEW1,
the second is given the default name VIEW2, etc. Click the view, enter a new name, then set the name by either
pressing <Enter> or clicking the mouse outside of the tree view.
3 In the tree view, select the desired view to display the Tables properties page. The All tables/views box will list all
tables and other views defined in the data dictionary.
4 In the All Tables/Views box, select the tables to be included in the view by doing one of the following:
• Double-click on an item.
• Click on the item, then click Add.
5 In the View type field, select the view type, as follows:
• To retrieve all data from the selected tables or views, click All.
• To only retrieve unique data from the selected tables or views, click Distinct.
6 On the properties page, click the Columns tab to display the Columns properties page.
7 In the All tables/columns list, select the desired columns for the view and click the Add button to copy them to the
Current Columns list.
8 On the properties page, click the Define tab to display the Define properties page. Each row in the grid defines a
column copied to the Current Columns list in the previous step, as follows:
• Column Name lists the name of the column, as defined in the tree view.
• Type lists the data type, as defined in the Data type field of the General Column properties page.
• Column Expression lists, by default, the name of the table and column displayed as table_name.column_name.
This column can be customized to contain an expression, as described in the next step.
9 To add a column to the view, click the Add button to add a blank row to the grid. Do the following to define the
column:
• Enter a name into the Column Name column.
• Enter STR or NUM into the Type column to define the data type.
• Enter a column name or expression into the Column Expression column. The entry can consist of:
• The name of a column, which retrieves the particular value for the column in a table.
• An expression, which modifies the data before it is displayed. An expression can consist of the names of existing
views, the names of two physical columns concatenated together, or a physical column, whose data has been
modified by a given factor. The expression can contain up to 255 characters. Specify table names to distinguish
between tables and views containing columns with the same name.
10 If you want to include a conditional SQL expression that limits the display information to specified criteria, enter it
into the Where box.
In a normalized database, the data contained in columns of individual tables cannot be broken into sub-components.
Each record contains information that is set to the exact same data format. The following two examples describe the
steps for creating views that display employee information using normalized data contained in a company’s employee
data file.
39
Example 1: Defining the SHORT_EMP View
In this example, the view uses the EMPLOYEE table’s employee identification number (EMP_ID), and name
(EMP_NAME) columns. Once the EMPLOYEE table and EMP_ID and EMP_NAME columns are defined in DDBuilder,
do the following:
1 In the tree view, add a view and name it SHORT_EMP.
2 On the property page, click the Tables tab.
3 In the All tables/views box, select the EMPLOYEE table to copy it to the Selected tables box.
4 On the property page, click the Column tab.

5 In the All tables/columns box, select the EMPLOYEE.EMP_ID and EMPLOYEE.EMP_NAME columns and click
Add to copy them to the Selected columns box.
40
6 On the properties page, click the Define tab. DDBuilder automatically inserts default column expression for the
EMP_ID and EMP_NAME columns. These expressions do not need to be modified.
Do not enter anything in the Where box.

When the SHORT_EMP view definition is applied to the employee data file, the following is an example of the output:
EMP_ID EMP_NAME
0001 Alicia Gomez
0002 Fred Jones
41
0003 John Lim
0004 Laura Montini
Example 2: Defining the SALES_EMP View

In this example, the view uses information contained in the employee identification number (EMP_ID), name
(EMP_NAME), and department (EMP_DEPT) columns, The view incorporates an SQL " Where" clause that restricts the
display to Sales department employees.
Once the EMPLOYEE table and EMP_ID, EMP_NAME, and EMP_DEPT columns are defined in DDBuilder, do the
following:
1 In the tree view, add a view and name it SALES_EMP.
2 On the properties page, click the Tables tab.
3 In the All tables/views box, select the EMPLOYEE table to copy it to the Selected tables box.
4 On the property page, click the Column tab.

5 In the All tables/columns box, select the EMPLOYEE.EMP_ID,,EMPLOYEE.EMP_NAME, and
EMPLOYEE.DEPT_NAME columns and click Add to copy them to the Selected columns box.
42
6 On the properties page, click the Define tab. DDBuilder automatically inserts default column expression for the
EMP_ID, EMP_NAME, and EMP_DEPT columns. These expressions do not need to be modified.
7 Enter EMP_DEPT="Sales" into the Where box:
When the SALES_EMP view definition is applied to the employee data file, the following is an example of the output:
EMP_ID EMP_NAME EMP_DEPT
0001 Alicia Gomez Sales
0002 Fred Jones Sales
43
(Information pertaining to John Lim and Laura Montini is not displayed in the view because they do not work in the sales
department.)
Defining Views for Use with Non-Normalized Data

"Non-normalized" files contain multiple data formats. DDBuilder, can access non-normalized files and create views that
remove individual data formats from physical files and display the information as if it were combined in a normalized file
format.
The following is an example of a multiple record type file that contains information for customers and orders pertaining
to two customers: Bob’s Western Wear (BWW) and Acme Boot Shop (ABS). Each customer has ordered two products:
BWW 0 Bob’s Western Wear 12 West St. Albany, OR
BWW 1 Felt Hat 21.95
BWW 2 Leather Gloves 4.80
ABS 0 ACME Boot Shop 9 Palm Ave. Fallon, NV
ABS 1 Leather Gloves 4.80
ABS 2 Stitched Boots 50.00
The first column contains the company code (i.e., BWW or ABS). The second column contains the order number (i.e., 1
or 2). The data format for these columns is the same.
The third column contains both the item description and the customer name. The fourth column contains both the
customer address and the item price. The fifth column contains both the customer city and blank entries. The sixth
column contains the customer state and blank entries. The data format for these columns is different.
Creating Base Tables

The first step to creating views to the non-normalized data is to create and define base CUSTOMER and ORDER
tables, as follows:
1 In the tree view, add the CUSTOMER and ORDER tables.
2 Click the General Table properties page for each table and define its properties.
3 In the tree view, add columns to the tables, as follows:
4 Click the General Column properties page for each column and define its properties.
Although each base table points to the same physical file, the BASIS ODBC Driver cannot be used to perform queries
against CUSTOMER and ORDER tables because each has a different column type and different numbers of columns.
You can, however, define two new relational views can be created to filter out the unneeded records.
Example 1: Defining the V_CUSTOMER View

Once the V_CUSTOMER view has been named and added, do the following to set the view definition:
1 In the tree view, select the V_CUSTOMER view.
3 In the All tables/views box, select the CUSTOMER table to copy it to the Selected tables box.
44
4 On the properties page, click the Columns tab.
5 In the All tables/columns box, select CUSTOMER.CUST_NUM, CUSTOMER.FIRST_NAME,
CUSTOMER.LAST_NAME, then click the Add button to copy them to the Current columns box.
6 On the properties page, click the Define tab.
7 In the All tables/columns, select CUSTOMER.CUST_NUM, CUSTOMER.FIRST_NAME,
CUSTOMER.LAST_NAME, then click the Add button to copy them to the Current columns field.
8 Click Add to create placeholders for each desired view column. The first view column will be given the default
name VCOLUMN1, the second VCOLUMN2, etc. This removes unwanted columns from the table and contains
only those columns listed in the query.
9 In the Column box, click the row that identifies the column you want to define.
10 In the Column Name column, enter a name that conforms to the DDBuilder naming conventions.
11 In the Type column, enter either NUM for a numeric type or STR for a string type.
12 In the Where box, enter the following expression:
ORDER_NUM=0
45
The V_CUSTOMERS view limits the selection of records to those that have an order number of 0.
Example 2: Defining the V_ORDER View

Once the V_ORDER view has been added and named, do the following to set the view definition:
1 In the tree view, select the V_ORDER view.
3 In the All tables/views box, select the ORDER table to copy it to the Selected tables box.
46
4 On the properties page, click the Define tab.
5 Add a column expression for each of the COMPANY_CODE, ORDER_NUM, PRICE, and ORDER_NUM columns.
6 Enter the following expression into the Where box:
ORDER.ORDER_NUM<>0
47
The V_ORDER view limits the selection of records to those in which the value of the ORDER_NUM column does not
equal zero and would display the following information:
COMPANY_CODE ORDER_NUM PRODUCT PRICE

BWW 1 Hat 21.95
BWW 2 Leather Gloves 4.80
ABS 1 Leather Gloves 4.80
ABS 2 Stitched Boots 50.00
The information displayed in the V_CUSTOMER and V_ORDER views was derived from multiple record types and did
not create or alter any physical files. Views can be used to peel individual record formats from a physical file and display
the records as if they were combined in a normalized file format.
48
USING THE GRID CONTROL IN VISUAL PRO/5
Introduction
A grid control can be used wherever tabular information needs to be displayed or edited in a graphical interface. The
Visual PRO/5 grid control supports up to 255 columns and 2.1 billion rows. The grid control can optionally manage
column and/or row headings. The headings are separate grid controls with unique control IDs that the main grid
manages automatically. Heading grids are placed inside the grid's bounding rectangle, reducing the size of the grid
body.
There are two basic modes for grid controls: data aware and standard. Data-aware grids display values in a file and
handle file I/O automatically. Standard grids do not perform any file I/O or automatic displaying. The program displays
data in cells and gets user input, if necessary. For additional information, see Standard and Data-Aware Grids.
Grid controls can be defined in ResBuilder or with the 'GRID' mnemonic. Not all grid attributes can be set when the grid
is created. Many grid attributes can be changed by the application at run time. These attributes include the number of
rows and columns, optional column and row headers, cell dimensions, colors, the alignment of text in cells, and cell
styles. The default cell style for cells in the body of a grid control is to operate as INPUTE controls. Cell style can also be
set to make cells look like check boxes or buttons. The column and row heading cell’s default style is raised button. The
grid control makes extensive use of the SENDMSG() function and the Notify event. A basic understanding of
SENDMSG() and Notify is required to program a grid control.
For an introduction to these concepts, see "Event-Driven GUI Programming With Notify and SENDMSG()" in the Spring
1998 BASIS Advantage at http://www.basis.com/advantage/mag-v2n1/eventdriven.html and related example at
http://www.basis.com/advantage/mag-v2n1/notify.src.
Standard and Data-Aware Grids

There are two basic modes for a grid control: standard and data-aware.
Standard Grids
A standard grid is not directly associated with any data source; the contents and actions of this sort of grid are defined
by the programmer. Standard Grid Control Tutorial 1: Display-Only Grid and Standard Grid Tutorial 2: User-Modifiable
Grid describe steps for creating and using Visual PRO/5 standard grid controls.
Standard grids require more Visual PRO/5 coding than data-aware grids but are more flexible. Standard grids are
populated and maintained by the application program. They are presentation structures, not data storage structures. It is
the responsibility of the application program to manage the data that is to be displayed in a grid and to keep track of
changes in the grid if editing is allowed (see the sample code for Start Edit - Grid SENDMSG() Function 31 for an
example).
Scrolling in a standard grid prompts it to be redrawn continuously. Column headings are cached, but there is no
guarantee that row headings and grid cells will be cached. Therefore, the main grid and the row headings grids may
need data from the application when they are redrawn. Grid controls request data by sending Notify event 22 to the
application. It is imperative that an event loop managing a standard grid check for Notify event 22 from the main grid
control and the row header grid, if present, and respond to them. Otherwise blank cells and headers may appear in the
grid (see the Standard Grid Tutorial 1: Display-Only Grid and Standard Grid Tutorial 2: User-Modifiable Grid for
examples of how this can be done).
There are two ways to put display data in standard grid cells:
• Position the highlight on the cell to be changed with Goto Column - Grid SENDMSG() Function 47 and Goto Row -
Grid SENDMSG() Function 48 . Use Set Single Cell - SENDMSG() Function 22 to display a value in one cell, or Set
Multiple Cells - SENDMSG() Function 21 to display a value in the current cell and one or more cells to the right of the
current cell.
• Use the grid information block and Draw Cell - Grid SENDMSG() Function 54 to pass data to a cell. The grid
information block is a templated string that can be used to specify the display value, colors, and style of an individual
cell. This approach is more flexible and generally requires less code because it does not require the highlight to be
moved. This is the preferred method for displaying data in response to a Notify event 22. See the documentation for
Draw Cell - Grid SENDMSG() Function 54 for more information.
To set up a program to capture data entered by a user in a grid (see the sample code for Start Edit - Grid SENDMSG()
Function 31 for more specifics):
1 Set up a data structure to hold the data to be displayed in the grid.
2 Code the event loop to respond to Notify event 22 by displaying data in cells with Draw Cell - Grid SENDMSG()
Function 54.
49
3 Code the event loop to respond to some event that will initiate editing in a grid cell. Left or right mouse button
clicks, for example, can be detected with Notify events. When the event is detected, put the cell in edit mode with
Start Edit - Grid SENDMSG() Function 31.
4 Code the event loop to respond to Notify event 7, which is fired when the user finishes editing.
5 Retrieve the edited value with Get Edit Text - Grid SENDMSG() Function 34.
6 Store the text in the data structure. It is generally not necessary to redisplay the data entered by the user unless a
validation routine changes the data after the user has entered it.
Data-Aware Grids
A data-aware grid is linked directly to a database table or a Visual PRO/5 data file; as the user works with the grid
control, changes are automatically reflected in the underlying table or file. Data-Aware Grid Control Tutorial describes
steps for creating and using a Visual PRO/5 data-aware grid control.
Data-aware grids display data from files and handle file I/O automatically. Data-aware grids require less Visual PRO/5
coding than standard grids but are not as flexible. Data-aware grids must be attached to an MKEYED, Visual PRO/5
SELECT, or SQL SELECT channel. Only one channel can be handled by a grid control at one time. A data-aware grid
can be used for viewing a file, or it can be programmed to allow inserting, deleting, and updating, if an MKEYED or
Visual PRO/5 SELECT channel is used. The grid control handles changes to the underlying file.
Validation Issues with Data-Aware Grids

Since data-aware grids write records to the underlying data file as soon as the user moves the highlight off the edited
row, it is impossible to validate all data before it is written. For this reason, only temporary files should be edited with
data-aware grids in production environments. Note that data-aware grids are read-only unless code is specifically
written to allow editing.
Standard Grid Control Tutorial 1: Display-Only Grid

The Visual PRO/5 grid control comes with dozens of features for formatting and manipulating information; most
programs will only use a few of the available features.
In general, there are three steps to follow when working with a standard grid control.
1 Create the basic grid control using either a resource file (ResBuilder and the 'RESOURCE' mnemonic) or the
'GRID' mnemonic.
2 Define various grid attributes using SENDMSG() functions.
3 Have the user interact with the grid using Notify events processed in an event loop.
The application in this example is a simple ASCII table. It shows a complete character set in a 16x16 grid. A menu
system is provided for changing the current font. Double-clicking on a cell displays the character from that cell, as well
as its decimal and hexadecimal values.
Defining the Window and Menu

1 Open the SYSGUI device (it is assumed that the device is defined in the config.bbx file as ALIAS X0 SYSGUI) and
create a main window for this application. Define a menu bar (option flag $0800$) and a close button (option flag
$0002$).
sysgui=unt
open (sysgui)"X0"
print (sysgui)'window'(20,40,580,450,"ASCII Table: Double-click any cell",
: $00000802$,$$)
2 Get a list of all the fonts defined in the system and create a Font menu:
menu$="&Font,0,,"+$0a$
fonts=pos($0a$=ctrl(sysgui,0,9),1,0)
dim font$:"name["+str(fonts)+"]:c(16*=10)"
font$=ctrl(sysgui,0,9)
for font=1 to fonts
menu$=menu$+" "+font.name$[font]+","+str(font)+",,"+$0a$
50
next font
menu$=menu$+$0a$
print (sysgui)'setmenu',menu$
Here is what the window looks like immediately after executing the code written so far:
Creating the Grid Control

1 Define control IDs for the main grid, column headings, and row headings:
grid=100,colid=101,rowid=102
2 Create the base grid control. The table following the code explains the meaning of the mnemonic arguments:
print (sysgui)'grid'(grid,20,20,544,430,$9846$,16,16,16,20,colid,20,rowid)
Argument Description
grid Grid control ID (main).
20,20,544,430 Grid location and size (X,Y,W,H)
$9846$ $8000$ = Vertical lines between columns.
$1000$ = 3-dimensional raised edge.
$0800$ = 3-dimensional client edge.
$0040$ = Horizontal lines between rows.
51
$0004$ = Grid has a row heading.
$0002$ = Grid has a column heading.
16 Initial number of rows.
16 Initial number of columns.
16 Maximum number of columns.
20 Width of the grid column heading.
colid Grid control ID (column heading).
20 Height of the grid row heading.
rowid Grid control ID (row heading).
For this example, the window and grid are defined using Visual PRO/5 code. In a production program, it is usually
easier to define windows and controls using ResBuilder. Column and row headings are separate grids that work
with the main grid. The following is an example of the grid immediately after executing the 'GRID' mnemonic:
3 Use Set Up Grid - SENDMSG() Function 30 to set column widths to 32 pixels each, not adjustable by the user:
dim ts$:"rows:u(4),cols:u(1),colwidth[16]:u(2),interspace[16]:u(2),
usersize[16]:u(2)"
ts.rows=16,ts.cols=16
for col=1 to 16
52
ts.colwidth[col]=32
next col
result$=sendmsg(sysgui,grid,30,0,ts$); rem ' initialize grid
4 Set the row height to 24 pixels:
result$=sendmsg(sysgui,grid,68,24,$$); rem ' set row height
The following is an example of the grid after applying the adjustments:
5 Set the column headers to 00, 01, 02, ... , 0D, OE, OF (0 through 15 in hexadecimal), using Set Cell - Grid
SENDMSG() Function 22:
for col=0 to 15
result$=sendmsg(sysgui,colid,22,col,hta(chr(col))); rem ' set column headers
next col
Only the data in column headers is permanently cached, so only column headers will be set in this manner. The row
header and main body cells are filled using a different technique, which is described below.
53
6 Deselect all cells.
result$=sendmsg(sysgui,grid,32,0,$$); rem ' deselect all cells
7 Grid information blocks will be used to load data in the main grid and the row heading grid. Use a variation of the
TMPL() function to assign templates and change the style of the row heading grid to recessed button:
dim grid$:tmpl(sysgui,ind=1)
grid$=sendmsg(sysgui,grid,20,0,$$)
dim row_head_grid$:tmpl(sysgui,ind=1)
8 Before starting the event loop, force a redraw of the main grid. This generates the Notify events that cause the
event loop to execute routines for filling cells with data.
result$=sendmsg(sysgui,grid,76,0,$$)
9 The completed table appears below:
54
Defining the Event Loop
1 With the grid completed, a standard event loop is entered until the user enters another command. For additional
information on event loops, see "Event-Driven GUI Programming with Notify and SENDMSG() " in the Spring 1998
BASIS Advantage magazine at http://www.basis.com/advantage/mag-v2n1/eventdriven.html. A related
example program can be found at http://www.basis.com/advantage/mag-v2n1/notify.src.
dim event$:tmpl(sysgui),generic$:noticetpl(0,0)while 1
read record(sysgui,siz=len(event$))event$ if event.code$="N": then
: generic$=notice(sysgui,event.x);
: dim notice$:noticetpl(generic.objtype,event.flags);
: notice$=generic$
The grid control is a presentation structure only; it doesn't necessarily retain the data in a cache, except column
headers, which are always cached. From time to time, the grid will request an update of one or more cells. For this
reason, the program will need to maintain a data structure of the data that belongs in the grid, and it must be
prepared to hand this information back to the grid control at any time.
2 When the main grid or the row heading grid needs to refresh one or more cells and doesn't have the data cached,
it sends Notify event number 22. When this message is received, code should be executed to redraw the specified
cell(s). The values returned in the templated NOTICE$ string control which cells are redrawn. Draw Cell -
SENDMSG() Function 54 uses the grid information block to transfer data to the control:
if event.id=grid and event.code$="N" and event.flags=22
: then
55
: for row=notice.toprow to notice.botrow;
: grid.row%=row;
: for col=notice.leftcol to notice.rightcol;
: grid.col%=col;
: grid.textcolor$=$000000$, grid.backcolor$=$ffffff$
: grid.style%=0
: byte=row*16+col;
: grid.buf$=chr(byte);
: result$=sendmsg(sysgui,grid,54,0,grid$);
: next col;
: next row
if event.id=rowid and event.code$="N" and event.flags=22
: then
: for row=notice.toprow to notice.botrow
: row_head_grid.row=row;
: row_head_grid.textcolor$=$000000$, row_head_grid.backcolor$=$ffffff0$
: grid.style%=2
: row_head_grid.buf$=hta(chr(row*16));
: tf$=sendmsg(sysgui,rowid,54,0,row_head_grid$)
: next row
Note that Notify events cause this code to be executed before user action takes place, thus filling the row header
and main grid cells immediately after the program begins.
3 If the user double-clicks on a cell, grid Notify event number 3 will be returned. When this event is trapped, display
the character from that cell, along with the equivalent value in decimal and hexadecimal:
if event.id=grid and event.code$="N" and event.flags=3
: then
: byte=notice.row*16+notice.col;
: i=msgbox("Character: "+chr(byte)+$0a$+"Decimal: "+str(byte)+$0a$+
: "Hexadecimal: "+hta(chr(byte)))
56
4 Enter code that responds to the user picking a new font from the menu. The 'FONT' mnemonic changes the font on
the main grid, then Redraw Grid - SENDMSG() Function 76 causes the grid to be redrawn with the new font.
Before redrawing, SENDMSG() Function 68 must be used to keep the cell height at 24 pixels:
if event.code$="C"
: then
: font_name$=font.name$[event.id];
: print (sysgui)'font'(grid,font_name$,0,0);
result$=sendmsg(sysgui,grid,68,24,$$);
: grid$=sendmsg(sysgui,grid,76,0,$$);
rem ' change font & redraw grid
57
5 End the program with the code to enable the user to terminate the event loop by clicking the close button, followed
by the end of the event loop itself and the end of the program:
if event.code$="X"
: then
: break
wend
end
6 The complete program is listed below:
0001 REM ' ASCII Table (Standard Grid Sample)
0010 LET SYSGUI=UNT
0020 OPEN (SYSGUI)"X0"
0030 PRINT (SYSGUI)'WINDOW'(20,40,580,450,"ASCII Table: Double-click on any ce
0030:ll",$00000802$,$$)
0040 LET MENU$="&Font,0,,"+$0A$
0050 LET FONTS=POS($0A$=CTRL(SYSGUI,0,9),1,0)
0060 DIM FONT$:"name["+STR(FONTS)+"]:c(16*=10)"
0070 LET FONT$=CTRL(SYSGUI,0,9)
0080 FOR FONT=1 TO FONTS; LET MENU$=MENU$+" "+FONT.NAME$[FONT]+","+STR(FONT)+"
58
0080:,,"+$0A$; NEXT FONT
0090 LET MENU$=MENU$+$0A$
0100 PRINT (SYSGUI)'SETMENU',MENU$
0110 LET GRID=100,COLID=101,ROWID=102
0120 PRINT (SYSGUI)'GRID'(GRID,20,20,548,430,$9846$,16,16,16,20,COLID,20,ROWID
0120:)
0130 DIM TS$:"rows:u(4),cols:u(1),colwidth[16]:u(2),interspace[16]:u(2),usersi
0130:ze[16]:u(2)"
0140 LET TS.ROWS=16,TS.COLS=16
0150 FOR COL=1 TO 16; LET TS.COLWIDTH[COL]=32; NEXT COL
0160 LET RESULT$=SENDMSG(SYSGUI,GRID,30,0,TS$); REM ' initialize grid
0170 LET RESULT$=SENDMSG(SYSGUI,GRID,68,24,$$); REM ' set row height
0180 FOR COL=0 TO 15; LET RESULT$=SENDMSG(SYSGUI,COLID,22,COL,HTA(CHR(COL)));
0180:NEXT COL; REM ' set column headers
0190 LET RESULT$=SENDMSG(SYSGUI,GRID,32,0,$$); REM ' deselect all cells
0200 DIM GRID$:TMPL(SYSGUI,IND=1)
0210 DIM ROW_HEAD_GRID$:TMPL(SYSGUI,IND=1)
0220 DIM EVENT$:TMPL(SYSGUI),GENERIC$:NOTICETPL(0,0)
0230 WHILE 1
0240 READ RECORD(SYSGUI,SIZ=LEN(EVENT$))EVENT$
0250 IF EVENT.CODE$="N" THEN LET GENERIC$=NOTICE(SYSGUI,EVENT.X); DIM NOTICE$:
0250:NOTICETPL(GENERIC.OBJTYPE,EVENT.FLAGS); LET NOTICE$=GENERIC$
0260 IF EVENT.ID=GRID AND EVENT.CODE$="N" AND EVENT.FLAGS=22 THEN FOR ROW=NOTI
0260:CE.TOPROW TO NOTICE.BOTROW; LET GRID.ROW%=ROW; FOR COL=NOTICE.LEFTCOL TO
0260:NOTICE.RIGHTCOL; LET GRID.COL%=COL; LET GRID.TEXTCOLOR$=$000000$,GRID.BAC
0260:KCOLOR$=$FFFFFF$; LET GRID.STYLE%=0; LET BYTE=ROW*16+COL; LET GRID.BUF$=C
0260:HR(BYTE); LET RESULT$=SENDMSG(SYSGUI,GRID,54,0,GRID$); NEXT COL; NEXT ROW
0270 IF EVENT.ID=ROWID AND EVENT.CODE$="N" AND EVENT.FLAGS=22 THEN FOR ROW=NOT
0270:ICE.TOPROW TO NOTICE.BOTROW; LET ROW_HEAD_GRID.ROW=ROW; LET ROW_HEAD_GRID
0270:.TEXTCOLOR$=$000000$,ROW_HEAD_GRID.BACKCOLOR$=$FFFFFF$; LET ROW_HEAD_GRID
0270:.STYLE%=2; LET ROW_HEAD_GRID.BUF$=HTA(CHR(ROW*16)); LET TF$=SENDMSG(SYSGU
0270:I,ROWID,54,0,ROW_HEAD_GRID$); NEXT ROW
0280 IF EVENT.ID=GRID AND EVENT.CODE$="N" AND EVENT.FLAGS=3 THEN LET BYTE=NOTI
0280:CE.ROW*16+NOTICE.COL; LET I=MSGBOX("Character: "+CHR(BYTE)+$0A$+"Decimal:
0280: "+STR(BYTE)+$0A$+"Hexadecimal: "+HTA(CHR(BYTE)))
0290 IF EVENT.CODE$="C" THEN LET FONT_NAME$=FONT.NAME$[EVENT.ID]; PRINT (SYSGU
0290:I)'FONT'(GRID,FONT_NAME$,0,0); LET RESULT$=SENDMSG(SYSGUI,GRID,68,24,$$);
0290: LET RESULT$=SENDMSG(SYSGUI,GRID,76,0,$$); REM ' change font & redraw gri
0290:d
0300 IF EVENT.ID=GRID AND EVENT.CODE$="N" AND EVENT.FLAGS=22 THEN FOR ROW=NOTI
0300:CE.TOPROW TO NOTICE.BOTROW; LET GRID.ROW%=ROW; FOR COL=NOTICE.LEFTCOL TO
0300:NOTICE.RIGHTCOL; LET GRID.COL%=COL; LET GRID.TEXTCOLOR$=$000000$,GRID.BAC
0300:KCOLOR$=$FFFFFF$; LET GRID.STYLE%=0; LET BYTE=ROW*16+COL; LET GRID.BUF$=C
59
0300:HR(BYTE); LET RESULT$=SENDMSG(SYSGUI,GRID,54,0,GRID$); NEXT COL; NEXT ROW
0310 IF EVENT.CODE$="X" THEN BREAK
0320 WEND
0330 END
Standard Grid Tutorial 2: User-Modifiable Grid

This tutorial describes how to create a grid that can be edited by users.
1 Open the SYSGUI device and dimension several variables:
sysgui=unt
open (sysgui)"X0"
dim event$:tmpl(sysgui); event=len(event$)
dim generic$:noticetpl(0,0)
dim edit_param$:"initstr:c(1*=0),key:u(2),col:u(2),row:u(4)"
dim grid_data$[2,2]
The event$ variable reads the event loop. The generic$ variable contains the template returned by the
NOTICETPL() function. (This function is new in Visual PRO/5 Rev. 2 and returns the Notify event template, which
is more extensive than the standard event template.) The edit_param$ variable causes the grid to enter edit mode.
The grid_data$[] array is used to store the information displayed in the grid. In this example, the data displayed in
the grid can be changed, and it is necessary to store the current value of every cell at all times so cells can be
redrawn as needed.
2 Draw the window and a grid of three rows and three columns, then assign a string template to the grid$ variable,
which contains the grid information block:
print (sysgui)'window'(50,50,200,150,"Grid Editing",$00000002$,$$)
grid=100
print (sysgui)'grid'(grid,20,20,160,120,$9040$,3,3,3)
3 Set the row height and change the highlight method from changing the highlight color (the default) to outlining the
cell:
result$=sendmsg(sysgui,grid,68,150/4,$$); rem ' row height
result$=sendmsg(sysgui,grid,57,0,$$); rem ' turn off color change highlighting
4 Create nested loops to populate the grid_data$[] array with numbers from 0 to 8. Note the grid_data$[] array is
loaded at the same time as the grid:
counter=0
for col=0 to 2
result$=sendmsg(sysgui,grid,36,col,chr(51)); rem ' column width
for row=0 to 2
grid_data$[col,row]=str(counter)
counter=counter+1
next row
next col
5 Set up the event loop. The basic structure is the same as in the previous example, but we’ll be checking for some
different events. The code to read the event loop and get a template for the Notify event information is identical:
while 1 read record(sysgui,len=event)event$ if event.code$="N" : then
: let notice$=generic$
60
6 Check for Notify event 22, which indicates that one or more cells in the grid must be redrawn. This event will be
sent to the program as soon as the grid displays, so the initial values will be displayed immediately.
if event.code$="N" and event.flags=22
: then
: for col=notice.leftcol% to notice.rightcol%;
: grid.col=col%;
: for row=notice.toprow% to notice.botrow%;
: grid.row=row%;
: grid.buf$=grid_data$[col,row];
: grid.textcolor$=$000000$,grid.backcolor$=ffffff$,grid.alignment%=2;
: result$=sendmsg(sysgui,grid,54,0,grid$);
: next row;
: next col
There are two user events that are a concern in a program that supports editing in a grid: the user indicating that
editing should begin, and the indication that editing should end. In this program, a left-button mouse click on any
cell will indicate editing should begin, and clicking on any other cell will indicate editing is complete, and the new
value should be stored in the data array. To check for a mouse click, we test for Notify event 14, which is
generated when the user clicks on a cell with the left mouse button. We’ll also check for notice.lparam=0 so that we
react to the mouse button being released instead of the button being pushed. When the user indicates editing
should begin, SENDMSG() Function 79 is issued to set a mask, and the grid control is put into edit mode with
SENDMSG() Function 31. If no mask is specified for a cell, no data can be entered. SENDMSG() Function 31
requires a specially formatted string, which is called edit_param$ in this sample. This string is defined in step one.
Here, the string is used to indicate the coordinates of the cell to be edited.
7 Check for Notify event 14 and notice.lparam=0:
if event.code$="N" and notice.code=14 and notice.lparam=0
: then
: result$=sendmsg(sysgui,grid,79,notice.col%,"000");
: edit_param.row%=notice.row%,edit_param.col%=notice.col%;
: result$=sendmsg(sysgui,grid,31,0,edit_param$)
8 Check for Notify event 7, which indicates that editing has been completed:
if event.code$="N" and notice.code=7
: then
: grid_data$[notice.col%,notice.row%]=sendmsg(sysgui,grid,34,0,$$)
When Notify event 7 is generated, SENDMSG() Function 34 is used to read the value in the just-edited cell and
store it in the data array.
9 End the program with the code to enable the user to terminate the event loop by clicking the close button, followed
by the end of the event loop itself and the end of the program:
if event.code$="X"
: then
: break
wend
end
10 The window created by the code so far looks like this:
61
11 The complete program is listed below:
0001 REM ' Grid Editing
0010 LET SYSGUI=UNT
0020 OPEN (SYSGUI)"X0"
0030 DIM EVENT$:TMPL(SYSGUI); LET EVENT=LEN(EVENT$)
0040 DIM GENERIC$:NOTICETPL(0,0)
0050 DIM EDIT_PARAM$:"initstr:c(1*=0),key:u(2),col:u(2),row:u(4)"
0060 DIM GRID_DATA$[2,2]
0070 PRINT (SYSGUI)'WINDOW'(50,50,200,150,"Grid Editing",$00000002$,$$)
0080 LET GRID=100
0090 PRINT (SYSGUI)'GRID'(100,20,20,160,120,$9040$,3,3,3)
0100 DIM GRID$:TMPL(SYSGUI,IND=1)
0110 LET RESULT$=SENDMSG(SYSGUI,GRID,68,150/4,$$); REM ' row height
0120 LET RESULT$=SENDMSG(SYSGUI,GRID,57,0,$$); REM ' turn off color change hig
0120:hlighting
0130 LET COUNTER=0
0140 FOR COL=0 TO 2
0150 LET RESULT$=SENDMSG(SYSGUI,GRID,36,COL,CHR(51)); REM ' column width
0160 FOR ROW=0 TO 2
0170 LET GRID_DATA$[COL,ROW]=STR(COUNTER)
0180 LET COUNTER=COUNTER+1
0190 NEXT ROW
0200 NEXT COL
0210 WHILE 1
0220 READ RECORD(SYSGUI,LEN=EVENT)EVENT$
0230 IF EVENT.CODE$="N" THEN LET GENERIC$=NOTICE(SYSGUI,EVENT.X); DIM NOTICE$:
0230:NOTICETPL(GENERIC.OBJTYPE,EVENT.FLAGS); LET NOTICE$=GENERIC$
0240 IF EVENT.CODE$="N" AND EVENT.FLAGS=22 THEN FOR COL=NOTICE.LEFTCOL% TO NOT
0240:ICE.RIGHTCOL%; LET GRID.COL%=COL; FOR ROW=NOTICE.TOPROW% TO NOTICE.BOTROW
0240:%; LET GRID.ROW%=ROW; LET GRID.BUF$=GRID_DATA$[COL,ROW]; LET GRID.TEXTCOL
0240:OR$=$000000$,GRID.BACKCOLOR$=$FFFFFF$,GRID.ALIGNMENT%=2; LET RESULT$=SEND
0240:MSG(SYSGUI,GRID,54,0,GRID$); NEXT ROW; NEXT COL
0250 IF EVENT.CODE$="N" AND NOTICE.CODE=14 AND NOTICE.LPARAM=0 THEN LET RESULT
62
0250:$=SENDMSG(SYSGUI,GRID,79,NOTICE.COL%,"000"),EDIT_PARAM.ROW%=NOTICE.ROW%,E
0250:DIT_PARAM.COL%=NOTICE.COL%,RESULT$=SENDMSG(SYSGUI,GRID,31,0,EDIT_PARAM$)
0260 IF EVENT.CODE$="N" AND NOTICE.CODE=7 THEN LET GRID_DATA$[NOTICE.COL%,NOTI
0260:CE.ROW%]=SENDMSG(SYSGUI,GRID,34,0,$$)
0270 IF EVENT.CODE$="X" THEN BREAK
0280 WEND
0290 END
Data-Aware Grid Tutorial

The small grid described in the first tutorial can be easily loaded and maintained under direct control of the programmer.
When large volumes of data are presented, the advantages of a data-aware grid come to the fore, especially if the data
is to be edited in the grid and not just viewed. A data-aware grid is created just like the standard grid. It is made data-
aware by being bound to a channel that is opened to an MKEYED file, Visual PRO/5 SELECT or SQL SELECT channel.
The grid then takes over managing the presentation of the data and the file I/O. This is a very powerful function that
simplifies the presentation of large amounts of data.
The following tutorial provides a step-by-step description of how to create a file maintenance grid using the datagrid.dat
file that is provided with Visual PRO/5 Rev. 2.x. Because of the large amount of code needed for a program of this
complexity, the tutorial uses GUIBuilder to cut down on the amount of code needed.
Creating the Resource

1 Start ResBuilder.
2 On the File menu, select New Resource File and create an empty resource file.
3 On the Edit menu, select Add Form to create a blank form that is numbered 101.
4 Open the form's property sheet and change only the following properties:
Property New Setting
Title Data-Aware Grid Demo
Name frmDataAwareGrid
x position 100
y position 100
Width 875
Height 400
5 Create a grid control by clicking the Grid button on the Controls toolbar and then clicking anywhere on the face of
the new form.
6 Open the grid's property sheet and change only the following properties:
Property New Setting Notes
Name grdTestGrid
x position 12
y position 22
Width 731
Height 353
Num Rows 1 This property is set to 1 at design time, but the number of rows will be
determined by the number of records in the file when the grid is bound
to the channel.
Num Columns 12 This property is set to 12 because the grid will use a particular file that
has 12 columns and the column width will be set at design time. It
would also be possible to set this property to 1 and set the number of
columns at run time with Visual PRO/5 code.
Row Head checked
63
Row Head Width 15
Col Head checked
Horiz Scroll checked
Vert Scroll checked
7 Click the ellipsis (...) button of the Column Prop property to display the Column Property dialog.
8 For each column, set the column width by selecting the column in the Column number list box and entering the
width according to the following.
Column Width
1 75
2 150
3 150
4 150
5 75
6 100
7 75
8 75
9 100
10 75
11 75
12 75
(It would have been possible to define column titles in the Column Property dialog, but they will be inserted as
part of the Visual PRO/5 code.)
9 Add four buttons to the form. In the property sheet, change only the following properties:
Property/Button 1 2 3 4
Name btnInsert btnDelet btnEdit BtnExit
e
Text &Add &Delete &Edit E&xit
x position 758 758 758 758
y position 20 60 100 140
10 On the File menu, save the resource by selecting Save As. The resource is now ready to become part of the file
maintenance program used in this tutorial.
Starting the Program in GUIBuilder

1 Start GUIBuilder.
2 On the File menu, select New to create a new GUIBuilder file. In the Name New GUIBuilder File dialog, enter a
filename. To simplify keeping track of the project files, give the GUIBuilder file the same name as the resource you
just created.
3 When the Create New Resource message box appears, click No because the resource was just created in
ResBuilder.
4 Select the resource you just created and click Open.
5 The Program Options dialog appears, providing the capability to set options for the program to be created.
6 Click OK to accept the default values. GUIBuilder is now ready for development.
7 On the Object drop-down list, select End of Job Code. The EOJ header remarks will appear in the GUIBuilder edit
area.
8 Type the following on a new line after the remarks to cause Visual PRO/5 to be released when the program
terminates:
64
release
9 On the Object drop-down list, select Form 101 frmDataAwareGrid.
10 On the Control drop-down list, select Push Button 106 btnExit.
11 On the Event drop-down list, select Button Pushed.
12 Enter the following code in the GUIBuilder edit area below the remark that says "rem ' Push button operated." (If
GUIBuilder is configured to use an external editor, invoke the editor instead.)
gb__eoj=1
This command will be executed when the user clicks the Exit button while the program is running. It sets the
GUIBuilder exit flag to true and causes the event loop to terminate and execute the EOJ code. Note that two
underscores are always used in the GUIBuilder special variables and function names.
13 On the Program menu, select Run Program.
14 On the Save Program As dialog click Save to save the generated program with the current name. The program
will run, displaying the resource created in ResBuilder created. The program doesn't do much yet, but it's possible
to see how the resource will look at run time.
15 Click the Exit button and the program will shut down, releasing the Visual PRO/5 session that GUIBuilder had
started.
Making the Grid Data-Aware

For our project we will use a file called datagrid.dat that was provided with the release. To get the project ready to
present a grid bound to a file we must write some initialization code and three subroutines.
Writing the Initialization Code

1 On the Object drop-down list, select Initialization Code. The Initialization header remarks will appear in the
GUIBuilder edit area.
2 Beneath the remarks add the following code:
rem get a template describing the form using GUIBuilder's get template function
dim datagrid_temp$:fngb__template$(gb__win_id$)
rem set up constants
gosub define_constants
rem open the data file and set up the template
gosub open_data_file
rem make the grid data-aware
gosub bind_grid_to_chan
This code uses a function provided with GUIBuilder to retrieve a templated string that describes the resource
(fngb__template$()). The template will be used later to get the grid control ID. Then the code executes GOSUBs to three
different subroutines, which we will write in the next three steps.
Creating the define_constants Subroutine

To create the define_constants routine, do the following:
1 On the Object drop-down list, select New Subroutine/Function.
2 In the Name Subroutine/Function dialog, type the following:
Define Constants
3 Click OK.
4 A set of remark headers will appear in the GUIBuilder edit area. Enter the following code after the initial comment
block:
define_constants:
rem message box constants
msgboxYes=6
65
msgboxYesNo=4
msgboxExclamation=48
msgboxInfo=64
msgboxSecond=256
rem grid send message functions
gridSetHeadingTitles=23
gridEndEdit=26
gridStartEdit=31
gridGetEdit=34
gridSetEdit=35
gridGetNumberofCols=40
gridGetNumberofRows=41
gridGetSelectedCol=44
gridGetSelectedRow=45
gridGotoCol=47
gridGotoRow=48
gridShowCurrentHeading=77
gridSetDataAware=80
gridDataAwareFunctions=81
rem misc grid values
gridHeadingDepressedMode=1
gridHeadingNotDepressedMode=0
rem data-aware functions
gridSetReadOnly$=$01$
gridDeleteRow$=$02$
gridAddRow$=$03$
gridRetrieveRow$=$04$
gridCancelUpdate$=$05$
return
This subroutine creates a series of variables that will be used in the grid's SENDMSG() functions to make the code
more readable.
Creating the open_data_file Subroutine

To create the open_data_file routine, do the following:
Open Data File
3 Click OK.
4 Beneath the remark headers for the new routine, enter the following code:
open_data_file:
data_chan = unt
open(data_chan)"datagrid.dat"
rem an alternate channel used for file operations
rem this channel will not be bound to the grid
66
alt_chan = unt
open(alt_chan)"datagrid.dat"
rem set up the template
datarec_desc$="CDNUMBER:C(6*=10):SHOW=1 ALIGN=0 LABEL=Number:," +
: "TITLE:C(50*=10):SHOW=1 ALIGN=0 LENGTH=50 LABEL=Title:," +
: "ARTIST:C(50*=10):SHOW=1 ALIGN=0 LENGTH=50 LABEL=Artist:," +
: "LABEL:C(50*=10):SHOW=1 ALIGN=0 LENGTH=50 LABEL=Label:," +
: "PLAYINGTIME:C(6*=10):SHOW=1 ALIGN=0 MASK=000.00 LABEL=Playing_Time:," +
: "RECORDINGTYPE:C(3*=10):SHOW=1 ALIGN=0 MASK=AAA LABEL=Recording_Type:," +
: "MUSICTYPE:C(15*=10):SHOW=1 ALIGN=0 LENGTH=15 LABEL=Music_Type:," +
: "BINLOCATION:C(10*=10):SHOW=1 ALIGN=0 LENGTH=10 LABEL=Bin_Location:," +
: "NUMBEROFTRACKS:N(10):SHOW=1 ALIGN=1 MASK=0000 LABEL=Number_of_Tracks:," +
: "ONHAND:N(10):SHOW=1 ALIGN=1 MASK=000000 LABEL=On_Hand:," +
: "COST:N(10):SHOW=1 ALIGN=1 LABEL=Cost:," +
: "RETAIL:N(10):SHOW=1 ALIGN=1 LABEL=Retail:"
dim datarec$:datarec_desc$
return
This code opens the file on two channels: one will be used by the grid and one will be used by the program when
creating new keys. It also creates a template description in datarec_desc$ and the template itself in datarec$. Each
field defined in datarec_desc$ has user attributes that control how the grid will look and behave, as follows:
Attribut Description
e
SHOW Controls whether or not the column will be shown. SHOW=1 indicates the column will be shown.
SHOW=0 indicates the column will be hidden.
ALIGN Controls the alignment of the grid cell data. ALIGN=0 causes the data to be left-justified, ALIGN=1
causes the data to be right-justified, and ALIGN=2 causes the data to be centered.
LABEL Provides the column header text. If a space is needed in the label text use the underscore
character ("_"), which will be replaced with a space at run time.
Note that column headers can also be defined in ResBuilder. Defining column headers in code
allows for greater flexibility but in some situations it makes maintenance more difficult.
MASK Provides an input mask that will be used when the cell is placed in edit mode. Valid mask
characters are the same as those used by INPUTE. When a cell is placed in edit mode the grid
uses a special INPUTE control to do the editing.
Creating the bind_grid_to_chan Subroutine

To create the bind_grid_to_chan subroutine, do the following:
Bind Grid to Chan
3 Click OK.
bind_grid_to_chan:
rem get the grid id from the template describing the form
grid_id=num(fattr(datagrid_temp$,"grdTestGrid","ID"))
rem send message 80 (gridSetDataAware) to grid to bind it to the channel
tf$=sendmsg(gb__sysgui,grid_id,gridSetDataAware,data_chan,datarec_desc$)
tf$=sendmsg(gb__sysgui,grid_id,gridShowCurrentHeading,gridHeadingDepressedMode,$$)
67
return
The line after the first remark above extracts the grid control ID from the template that describes the form. The
template was created in the initialization code. The line after the second remark binds the grid to the channel. This
is a SENDMSG() Function 80 . The function's parameter list contains several variables:
Variable Description
gb__sysgui Channel that GUIBuilder opened the SYSGUI on.
grid_id Grid control ID
gridSetDataAware Constant defined in define_constants; it is equal to
80.
data_chan Channel that the files is opened on.
datarec_desc$ template description created in open_data_file.
The last line uses Set Current Heading Mode - Grid SENDMSG() Function 77 to set the headings, both row and
column, to be displayed as depressed for the current row and column as the user navigates through the grid. The
program is now ready to run as a data-aware grid. All that remains to be done is to add the Add, Edit, and Delete
functions.
Running the Program for the First Time

Do the following to run the program:
2 In the Save Program dialog, click the Save button.
3 The program will present the records from the file in the grid.
4 Use the vertical scroll bar to move through the file.
68
5 Click with the mouse in various cells. This will move the grid focus to the clicked cell. Notice how the column and
row header for the highlighted cell are depressed. That's about all the program can do at this point because no
code has been added to provide the Edit, Add and Delete functions.
Placing a Cell in Edit Mode

To edit the data in a given cell we first need a way for the user to indicate a cell should be edited. Then we need a
method to place the cell in edit mode and finally a way to save the changes. In the sample program we'll provide two
methods for communicating our intention, double-clicking on the cell itself and clicking the edit button while the cell is
highlighted.
2 On the Control drop-down list, select Push Button 105 btnEdit.
4 In the GUIBuilder edit area, add code that will be executed any time the user clicks the Edit button:
gosub edit cell
5 On the Control drop-down list, select Grid 100 grdTestGrid.
6 On the Event drop-down list, select Grid Double Clicked.
7 Below the remarks in the GUIBuilder edit area, add code that will be executed any time the user double-clicks a
grid cell:
gosub edit cell
Writing the edit_cell Subroutine

Edit Cell
3 Click OK.
edit_cell:
rem get the current row
row$=sendmsg(gb__sysgui,grid_id,gridGetSelectedRow,0,"")
row = dec($00$+row$)
rem get the current col
col$=sendmsg(gb__sysgui,grid_id,gridGetSelectedCol,0,"")
col=dec(col$)
rem prep the edit
editparams_desc$="mask:c(1*=0),restore:c(1*=0),"+
: "initstr:c(1*=0),key:u(2),col:u(2),row:u(4)"
dim editparams$:editparams_desc$
editparams.key = 0
editparams.col = col
editparams.row = row
rem block editing the first column which is the primary key
if col=0 then
: msg$="You cannot edit the primary key for this record.";
: style = msgboxExclamation;
: title$="No Edit";
69
: trash=msgbox(msg$,style,title$)
: else
: trash$=sendmsg(gb__sysgui,grid_id,gridStartEdit,0,editparams$)
return
The code below the first remark extracts the grid ID from the descriptive template obtained in the initialization code
and then uses Get Selected Row - Grid SENDMSG() Function 45 to retrieve the row number of the selected cell.
The code below the second remark uses Get Selected Column - Grid SENDMSG() Function 44 to retrieve the
column number of the selected cell. Start Edit - Grid SENDMSG() Function 31 requires a templated string with
several values.
The code below the third remark creates this string and sets the values for the row and column we retrieved above.
The code below the fourth remark checks to see if the user wants to edit a cell in the first column, which contains
the primary key. If so, it presents a message box informing the user that the primary key cannot be edited. If the
user wants to edit a cell in any other column it issues Start Edit - SENDMSG() Function 31, with the templated
string we defined earlier.
Running the Program

Do the following to run the program:
2 In the Save Program dialog, click the Save button. The program will present the grid as it did before.
3 Double-click a cell. Notice that a heavy outline surrounds the cell and the caret is placed at the beginning of the
data.
4 Double-click any value in the Recording Type column.
5 Delete the current contents and type a new value. Notice that it will only accept alphabetic characters and it
converts them to upper case. That's because an 'AAA' mask for that field has been set in the template.
6 After editing the cell's contents, move the focus to another cell by clicking it. This instructs the grid to automatically
commit the changes made to the first cell.
Adding a New Record

To add a new record we'll need to connect a routine to the Button Pushed event for the Add button.
2 On the Control drop-down list, select Push Button 103 btnInsert.
4 In the GUIBuilder edit area, add code that will be executed any time the user clicks the Add button:
gosub add record
Create the add_record subroutine:
Add Record
3 Click OK.
4 Beneath the header remarks in the GUIBuilder edit area, enter the following code:
add_record:
rem send the add row message
trash$=sendmsg(gb__sysgui,grid_id,gridDataAwareFunctions,0,gridAddRow$)
rem this flag is checked in the Grid Edit Mode start event so that
rem the primary key value can be set by the program when the grid
rem start edit event occurs
70
add_in_progress=1
return
This code again gets the grid control ID from the descriptive template and then uses it in Perform Data-Aware
Function - Grid SENDMSG() Function 81, which is used to perform various actions on the data-aware grid. The last
parameter is a constant string value we set in the Define Constants routine: gridAddRow$. This parameter causes
the function to add a new row to the grid that will ultimately hold a new record. Finally we set a flag called
add_in_progress. Every time a grid cell is placed in edit mode a Grid Edit Mode event occurs. When this event
occurs and add_in_progress is true, it indicates that a new record has been added and we need to generate a new
key for that record.
Setting the Grid Edit Mode Event

2 On the Control drop-down list, select Grid 100 grdTestGrid.
3 On the Event drop-down list, select Grid Edit Mode.
4 In the GUIBuilder edit area, add the following code:
while add_in_progress
rem this code catches the start edit on col 0 (primary key) and sets the value)
add_in_progress=0
if gb__notice.col = 0 then
: gosub create_new_key;
: trash$=sendmsg(gb__sysgui,gb__notice.id,gridSetEdit,0,newkey$);
: trash$=sendmsg(gb__sysgui,gb__notice.id,gridEndEdit,0,$$);
: desc$="mask:c(1*=0),restore:c(1*=0),initstr:c(1*=0),";
: desc$=desc$+"key:u(2),col:u(2),row:u(4)";
: dim editparams$:desc$;
: editparams.key = 0;
: editparams.col = gb__notice.col+1;
: editparams.row = gb__notice.row;
: trash$=sendmsg(gb__sysgui,gb__notice.id,gridStartEdit,0,editparams$)
wend
This code will execute if the Grid Edit Mode event occurs and the add_in_progress flag is true. It immediately sets
add_in_progress to false and does a gosub to the create_new_key routine. The new key value is placed in the variable
newkey$ and passed to the grid's special INPUTE control via Set Edit Text - Grid SENDMSG() Function 35. This
message places the data from newkey$ into the INPUTE control. It then immediately issues End Edit - Grid
SENDMSG() Function 26 to end editing in the first column. Then we set up an editparams$ string as we did in the
edit_cell routine earlier. Notice that we bump the column value by 1. We then issue Start Edit - Grid SENDMSG()
Function 31 with the editparams$ that places the second column in edit mode.
The Grid Edit Mode event is a notify event. GUIBuilder automatically retrieves the notice from the sysgui device and
places it in a templated string call gb__notice$. The routine above uses that string to access the row and column
information.
Creating the create_new_key Routine

Create New Key
3 Click OK.
create_new_key:
rem ' assign new number
71
trash$=fattr(datarec$,"CDNUMBER")
keylen = dec(trash$(10,2))
keymask$ = fill(keylen,"0")
newkey$=keyl(alt_chan,err=cnk_no_keyl)
done=0
bump_it:
while !(done)
newkey$=str(num(newkey$)+5:keymask$)
done=1
read(alt_chan,key=newkey$,dom=got_it)
done=0
got_it:
wend
return
cnk_no_keyl:
rem this handles the case of an empty file
print err
newkey$=str(1:keymask$)
goto bump_it
This code generates a new key for the file. First, it gets an encoded information string for the CDNUMBER field and
gets the length of the key from the string. Second, it builds a mask of all zeros that is as long as the key length.
Third, it uses the KEYL function to get the last key in the file. Notice that it uses the alt_chan and not the channel
that was bound to the grid. Once a channel has been bound the grid the program should avoid any I/O to that
channel. Fourth, it bumps the CDNUMBER value by 5 and tests to see if it is in the file. If not we are done and the
variable newkey$ contains the new key. If it is in the file we loop again. The cnk_no_keyl routine is there to handle
the special case of an empty file.
7 Click the Add button. A blank row will appear at the end of the grid, and the new key value will be inserted into the
first column. The second column will be in edit mode. Once the focus moves off the new row the record is saved to
the file.
72
Deleting a Record
Do the following to select the event and create the routine that makes it possible to delete a record from the file.
2 On the Control drop-down list, select Push Button 104 btnDelete.
4 In the GUIBuilder edit area, add code that will be executed any time the user clicks the Delete button:
gosub delete current row
Delete Current Row
7 Click OK.
delete_current_row:
rem get the current row
row$=sendmsg(gb__sysgui,grid_id,gridGetSelectedRow,0,"")
row = dec($00$+row$)
rem create a temporary template to hold row contents
dim tmp_datarec$:datarec_desc$
rem get the data from the current row
73
tmp_datarec$=sendmsg(gb__sysgui,grid_id,gridDataAwareFunctions,row,gridRetrieveRow$)
rem confirm the delete
msg$="Are you sure you want to delete CD Number "+tmp_datarec.cdnumber$+"?"
style = msgboxYesNo+msgboxInfo+msgboxSecond
title$="Delete Confirmation"
resp = msgbox(msg$,style,title$)
rem if response is yes then send the delete message
if resp<>msgboxYes then
: return
rem delete the row
trash$=sendmsg(gb__sysgui,grid_id,gridDataAwareFunctions,row,gridDeleteRow$)
rem disconnect the grid
trash$=sendmsg(gb__sysgui,grid_id,gridSetDataAware,0,$$)
rem reset the file pointer
read(data_chan,key="",err=dr_continue)
dr_continue:
rem reconnect the grid
trash$=sendmsg(gb__sysgui,grid_id,gridSetDataAware,data_chan,datarec_desc$)
return
The code first gets the grid control ID and then use Get Selected Row - Grid SENDMSG() Function 45. Second, it
dimensions a temporary template to hold the data from the grid row. Third, using the row number, Perform Data-Aware
Function - Grid SENDMSG() Function 81 is issued with the Retrieve Row flag, which instructs the function to return all
the data from the current row into the temporary template. Fourth, a message box is created to allow the user to confirm
or reject the deletion.
The actual delete takes place with SENDMSG() Function 81 with the Delete Row flag. Once a record is deleted the grid
will visually indicate this by displaying a deleted icon in the first column and filling all the data fields with asterisks. The
only way to clear the empty row is to disconnect and reconnect the data channel. This is accomplished with the last
three commands in the routine. We issue Set Channel and Template - Grid SENDMSG() Function 80 with a channel
number of zero. This disconnects the grid from the channel. Then we reset the file pointer on the primary channel and
rebind it to the grid with SENDMSG() Function 80.
3 Click any row, then click the Delete button. The program displays a message box, prompting you to confirm or
reject the deletion.
74
GUIBUILDER
Introduction
GUIBuilder is the new Visual Programming Environment for Visual PRO/5 Rev 2.x. It provides all of the tools needed for
developing Visual PRO/5 2.x event-driven GUI programs in a high-level graphical environment.
GUIBuilder greatly simplifies the development of GUI programs by enabling you to concentrate on business rules, rather
than on the details of how to write a GUI program. It automatically builds a framework that includes the complete event
loop, with places where you can insert code, known as event handlers, to respond to selected events.
GUIBuilder Features
GUIBuilder is the new visual programming environment for Visual PRO/5 Rev 2.x. It provides all of the tools needed for
developing Visual PRO/5 2.x event-driven GUI programs in a high-level, graphical environment.
There are several advantages to developing programs using ResBuilder:
GUIBuilder Glossary
Form ID (Also: Form Number). A positive integer from 1 to 32767 assigned by the developer to a top-level
window in ResBuilder or ResEdit. A form is equivalent to a Visual PRO/5 'WINDOW' (parent window),
also called a "Primary Window" in Microsoft's documentation.
Window For a top-level (Primary) window, this is equivalent to the Form ID. For a Secondary Window (Visual
ID PRO/5 'CHILD'), the Window ID shows how the child window is related to its top-level form. A form with
Form ID of "10" also has a Window ID of "10. A child window of "1001" within that form has a window ID
of "10.1001. Because child windows can be nested to an arbitrary level, arbitrarily long Window IDs are
possible.
Control (Also: Control Number). A positive integer from 1 to 32767 assigned by the developer to a graphical
ID control within a specific window. As with Form IDs and Window IDs, Control IDs are basically arbitrary,
but some Control IDs have special meaning. Control ID 1 is assigned to the "OK" button, if any. This
button will be activated by the RETURN key if no other control on the window has keyboard focus.
Control ID 2 is assigned to the "Close" or "Cancel" button, if any. This button will be activated by the
ESCAPE key. Also, Control IDs determine the tab order within the window. When the user presses the
TAB key, keyboard focus moves to the next control, based on ascending Control ID sequence. Also,
GUIBuilder will sometimes refer to Control ID 0, meaning the window itself.
Event In Visual PRO/5, the event code is a single, case-sensitive letter or digit that identifies some event, like a
Code button push or a close-box activation. In the case of several events, GUIBuilder appends an integer
qualifier to the base event code. A base event code of "f" (focus gained or lost) maps to two distinct
GUIBuilder events -- "f0" (focus lost) and "f1" (focus gained). Normally you don't need to be concerned
with the specific event codes; GUIBuilder will always provide a list of available events for any given
control or window.
GUI Design
The hardest part about GUI programming isn’t the mechanics of managing windows and controls; with a tool like
GUIBuilder, a lot of the mechanical details can be automated. The real difficulty is learning how to think in an entirely
new way. In a GUI program, you don’t directly control program flow; you create a window with various graphical controls
and wait for the user to do something. As long as a control is visible and enabled, the user can activate it (push a button,
select a menu item, check a check-box or radio button, or type into an edit box, for example). Your program needs to be
prepared to respond in a logical way to whatever the user chooses to do. Your direct control over the process is limited.
One of the more useful approaches is to only make windows and controls visible and active when you are prepared to
respond to them. For example, if there is no printer configured, you can gray out printer-related functions. The user can
only select the Print option when you know the printer is available, so error handling becomes much simpler.
GUIBuilder does a good job of managing the technical (housekeeping) details of an event-driven GUI program, but it
can’t help out with program design. Because a GUI program operates very differently from a traditional character mode
program, it’s a good idea to invest some time in reading and thinking about GUI design issues. The following references
are a useful starting point:
The Windows Interface Guidelines for Software Design (Microsoft):
75
http://www.microsoft.com/win32dev/uiguide/
Macintosh Human Interface Guidelines (Apple):
http://developer.apple.com/techpubs/mac/HIGuidelines/HIGuidelines-2.html
Interface Hall of Shame, Interface Hall of Fame, and useful links:
http://www.iarchitect.com/
Articles in The Advantage:
http://www.basis.com/advantage/mag-v1n4/resources.html
http://www.basis.com/advantage/mag-v1n4/offtheshelf.html
The GUIBuilder Interface

The GUIBuilder interface consists of the menu bar, tool bar, drop-down lists, and edit area.
Drop-down Lists
The drop down lists provide the capability to access and edit code blocks.
Drop-down Function
List
Object This is a list of top-level objects for the user to choose from, including Initialization (edit
initialization code), Forms (a selection for each top-level form in the resource), End of
76
Job (edit end of job code), Subroutines (a selection for each subroutine/function defined
in the .gbf file), and New Subroutine/Function. The other three drop-down lists are only
functional if the user selects a Form ID in this list.
Window If the user selected a Form in the Object list, this will contain a list of windows defined
for that form. First on the list is the form itself, followed by child windows, if any. If there
are no child windows, the Window list box will show the Form ID, and it won't be
editable by the user.
Control After a window has been selected in the Window list, the user can choose a control in
the Control list. First on the list of controls will be the window (or form), because events
can be defined for windows. Following the form/window will be the list of controls on
that window. If the window contains no controls, the form/window will be automatically
selected, and it won't be editable by the user.
Event After a control has been selected in the Control list, the user can choose an event in
the Event list. If there is only one event defined for the selected control (e.g. a tool
button), the event is automatically selected, and the user is taken directly to the edit
window to create or edit the event handler code, or the external editor menu choice and
tool button are enabled. If there is more than one possible event for the selected
control, you can select one from the list. An "*" in front of an event means that an event-
handler routine already exists for that event code. If the event list says "-----No Events
Defined-----", then the selected control doesn't have any events (e.g. a group box). If
the event list says "-----No Events Visible-----", then the selected control does define at
least one possible event, but the events defined for this control are not visible based on
the event mask set in the resource file. Toggle the "Show All Events" tool button to see
all of the events. To use an event that's not visible, you'll need to edit the event mask in
the resource file.
Getting Started
Creating New GUIBuilder Files

To create a new GUIBuilder.(gbf) file do the following:
1 Do one of the following:
• On the File menu, select New.
• On the toolbar, click the New button.
• Press <Ctrl>+ N.
2 The Name New GUIBuilder File dialog appears, prompting you to provide a name for the new file. Move to the
directory into which you want to save the file, enter a filename (no file suffix is necessary) and click Save.
3 The Create New Resource dialog appears. Do one of the following:
• If you have not created a resource file, and want to call up ResBuilder to create one, click Yes. (Upon exiting
ResBuilder, you will be returned to GUIBuilder.)
• If you have already created a resource file, and want to continue creating the .gbf file, click No.
• If you want to remain in ResBuilder, but discontinue the new file creation process, click Cancel.
4 The Open Resource File dialog appears, prompting you to select a resource file. Move to the directory that
contains the resource file, select it, and click Open.
5 The Program Options Dialog appears, which enables you to define the following options for the program to be
created:
• To specify a PREFIX file search path, enter the path into the Enter search PREFIX field.
• To specify the number of digits of numeric precision, enter the desired value (acceptable range is -1 to 16, where -1
indicates maximum precision) into the Enter precision field.
• To specify the number of pages to use for a minimum memory check, enter the number into the Enter pages for
minimum memory check field.
• To specify which forms to display upon startup of the program, click one of the following buttons: Show all form(s) at
program startup, Show only the first form at program startup, or Do not show any forms at program startup
buttons.
77
• To include remarks in the tokenized program, click the Include remarks in tokenized program check box. Remarks
are always included in the source version of the generated program.
• To include a message that appears near the beginning of the program code, enter a text string into the Copyright
Message field.
6 Enter the desired information and click OK to continue. (The options information can be modified at a later time via
the Program Options command.)
7 The GUIBuilder title bar displays the .gbf filename to indicate that the file is open and ready for modification.
Opening Existing GUIBuilder Files

To open an existing GUIBuilder (.gbf) file, do the following:
1 If the file is listed in the MRU list (most recently used files), select it. Otherwise, do one of the following to display
the Open GUIBuilder File dialog, which allows you to select the file:
• On the File menu, select Open.
• On the toolbar, click the Open button.
• Press <Ctrl>+ O.
2 The Open GUIBuilder File dialog appears. Move to the directory that contains the .gbf file and click Open.
Saving GUIBuilder Files

The current GUIBuilder (.gbf) file is automatically saved whenever you exit from GUIBuilder, close the .gbf file, or open a
new .gbf file. It is also saved every time you View, Build, or Run the generated program.
To save the file at any other time, do one of the following:
• On the toolbar, click the Save button.
• Press <Ctrl>+ S.
Printing GUIBuilder Files

To print the GUIBuilder (.gbf) file, do the following:
1 Display the Print dialog by doing one of the following:
• On the toolbar, click the Print button.
• Press <Ctrl>+ P.
2 Select the desired print options and click OK.
Note: If there is no SYSPRINT device defined in the config.bbx file, this option will be unavailable.
Exiting GUIBuilder
To exit GUIBuilder do one of the following:
• On the File menu, select Exit.
• On the title bar, click the Close button.
• Press <Alt>+ F4.
Working with Blocks of Code: Defining Code Blocks
Defining Event Handler Code Blocks

Defining a code block involves defining the Visual PRO/5 code to be executed upon occurrence of the event.
There are two ways to select the code block to be edited:
78
• Selection via drop down lists.
• Selection by clicking on the form to which the event is to be attached.
List Method
1 Click the drop down arrow of the Object list to display the forms in the resource file. (The Object list also displays
Initialization, End of Job, and user-defined Subroutines and Functions, but we’re not interested in them at this
point.) Select the form that contains the resource (form, window, or control) for which you want to define the code
block.
2 If the resource is a child window, or is contained within a child window, click the drop down arrow of the Window
list and select the child window. (The Window list initially shows the form selected in the Object list.) If there are
no child windows on the selected form, the form itself will already be selected in the Window list, and it will be
grayed out so it cannot be edited.
3 Click the drop down arrow of the Control list to display the list of controls contained in the form or window selected
in the Window list.
• To define a code block for the form or window selected in the Window list, select it again in the Control list. If the
selected form or window contains no controls, it will already be selected in the Control list, and it will be grayed out so
it cannot be edited.
• To define a code block for a control contained in the form or window selected in the Window list, select that control
from the list.
4 Click the drop down arrow of the Event list and select an event. If there is only one event available for the item
selected in the Control list, it will already be selected in the Event list, and it will be grayed out so it cannot be
edited. If you are creating a new event handler:
• The code will be initialized with a comment block to identify the event; for some events, control variables will also be
set to help you out.
• If the event will not be visible in the event loop of the generated program, the Event Warning dialog is displayed.
This is to warn you that you’ll need to edit the window attributes in the resource file to make this event visible within
the event loop.
5 If you are using an external editor, click the Edit Code tool button to edit the block of code using your external editor.
6 Enter or edit the Visual PRO/5 code to be executed upon occurrence of the event.
Visual Method
• On the Program menu, select Select Form, then select the desired form from the sub-menu.
• On the toolbar, click the Select Form button, then select the desired form in the Select Form dialog and click OK.
2 If GUIBuilder is configured to provide extra help at this point, the Selecting a Form dialog is displayed to provide
instructions for working with the form. (To prevent this dialog from being displayed each time you select a form,
click the Don’t show me this screen again checkbox.) Click OK to dismiss the Selecting a Form dialog.
3 The selected form appears. Do one of the following:
• To define an event handler for the form as a whole, double-click on the form background.
• To define an event handler for a specific control, double-click on that control.
• To define an event handler for a menu item, select that menu item.
• To define an event handler for the close box, click the close box.
• To exit from the form without defining an event handler, press the Delete key.
4 If you clicked on a part of the form where more than one control overlaps, the Select Control dialog appears.
Select a control from the list and click OK.
5 To select an event:
• If you selected a control that only supports one type of event, or if you’re defining an event handler for a menu item
or the close box, the correct event is selected automatically.
• If you clicked on the form background or on a control that supports more than one type of event, the Select Event
dialog appears. Select an event from the list and click OK.
79
6 Even when a control supports a certain type of event, that event might not be visible in the event loop of the
generated program. This means that the event is optional, and hasn’t been enabled for this window in ResBuilder.
If such an event is selected, the Event Warning dialog appears. This dialog indicates that, while you can go ahead
and create the event handler code, it won’t be visible to the event loop unless you go back into ResBuilder and edit
the window properties, enabling the event. (The following events are always visible: Close box operated; Menu
selection made; Push button operated; Tool button operated; and any of the Notify events, code “N”).
7 If you are creating a new event handler, the code block is initialized with a comment to identify the event. For some
events, control variables are also set to help you out. After the initial comment block inserted by GUIBuilder, enter
your own Visual PRO/5 code to be executed whenever this event occurs in the generated program. There’s no
need to explicitly save each block of code; when you move on to the next code block, or when you close the file or
exit from the program, the block of code is automatically saved to your .gbf file.
Defining Initialization Code

To define the code to be executed immediately before the event loop (such as opening data files, defining record
templates, and initializing global variables), do the following:
• On the Program menu, select Initialization.
• On the toolbar, click the Edit Subroutine button, then select Initialization from the list.
• Click the drop down arrow of the Object list box and select Init Code.
2 Enter the Visual PRO/5 code to be executed immediately before going into the event loop.
Defining End of Job Code

To define the code to be executed immediately following the event loop (such as closing data files and performing
whatever other cleanup might be necessary), do the following:
• On the Program menu, select End of Job.
• On the toolbar, click the Edit Subroutine button, then select End of Job from the list.
• Click the drop down arrow of the Object list box and select EOJ Code.
2 Enter the code to be executed immediately after exiting from the event loop.
Defining Subroutines/Functions
To edit code in subroutines, functions, or non-executing statements like TABLE, IOLIST, and DATA, do the following:
• On the Program menu, select Subroutines/Functions.
• Click the drop down arrow of the Object list box and select Subroutines/Functions.
• On the toolbar, click the Edit Subroutine button, then select a subroutine from the list, or New Subroutine/Function
to create a new subroutine or function.
2 If you’re defining a new subroutine or function, the Name Subroutine/Function dialog comes up. Enter a
descriptive name for this subroutine or function and click OK.
• To define a function, enter a single or multi-line defined function according to Visual PRO/5 rules.
• To define a subroutine, enter a unique subroutine label ending with a colon, followed by the Visual PRO/5 code that
implements the subroutine, and finally a RETURN statement.
• To define a non-executing statement, enter a unique statement label ending with a colon, followed by a TABLE,
IOLIST, or DATA verb according to Visual PRO/5 rules. You can refer to this statement from elsewhere in the
program by using the label (TBL=LABEL, IOL=LABEL, or RESTORE LABEL; DREAD data-list).
80
Working with Blocks of Code: Miscellaneous Features
Checking Code Blocks for Errors

To check for errors in the current block of code:
• On the Program menu, select Check for Errors.
• On the toolbar, click the Check for Errors button.
2 One of the following dialogs is displayed:
• If no errors are found in the current block of code, the Check for Errors dialog is displayed with the message “No
errors found.”
• If one or more errors are found in the current block of code, the “Error List” dialog is displayed with a list of error
messages, showing the relative line number within the current block for each error.
3 Select one of the errors from the list, then press the Close button. Input focus is transferred to the Edit Code
window. The error line will be highlighted.
The Build Program function from the Program menu also checks for errors, but it only reports one error at a time. The
error checking included with the Build Program function is more comprehensive, because it is able to examine the
entire program rather than just a line of code at a time.
There is a parameter in the gb.ini file called check_syntax. If this parameter is set to Yes, GUIBuilder checks each
block of code for errors as it is saved to the .gbf file. In any errors are found, the “Syntax Errors dialog will be displayed
with the warning message “This code has syntax errors. (Note: The check_syntax function is set to No by default; to
enable it, edit the gb.ini file.)
Deleting Code Blocks

To delete the current block of code, do the following:
1 Display the code block to be deleted, then do one of the following:
• On the Program menu, select Delete Code.
• On the toolbar, click the Delete Current Code Block button.
2 The Confirm Delete Command dialog appears, requesting confirmation of the deletion. Click Yes to confirm the
deletion or No to cancel the deletion.
Getting External Code

To load an external program or text file, do the following:
• On the Program menu, select Get External Code.
• On the toolbar, click the Get External Code button.
2 The Open Visual PRO/5 Program or Source File dialog appears. Enter the name of a text file or a tokenized
Visual PRO/5 program.
• If you enter the name of a text file, it is loaded into the View Window and input focus is transferred to the View
Window.
• If you enter the name of a Visual PRO/5 program file, the following processing takes place:
a In a temporary copy of the program, all line number references are converted to line labels, and line labels are
created as necessary.
b The temporary copy of the program is listed to a text file using the lister parameter from the gb.ini file. This will
usually be pro5lst.exe.
c The listed version of the Visual PRO/5 program file is loaded into the View Window and input focus is
transferred to the View Window.
3 Now that the program listing is in the View Window, you can do the following:
81
• To navigate within the program listing, use the PGUP/PGDN keys or the up/down arrow keys.
• To copy portions of the program listing to the Edit Code window, do the following:
a Select one or more lines.
b Copy the selected lines to the clipboard using the Copy command from the Edit menu.
c Switch back to the Edit Code window by selecting Window 0 from the Window menu or by clicking on the
Toggle Window tool button.
d And finally, select the Paste command from the Edit menu. You can toggle back and forth between the Edit
Window (Window 0) and the View Window (Window 1) using the Window 0 and Window 1 selections on the
Window menu or by clicking on the Toggle Window tool button. The program listing remains in the View
Window (Window 1) until the next time you select one of the following functions:
• Get External Code from the Program menu.
• View Program from the Program menu.
• Read Me from the Help menu.
Using an External Editor in GUIBuilder

The default behavior for GUIBuilder is to allow editing in the “Edit Code window. To use an external text editor, do the
following:
1 Before starting GUIBuilder, ensure that the "editor=" line in the gb.ini file points to the specified external editor.
2 When GUIBuilder is started and a code block is specified, the Invoke External Editor tool button and External
Editor in the View menu are enabled.
3 Operating either the tool button or the menu item will cause GUIBuilder to disable the "Edit Code" window, write the
current code block to a temporary file, and invoke the editor to edit the block of code in the temporary file.
4 Save this temporary file in ASCII format. LF or CR/LF line terminators are supported.
5 When you exit the external editor, GUIBuilder inserts the modified code block into the .gbf file.
Because .gbf files are in ASCII format, they can be edited with any editor at any time, but it is highly recommended that
they only be edited one block at a time through GUIBuilder. Although .gbf files include BBx source code, they are not
source files and they have their own format. If a GUIBuilder file's formatting is lost or damaged, it may become totally
unusable or lead to unpredictable results.
Pulling it all Together: The Completed Program
Checking Resources
To check a GUIBuilder (.gbf) file against the corresponding resource file, do the following:
• On the Program menu, select Check Resource.
• On the toolbar, click the Check Resource button.
2 If no errors are found, the following message is displayed: “This GUIBuilder file is consistent with resource file
‘filename’. No errors found. If any errors are found in the resource file, the Resource File Error dialog is displayed,
with one of the following messages:
Corruption Type Message(s)
Resource file is corrupt. Missing [Program] block.
Multiple [Init] blocks.
Multiple [EOJ] blocks.
Missing ‘Program Name’ variable.
Missing ‘Resource File’ variable.
Invalid Event header: [Event…]
Error in program _qres, Enumerate_Res_Forms, using resource file filename.
Error in program _qres, Enumerate_Res_Child_Windows, using resource file
82
filename.
Error in program _qres, Enumerate_Res_Controls, using resource file
filename.
Resource file is corrupt. or unavailable. Couldn’t open resource file ‘filename’.
The .gbf file refers to data structures Window ID X no longer exists in the resource file.
that no longer exist in the resource file:
Control ID X no longer exists on window ID Y.
Event Code X is not available for control ID Y on window ID Z.
3 Along with one of the above messages, GUIBuilder asks “Delete n event handler routine(s) from the .gbf file? Do
one of the following:
• To delete the routine(s) from the .gbf file, select Yes.
• To retain the routine(s) in the .gbf file, select No.
• To stop the resource checking process, select Cancel.
Setting Program Options

When a .gbf file is created, GUIBuilder provides the capability to specify options for the program to be generated. These
options can be modified as follows:
1 On the Program menu, select Program Options.
2 The Program Options dialog appears, which allows you to define the following options for the program to be
created:
• To specify a PREFIX file search path, enter the path into the Enter search PREFIX field.
• To specify the number of digits of numeric precision, enter the desired value (acceptable range is -1 to 16) into the
Enter precision field.
• To specify the number of pages to use for a minimum memory check, enter the number into the Enter pages for
minimum memory check field.
• To specify which forms to display upon startup of the program, click one of the following buttons: Show all form(s) at
program startup, Show only the first form and program startup, or Do not show any forms at program startup
buttons.
• To include remarks in the program, click the Include remarks in tokenized program check box.
• To include a message that appears near the beginning of the program code, enter a text string into the Copyright
Message field.
3 Click OK to dismiss the Program Options dialog.
Building Programs in GUIBuilder

To build a program, do the following:
• On the Program menu, select Build Program.
• On the toolbar, click the Build Program button.
2 The Save Program As dialog appears. Enter the name of the tokenized program. If the program already exists,
the “Save Program As warning dialog is displayed, with the message “Program already exists. Delete existing file?
Select Yes to go ahead and delete the existing file, or No to enter a different program name.
3 The complete program is assembled into a source file according to the rules described in the
gb_func::gb__build_program routine.
4 The generated source file is tokenized (compiled) using the program identified by the tokenizer parameter from the
gb.ini file (usually pro5cpl.exe).
• If any errors are detected by the tokenizer, the “Build Program Error dialog is displayed, with the message “Compiler
reported an error in line N of routine X: error-message. Click the OK button to acknowledge the message. GUIBuilder
calls up the routine with the error and positions the cursor on the line with the error.
• If no errors are detected by the tokenizer, the “GUIBuilder dialog is displayed, with the message “Program
programname built successfully. Press the OK button to acknowledge this message.
83
Viewing GUIBuilder Programs
To view the program, do the following:
• On the Program menu, select View Program.
• On the toolbar, click the View Program button.
2 If the program needs to be rebuilt, the Build Program process is invoked at this point.
3 When the program has been built successfully, the program source listing is loaded into the View Window. Use
the PGUP/PGDN and up/down arrow keys to navigate within the program listing.
4 You can toggle back and forth between the Edit Window (Window 0) and the View Window (Window 1) using the
Window 0 and Window 1 selections on the Window menu or by clicking on the Toggle Window tool button. The
program listing remains in the View Window (Window 1) until the next time you select one of the following
functions:
• Get External Code from the Program menu.
• View Program from the Program menu.
• Read Me from the Help menu.
Running GUIBuilder Programs

To run the tokenized program, do the following:
• On the Program menu, select Run Program.
• On the toolbar, click the Run Program button.
2 If the program needs to be rebuilt, the Build Program process is invoked at this point.
3 When the program has been built successfully, GUIBuilder runs it in a secondary copy of the Visual PRO/5
interpreter, using the interpreter parameter from the gb.ini file. By default, when the generated program
terminates, it exits to the Visual PRO/5 console; enter BYE or RELEASE to return to GUIBuilder.
Generated Program Variables

This is a list of the variables and functions available to developers in programs generated by GUIBuilder.
The following variables are available in all parts of the program. including initialization and EOJ:
__arg$ Argument passed in a CALL statement and retrieved in the ENTER line of the generated
program.
__args Number of values passed in gb__arg$. gb__args will be -1 if gb__arg$ is a simple variable
(without a template), 0 if the program was run (or if the program was called and gb__arg$
was not passed), or a positive integer to indicate the number of fields defined in the string
template associated with gb__arg$.
__sysgui$ Name of the SYSGUI alias, taken from the config.bbx file.
__sysgui Channel on which the SYSGUI device (gb__sysgui$) is opened.
__sysprint$ Name of the SYSPRINT alias, if one was defined in config.bbx. If no SYSPRINT device
exists in config.bbx, then gb__sysprint$ will be null ("").
__win_id$ Initialization: The first window ID found in the resource file.
End of Job: The last window ID referenced within the Event Loop.
__win$ Template associated with this string contains each of the form and window names defined in
this program’s resource file; the value of each field is the context of the given form or
window. For example, if a form is named “Main and its context is 0, then gb__win.main will
be 0.
The following variables are available only within the event loop:
84
gb__event$ Event record. It is dimensioned using TMPL(gb__sysgui). The event record is documented
in the Visual PRO/5 GUI Guide.
gb__notice$ Notice string for the current Notify event. This string is only meaningful if gb__event.code$
is "N. It will be dimensioned with the correct template based on the notify type.
gb__win_id$ Current window ID. For example, if the current window is a top-level form with an ID of 100,
then gb__win_id$ is "100. If the current window is a child window with an ID of 1001 on a
top-level form of 100, then gb__win_id$ is "100.1001.Child windows can be nested to an
arbitrary level, so it's possible to see gb__win_id$ as "100.1111.2222.3333.
gb__eoj This variable can be set to any non-zero value to force termination of the event loop.
Both gb__event$ and gb__notice$ are set at the top of the event loop:
dim gb__event$:tmpl(gb__sysgui)
gb__event=len(gb__event$)
dim gb__generic$:noticetpl(0,0)
gb__eoj=0
repeat
read record (gb__sysgui,siz=gb__event,err=gb__event_loop_end)gb__event$
if gb__event.code$="N" then
: gb__generic$=notice(gb__sysgui,gb__event.x%);
: dim gb__notice$:noticetpl(gb__generic.objtype%,gb__event.flags%);
: gb__notice$=gb__generic$
body of the event loop
until gb__eoj
Note that all variables defined by the framework start with gb__ (with two underscores). Similarly, all functions defined
by the framework start with fngb__.
Preparing GUIBuilder Programs for End Users

Note the program and resource file are required for each generated program; also ship the .gbf files if you intend to do
on-site development, in which case, GUIBuilder must be installed at the end user site. The _qres program must always
exist on the end user site.
Description
Filename
program.brc or Resource file – must be created first, using ResBuilder (.brc), ResEdit (.brf), or
program.brf ResCompiler (.arc compiled to .brc). Required at runtime.
program.gbf Initially created based on program.brc; modified by the developer using GUIBuilder.
program.src Generated from program.brc, program.gbf, gb_*.cod, and GUIBuilder internal rules.
program.bbx Tokenized from program.src using pro5cpl.exe. Note the user can override the
extension by changing the program_extension= parameter in gb.ini. Required at
runtime.
program.err Temporary, created and erased when building program.
_qres Query Resource Functions (Utility Program). Required at runtime.
Using Other Programs from the GUIBuilder Workbench
Invoking ResBuilder from GUIBuilder

To invoke ResBuilder, do one of the following:
• On the Tools menu, select ResBuilder.
85
• On the toolbar, click the ResBuilder button.
GUIBuilder is suspended, and ResBuilder starts. The resource file is closed so it can be used in ResBuilder.
Upon the close of ResBuilder, GUIBuilder becomes enabled, and checks the current .gbf file against its corresponding
resource file.
Invoking DDBuilder from GUIBuilder

To invoke DDBuilder, do one of the following:
• On the Tools menu, select DDBuilder.
• On the toolbar, click the DDBuilder button.
DDBuilder is then started. You can toggle between GUIBuilder and DDBuilder via <Ctrl>+<Tab>.
Invoking a Visual PRO/5 Console Window in GUIBuilder

To invoke an additional Visual PRO/5 console window, do one of the following:
• On the Tools menu, select Visual PRO/5.
• On the toolbar, click the Visual PRO/5 button.
An additional Visual PRO/5 console window is then started. You can toggle between GUIBuilder and Visual Pro/5 via
<Ctrl>+<Tab>.
Helper Functions
Functions for Reading and Updating the Screen

These three functions enable you to work with controls using the names assigned in ResBuilder (as opposed to the
numeric control IDs), which provides a simplified way to manipulate graphical controls.
Function Description
fngb__template$() Returns a string template that describes the controls on a specified window.
fngb__get_screen$() Copies the value of each of the controls from the screen (window) to the
template record.
fngb__put_screen$() Updates each of the controls on the screen (window) based on the values
from the template record.
These functions provide all of the functionality you’ll need for most situations, but in some cases, you’ll need to use
more precise mnemonics, as well as the CTRL() and SENDMSG() functions. For example, these functions read or write
complete lists from or to list button and list box controls. To determine the currently selected item in a list box or list
button, use the CTRL() function; to change the currently selected item or items, use one of the ‘LISTSEL’, ‘LISTMSEL’,
or ‘LISTUNSEL’ mnemonics.
The following table shows how each control type maps to the template data structure:
Control Type Template Value Description Get Value: Put Value:
Format
Screen -> String String -> Screen
Push Button (11) C(1*=0) N/A N/A N/A
Radio Button (12) N(1*=0) 0=unchecked dec(ctrl(gb__sysgui, ‘CHECK’
1=checked gb__ctl_id,2))
Check Box (13) N(1*=0) 0=unchecked dec(ctrl(gb__sysgui, ‘CHECK’ or ‘UNCHECK’
Horizontal Scrollbar N(4*=0) scrollbar position dec(ctrl(gb__sysgui, ‘SCROLLPOS’(gb__ctl_
(14) based on the id,int)
‘scrollrange’ gb__ctl_id,2))
Vertical Scrollbar N(4*=0) scrollbar position dec(ctrl(gb__sysgui, ‘SCROLLPOS’(gb__ctl_

(15) based on the id,int)
‘scrollrange’ gb__ctl_id,2))
86
Edit (16) C(64*=0) Text value of the ctrl(gb__sysgui, ‘TITLE’
control.
gb__ctl_id,1)
Static Text (17) C(64*=0) Text value of the ctrl(gb__sysgui, ‘TITLE’
control.
gb__ctl_id,1)
List Box (18) C(255*=0) Complete list, with ctrl(gb__sysgui, ‘LISTSUSPEND’
items delimited by
line feeds, followed gb__ctl_id,7) ‘LISTCLR’
by list selections, ‘LISTADD’
delimited by $ff$.
See below for more ‘LISTRESUME’
information.
List Button (19) C(255*=0) Complete list, with ctrl(gb__sysgui, ‘LISTSUSPEND’
items delimited by
line feeds, followed gb__ctl_id,7) ‘LISTCLR’
by list selections, ‘LISTADD’
delimited by $ff$.
See below for more ‘LISTRESUME’
information.
List Edit (20) C(64*=0) Text value of the ctrl(gb__sysgui, ‘TITLE’
edit portion of the
control. gb__ctl_id,1)
Group Box (21) C(1*=0) N/A N/A N/A

Custom Edit (22) C(64*=0) Text value of the ctrl(gb__sysgui, ‘TITLE’
control.
gb__ctl_id,7)
Menu Item (100) N(1*=0) 0=unchecked dec(ctrl(gb__sysgui, ‘CHECK’ or ‘UNCHECK’
Checkable Menu N(1*=0) 0=unchecked dec(ctrl(gb__sysgui, ‘CHECK’ or ‘UNCHECK’
Item (101)
Status Bar (102) C(64*=0) Text value of the ctrl(gb__sysgui, ‘TITLE’
control.
gb__ctl_id,1)
Tool Button (103) N(1*=0) 0=unchecked dec(ctrl(gb__sysgui, ‘CHECK’ or ‘UNCHECK’
INPUTE (104) C(64*=0) Text value of the ctrl(gb__sysgui, ‘TITLE’
control.
gb__ctl_id,1)
INPUTN (105) C(16*=0) Text value of the ctrl(gb__sysgui, ‘TITLE’
control (use NUM()
to convert to gb__ctl_id,1)
numeric).
Tab (106) N(4*=0) Currently selected dec(sendmsg sendmsg(gb__sysgui,
tab index.
(gb__sysgui, gb__ctl_id,34,0,$$)
gb__ctl_id,29,0,$$))
Grid (107) C(1*=0) N/A N/A N/A
Line (108) C(1*=0) N/A N/A N/A
Image (109) C(1*=0) N/A N/A N/A
Values can be passed to list boxes and list buttons in a string that contains the complete list of items, delimited by line
feeds. The following would load the items “One, “Two, and “Three in a list control:
win.list_btn$=One+$0a$+Two+$0a$+Three+$0a$
In the GUIBuilder version that is shipped in Visual PRO/5 Rev. 2.20 and above, it is also possible to specify which item
or items should be highlighted by appending string numerics to the list, delimited by $ff$ characters. Passing the
87
following string with fngb__put_screen would cause the first and third items to be highlighted (note that item numbering
is zero-based).
win.list_btn$=One+$0a$+Two+$0a$+Three+$0a$+0+$ff$+2
Likewise, after using fngb__get_screen to query a list control, the highlighted item or items will be indicated with a list of
string numerics delimited by $ff$ characters.
The highlighting functionality is dependent on $ff$ characters not being used in the list text. If this character does occur
in the list, unpredictable results will occur.
fngb__template$(gb__win_id$) - Get String Template Given Window ID
Description
This function returns a string template given a window ID. The string template contains a field for each control on the
specified form or window, with the data types and meanings listed in the table above. The following example is based on
the “Hello program described in “Getting Started:
>dim Hello$:fngb__template$(gb__win_id$)
>print fattr(Hello$,"")
STATUS
PUSH_ME
MESSAGE
>print fattr(Hello$)
STATUS:C(64*=0):ID=1 TYPE=102 X=0 Y=178 W=320 H=22:,
PUSH_ME:C(1*=0):ID=1001 TYPE=11 X=110 Y=50 W=90 H=25:,
MESSAGE:C(64*=0):ID=1002 TYPE=17 X=50 Y=110 W=200 H=25:
Field names are assigned based on the names from ResBuilder. If the name in ResBuilder is blank, the template field
name will be "ID" + str(ctl_id). When defining the template, if GUIBuilder finds a field name that duplicates one already in
the template, it adds "_"+str(ctl_id) to the end of the second field name to make it unique. If the field name in ResBuilder
contains any characters that are illegal in Visual PRO/5 identifiers (e.g. spaces), they will be converted to underscores.
For example, a ResBuilder field name of "Over Credit Limit?" would appear in the template as "OVER_CREDIT_LIMIT.
The characters " " and "?" are converted to underscores, and leading and trailing underscores are removed.
Field Description
ID Control ID assigned in ResBuilder.
You can retrieve an ID value from the template by using fattr(rec$,fld$,ID). For example,
fattr(Hello$,Message,ID) would return “1002.
TYPE Numeric field type as defined in the above table.
You can retrieve a TYPE value from the template by using fattr(rec$,fld$,TYPE). For example,
fattr(Hello$,Message,TYPE) would return “17, which indicates that this field is a static text
control.
X, Y, W, and H Location of control on the screen (X=horizontal pixel location, Y=vertical pixel location, W=width
in pixels, and H=height in pixels).
You can retrieve any of these values from the template by using fattr(rec$,fld$,parameter). For
example, fattr(Hello$,Message,X) would return “50, which indicates that the Message field starts
at horizontal pixel position 50.
fngb__get_screen$(gb__win_id$,screen$) - Copy Control value from Screen to

Template Record
Description
This function retrieves data from the screen/window into a string variable you dimensioned using the fngb__template$()
function. Here’s an example from the “Hello program:
>Hello$=fngb__get_screen$(gb__win_id$,Hello$)
>print Hello.Status$
>print Hello.Push_Me$
88
>print Hello.Message$
Hello from GUIBuilder!
fngb__put_screen$(gb__win_id$,screen$) - Update Screen Control Values from

Template Record
Description
This function takes data from the string variable you dimensioned using the fngb__template$() function and updates it to
the screen/window. Here’s an example from the “Hello program:
>Hello.Status$="This is a status message"
>Hello.Message$="Hello, GUIBuilder"
>Hello$=fngb__put_screen$(gb__win_id$,Hello$)
Functions for Setting Screen Focus

These functions are used to set input focus to a particular window/screen, and optionally to a particular control.
fngb__focus_win_id - Set Focus to a Given Window ID.

Usage
gb__context=fngb__focus_win_id(gb__win_id$)
Description
This function sets focus to a given window ID.
fngb__focus_ctl_id - Set Focus to A Given Window ID and Control ID

Usage
gb__context=fngb__focus_ctl_id(gb__win_id$,gb__ctl_id)
Description
Sets focus to a given window ID and control ID.
fngb__focus_ctl_name - Set Focus to A Given Window ID and Control Name

Usage
gb__context=fngb__focus_ctl_name(gb__win_id$,"Push_Me")
Description
Sets focus to a given window ID and control name.
Functions for Retrieving Window Information

fngb__focus_win_id - Get Window ID from Current Context.
Usage
gb__win_id$=fngb__win_id$(gb__event.context)
Description
This function gets the window ID from the current context.
fngb__context - Get Context from Window ID

Usage
gb__context=fngb__context(gb__win_id$)
Description
This function gets the context the from window ID
89
fngb__focus_winl_info - Get Window Information Block for a Given Window ID.
Usage
gb__win_info$=fngb__win_info$(gb__win_id$)
Description
This function gets the Window Information Block for a given window ID.
Window Information Block Template
dim gb__win_info$:"class:u(1),type:u(1),hidden:u(1),disabled:u(1),"
: +"context:u(2),eventmask:u(4),flags:u(4),focus:u(2),"
: +"x:i(2),y:i(2),w:u(2),h:u(2),title:c(16*=)"
The window information block is constructed using the following Visual PRO/5 functions:
gb__win_info$=ctrl(gb__sysgui,0,4,gb__context)
: +ctrl(gb__sysgui,0,8,gb__context)
: +bin(gb__context,2)
: +sendmsg(gb__sysgui,0,21,0,$$,gb__context)
: +sendmsg(gb__sysgui,0,22,0,$$,gb__context)
gb_func Code Library
fngb__get_code (gb_func) - Retrieve .gbf String Data or Chunks of Code

Syntax
def fngb__get_code(gb__win_id$,gb__ctl_id$,gb__event_code$,gb__gbf_data$)
Description
This function is used to retrieve a single event handler routine, all event handler routines for a given window ID and
control ID or window ID only, Initialization or End of Job routines, a single user-defined subroutine/function, all user-
defined subroutines/functions, or variables from the [Program] block of the .gbf file.
In the following routines, where n is the number of lines in a routine, remember that these lines might be made up
entirely of spaces, tabs, and new line characters, meaning that they're effectively empty. To tell if there is any code in
the returned string, use the following code:
is_code = sgn(len(cvs(cvs(gb__sub_code$,16),3)))
is_code = sgn(len(cvs(cvs(gb__sub_code$[i],16),3)))
For convenience, the following variable equivalents are defined:
gb__sub_name$ = gb__sub_name$[1]
gb__sub_code$ = gb__sub_code$[1]
gb__sub_info$ = gb__sub_info$[1]
To Get Use Notes
Single event n = fngb__get_code("win-id", n = 1 if the routine was found, 0 if not found.
handler routine
"ctl-id","event-code", gb__sub_name$ - Name of event handler
subroutine.
gb__gbf_data$)
gb__sub_code$ - Body of event handler
subroutine.
gb__sub_info$ - Contains window ID + $0a$ +
control ID + $0a$ + event code + $0a$
90
All event handler n = fngb__get_code("win-id", n = Number of routines found.
routines for a
given Window ID "ctl-id","",gb__gbf_data$) gb__sub_name$[1..n] - Names of event handler
and Control ID subroutines.
gb__sub_code$[1..n] - Bodies of event handler
subroutines.
gb__sub_info$[1..n] - Contain window ID + $0a$
+ control ID + $0a$ + event code + $0a$
All event handler n = fngb__get_code("win-id", n = Number of routines found.

routines for a
given Window ID ,"","",gb__gbf_data$) gb__sub_name$[1..n] - Names of event handler
subroutines.
gb__sub_code$[1..n] - Bodies of event handler
subroutines.
gb__sub_info$[1..n] - Contain window ID + $0a$
+ control ID + $0a$ + event code + $0a$
End of Job or n = fngb__get_code("", n = 0 if the routine wasn’t found, or the number

Initialization of lines in gb__sub_code$ if it was found.
routine "Init","",gb__gbf_data$)
gb__sub_name$ - Name of the special routine.
n = fngb__get_code("",
gb__sub_code$ - Body of the special routine.
"EOJ","",gb__gbf_data$)
Single user- n = fngb__get_code("", n = 0 if the routine wasn’t found, or the number

defined of lines in gb__sub_code$ if it was found.
subroutine or "Function","funcname",
function gb__sub_name$ - Name of the subroutine or
gb__gbf_data$) function.
gb__sub_code$ - Body of the subroutine or
function.
All user-defined n = fngb__get_code("", n = Number of functions found.

subroutines or
functions "Function","", gb__sub_name$[1..n] - Names of subroutines or
functions.
gb__gbf_data$)
gb__sub_code$[1..n] - Bodies of subroutines or
functions.
[Program] block n = fngb__get_code("", n = 0 if the variable wasn’t found, 1 if it was

variable found.
"Program","varname",
gb__sub_name$ - Name of variable.
gb__gbf_data$)
gb__sub_code$ - Value of variable.
fngb__put_code - Insert Chunks of Code or Data into a .gbf String

Syntax
def fngb__put_code(gb__win_id$,gb__ctl_id$,gb__event_code$,
gb__gbf_data$,gb__sub_name$,gb__sub_code$)
91
Description
This function is used to put single event handler routines, special routines, user-defined suboutines/functions, and
[Program] variable/value lines into a .gbf file.
To Put Use Notes
n = fngb__put_code
Single event ("win-id","ctl-id", n = 1 if the routine was added, 0 if updated.
handler routine in "event-code",
the .gbf file All "." in gb__sub_name$ will be converted to
gb__gbf_data$, "_".
sub_name$,sub_code$)
This is to handle child window IDs in
If sub_name$="", it will be gb__win_id$; they can be formatted like "1.10",
formatted as follows: "1.10.10", etc.
gb__sub_name$="W"+gb__win_id$;
if num(gb__ctl_id$) then
gb__sub_name$=gb__sub_name$+"_C"+
gb__ctl_id$;
gb__sub_name$=gb__sub_name$+"_"+f
ngb__get_event_label$(gb__event_c
ode$)
n = fngb__put_code("",
Special routine "Init","",gb__gbf_data$, n = 1 if the routine was added, 0 if updated.
(Init, EOJ) into the "",sub_code$)
.gbf file
User-defined "Function","",gb__gbf_data$, n = 1 if the routine was added, 0 if updated.
subroutine or "func-name",sub_code$)
function into the
.gbf file
[Program] "Program","",gb__gbf_data$, n = 1 if the variable was added, 0 if updated.
variable/value line "var-name","var-value")
into the .gbf file
fngb__del_code (gb_func) - Delete .gbf String Data or Chunk of Code

Syntax
def fngb__del_code(gb__win_id$,gb__ctl_id$,gb__event_code$,
gb__gbf_data$,gb__sub_name$)
Description
This function is used to delete event handler routines, Initialization or End of Job routines, user-defined
subroutines/functions, or [Program] variable/value lines from the .gbf file.
To Delete Use Notes
n = fngb__del_code("win-id","ctl-id",
Event handler "event-code",gb__gbf_data$, n = 1 if the routine was deleted, 0 if
routine sub_name$) the routine didn't exist.
n = fngb__del_code("",
Initialization or "Init","",gb__gbf_data$,"") n = 1 if the routine was deleted, 0 if
End of Job the routine didn't exist.
routine
N = fngb__del_code("",
User-defined "Function","",gb__gbf_data$, n = 1 if the subroutine or function
subroutine or "func-name") was deleted, 0 if the subroutine or
function. function didn't exist.
n = fngb__del_code("",
[Program] block "Program","",gb__gbf_data$, n = 1 if the variable was deleted, 0 if
variable or value "var-name") the variable didn't exist.
line
92
gb_func::gb__val_data - Validate a .gbf String
Syntax
call "gb_func::gb__get_file","my.gbf",gb__gbf_data$,"",gb__err$
call "gb_func::gb__val_data",gb__gbf_data$,gb__err,gb__err$
Description
This routine scans the gb__gbf_data$ string, ensuring that there is a [Program] block with at least the variables
"Program Name" and "Resource File", and that there are no more than one each of the "[Init]" and "[EOJ]" blocks.
This function also checks the format of the [Event] headers, according to the following format mask:
[Event Win=int{.int} ID=int Code=char{int{:int}} <EVENT_NAME> (SUBROUTINE_NAME)]
gb__ok=mask("","^\[Event Win=[0-9]+(.[0-9]+)* ID=[0-9]+ “+
: “Code=[A-Za-z0-9]([0-9]+(:[0-9]+)?)? "+
: "<[a-zA-Z0-9_]+> $[A-Za-z0-9_]+$\]$")
The final step is to verify that the [Event] headers are consistent with the windows and controls in the resource file.
Possible Errors
gb__err gb__err$
0 Success.
ERR Unexpected error -- Visual PRO/5 ERR returned.
-1 Missing [Program] block.
-2 Multiple [Init] blocks.
-3 Multiple [EOJ] blocks.
-6 Missing 'Program Name' variable.
-7 Missing 'Resource File' variable.
-9 Invalid [Event] header structure.
-99 Couldn't find resource file.
-98 _qres::Enumerate_Res_Forms Error.
-97 _qres::Enumerate_Res_Child_Windows Error.
-96 _qres::Enumerate_Res_Controls Error.
-100 Formatted string identifying the windows/controls/events that were not in the resource
file:
"win_id:c(8*=0),ctrl_id:c(5*=0),event_id:c(1*=0),code:c(1*=10)"
Window ID will be formatted like "10" or "10.200" or "10.200.200.
Control ID is a simple integer.
Event ID is a single character, optionally followed by an integer qualifier to be tested
against gb__event.flags (e.g. 'f0'). Notify event codes will be formatted with the control
type appended to the event code, i.e., 'N1:20' or 'N3:107'.
Code = 1: Window not in resource file.
Code = 2: Control not in window.
Code = 3: Illegal event code for this control type.
gb_func::gb__get_file - Get Text File into a .gbf String

Syntax
Loading gb__gbf_data$ from the .gbf file:
93
call "gb_func::gb__get_file","my.gbf",gb__gbf_data$,
"",gb__err$
Loading any other file after initializing gb__gbf_data$
call "gb_func::gb__get_file",filename$,gb__file$,
gb__gbf_data$,gb__err$
Note (1): Only line feeds ($0a$) are recognized as line terminators. Any carriage returns ($0d$) in the file are discarded
and will not appear in gb__file$.
Note (2): Variable substitution is done according to the following rules: Anything in the text file formatted like {_variable
name_} will be converted to the value of the variable "variable name" from the [Program] block in gb__gbf_data$. This is
completely open-ended; users are free to define their own [Program] variables. For example, if the following appears in
the [Program] block of gb__gbf_data$:
Copyright = Copyright (C) 1998 My Company Name Here
Assuming the following appears as a line in the program:
REM ' {_Copyright_}
The final generated program line will look like this:
REM ' Copyright (C) 1998 My Company Name Here
To turn off variable substitution, pass gb__gbf_data$ as "".
Note (3): gb__err$ will be null for success; non-null indicates some error occurred, typically on opening the file.
gb_func::gb__build_program - Build and Tokenize Program using .gbf

Data
Syntax
call "gb_func::gb__get_file","my.gbf",gb__gbf_data$,
"",gb__err$
call "gb_func::gb__build_program",gb__gbf_data$,"pro5cpl",
"bbx",gb__err,gb__err$
Description
This routine is used to build and tokenize a program using data in the .gbf file.
This section describes the program format, tokenization, error handling, and compilation errors for the function used to
build and tokenize the program using .gbf data.
Program Format
The program is generated in the following 12 steps:
1 The header block identifies the program, the resource file used to create the program, and copyright information.
An ENTER line is generated to allow a single string variable to be optionally passed to the program. For each of
the following, code is generated only if the corresponding variable exists in the [Program] section of the .gbf file:
• Show Forms = 0 or None: Initially hide all forms.
• Show Forms = 1 or First: Initially hide all forms except the first one.
• Show Forms = 2 or All: Initially show all forms.
rem ' Program Name: C:/basis/vpro5/gb/sample.src
rem ' Resource File: sample.brc
rem ' Generated by GUIBuilder (June 15, 1998 @ 13:08:39)
rem ' Portions Copyright (C) 1997-1998 BASIS International Ltd.
seterr gb__no_arg
enter gb__arg$; gb__args=-1,gb__args=pos($0a$=fattr(gb__arg$,$$),1,0)
94
gb__no_arg:
seterr 0
2 Merge gb_ini.cod (standard initialization block). This file is merged into the generated program immediately after
the header block. It contains initialization code and a series of data management functions. The initialization code
confirms that the program is running under an interpreter that will support its GUI features, then it sets
GB__SYSGUI$ to the first SYSGUI device found in the config.bbx file and GB__SYSPRINT$ to the first
SYSPRINT device (if any) found in the config.bbx file. GB__SYSGUI$ is opened on channel GB__SYSGUI; if no
SYSGUI device is found, the program terminates. After this basic initialization, the resource file is opened, and all
forms from it are displayed (some might be hidden, based on the setting of the gb__show_forms parameter from
the .gbf file).
3 Merge in the user-defined initialization code, from the [Init] section in the .gbf file. This will typically do things like
DIM record structures, open files, and set global variables. If the program uses grid and/or tab controls, some setup
is typically required and would also go in this section. If the program will be using the printer, you can open it here;
the printer device is GB__SYSPRINT$ (which will be set to “ if no printer alias was found in config.bbx).
4 Generate event loop based on [Event] blocks. The following is a sample of the generated event loop code.
rem ' ---------------------------------------------------------------
rem ' Event Loop
rem ' ---------------------------------------------------------------
gb__windows=3; rem ' includes child windows
This tells us how many windows there are in total.
Note gb__forms tells us the number of top-level windows.
dim gb__closed[gb__windows]
This simply tells us that all windows/forms are initially open.
gb__eoj=0
repeat
readrecord(gb__sysgui,siz=gb__event,err=gb__event_loop_end)gb__event$
The following code will retrieve the Notice string into gb__notice$, formatted with the appropriate template. The
gb__notice$ variable is only meaningful when gb__event.code$=N:
if gb__event.code$="N" then
: gb__generic$=notice(gb__sysgui,gb__event.x%);
: dim gb__notice$:noticetpl(gb__generic.objtype%,gb__event.flags%);
: gb__notice$=gb__generic$
The following block of code returns the window ID given the Event Context. The reverse function is also available --
to return the Context Number for a given window ID, use: gb__context=fngb__context("10.10")
rem ' Get Window ID from Event Context
gb__win_id$=fngb__win_id$(gb__event.context)
if gb__win_id$=$$ then
break
There will be one of these “while blocks for each form or child window in the resource file. This is where we decide
which event subroutine needs to be called. Note for "X" events, we also track the fact that the window has been
closed; when all windows have been closed, the event loop terminates.
rem ' Handle events for window ID 10
while gb__win_id$="10"
if gb__event.id=1 and gb__event.code$="B" then
: gosub W10_C1_PUSH_BUTTON;
: break
if gb__event.id=1000 and gb__event.code$=f and gb__event.flags=0 then
gosub W10__C1000_LOST_FOCUS;
95
break
if gb__event.code$="X" then
: gosub W10_WIN_CLOSE;
: gb__closed[1]=1;
: break
break; rem ' catch unhandled events
wend; rem ' End of window ID 10
When all windows are closed, the control variable 'gb__eoj' will evaluate to 1, causing the event loop to terminate.
Note the developer has the option to force this condition (terminating the event loop) by setting gb__eoj=1 at any
time.
if !(gb__eoj) then
: gb__eoj=1;
: for gb__window=1 to gb__windows;
: gb__eoj=(gb__eoj and gb__closed[gb__window]);
: next gb__window
The event loop terminates when gb__eoj is non-zero:
until gb__eoj
gb__event_loop_end: rem ---------------------------------------
5 Merge in user-defined code from .gbf [EOJ] block, if any. You would close files and do any other required cleanup
here.
6 Merge gb_eoj.cod (standard EOJ/cleanup block). Destroy all contexts (windows) and close gb__sysgui. This is the
standard end-of-job routine. It removes all forms from the screen, closes SYSGUI, then stops or exits.
rem gb_eoj.cod - GUIBuilder generated programs: standard EOJ code
rem Copyright (C) 1998 BASIS International Ltd. All Rights Reserved.
rem ***** P R O G R A M E X I T **************************************
gb__eoj:
if gb__forms and gb__sysgui then
: for gb__temp=1 to gb__forms;
: print (gb__sysgui)'context'(gb__form_context[gb__temp]),'destroy'(0);
: next gb__temp
if gb__sysgui then
: close (gb__sysgui)
if tcb(13) then
: exit
: else
: stop
7 Merge in gb_err.cod (standard error handler). The error routine displays a message indicating that a particular error
occurred at some line number and gives the user the option to retry or end the program. You can insert your own
error handler here.
rem gb_err.cod - GUIBuilder generated programs: standard error handler
rem ***** E R R O R H A N D L E R ************************************
gb__err:
gb__temp=msgbox(errmes(err)+" ("+str(err)+")"+
: " occurred at line "+str(tcb(5))+
96
: " in program "+pgm(-2),5+48,"Error handler")
if gb__temp=4 then
: retry
: else
: goto gb__eoj
8 Merge in gb_esc.cod (standard escape handler). If the user presses the break key (Ctrl-C or Break), this routine
displays a message indicating that an escape has been detected. The user is given the option to end the program
or return to where the escape was detected to continue running the program.
rem gb_esc.cod - GUIBuilder generated programs: standard escape handler
rem ***** E S C A P E H A N D L E R ***********************************
gb__esc:
gb__temp=msgbox("An ESCAPE has been detected. Do you want to end "+
: "this program?",4+32+256,"ESCAPE handler")
if gb__temp=7 then
: return
: else
: goto gb__eoj
9 User-defined functions/subroutines defined in the .gbf file are merged into the generated program at this point.
Each one will start with a simple comment block giving the subroutine/function name.
10 The event-handler routines from the .gbf file are merged into the generated program at this point. Each one will
start with a comment block giving the details of the window, control, and event for which this event handler was
defined. The subroutine label and final RETURN statement are also generated; the body of the event handler code
is merged in between the subroutine label and the RETURN statement.
11 If there are any standard functions or subroutines that you typically include in all or most of your programs (for
example, date formatting or editing), you should put them in this file. The contents of gb_std.cod are merged in to
the end of all programs generated by GUIBuilder.
12 Generate the "END" statement.
Tokenization
The generated program is tokenized with the tokenizer specified in the argument list (in this example, “pro5cpl). The .gbf
variable 'Remarks = [y|n]' is used to determine whether comments will appear in the tokenized file. Use 'Remarks = No'
to cause remarks to be skipped. The default is 'Remarks = Yes'. The extension of the generated program will also be
determined from the argument list; in this case, it’s “bbx.
Error Handling
The following lists the errors listed in gb__err:
gb__err Error Description
0 Success-no errors.
-1 COMMAND.COM Error: Tokenizer couldn't find workfile.
-2 COMMAND.COM Error: Couldn't find tokenizer.
1..255 Unexpected error -- Visual PRO/5 ERR.
1000 Compilation errors reported in gb__err$.
1001 Program Name variable missing from .gbf file.
1002 Resource File variable missing from .gbf file.
1003 Couldn't create work file.
1004 Couldn't open resource file.
1010 Error detected within _qres::Enumerate_Res_Forms.
97
1011 Error detected within _qres::Enumerate_Res_Child_Windows.
1012 Error detected within _qres::Enumerate_Res_Controls.
pro5cpl Compilation Errors

If gb__err=1000, gb__err$ will list the compilation error(s) in the following format:
"type:c(1*=0),line:n(3*=0),msg:c(16*=0),arg1:c(8*=0),arg2:c(8*=0),arg3:c(8*=0)"
Each error will be reported in a string of this format, terminated by a linefeed. There will be one record for each error.
The number of errors will be equal to: pos($0a$=gb__err$,1,0).
If type="f", the error was in an include file:
• line = error line number within the include file, or 0 to indicate an error opening the file.
• msg = text of error reported by the tokenizer or gb_func::gb__get_file.
• arg1 = include file which caused the problem:
• arg2 = ""
• arg3 = ""
To retrieve the block of code (include file) with the error:
call "gb_func::gb__get_file",arg1$,gb__string$,gb__gbf_data$,gb__err$
If type="g", the error was in user-defined code in the gb__gbf_data$:

• line = error line number within the .gbf code chunk.
• msg = text of error reported by gb__bbxcpl$.
• arg1 = First argument to be passed to fngb__get_code.
• arg2 = Second argument to be passed to fngb__get_code.
• arg3 = Third argument to be passed to fngb__get_code.
To retrieve the block of code with the error:
n = fngb__get_code(arg1,arg2,arg3,gb__gbf_data$)
gb__sub_name$ is returned as the name of the event-handler subroutine.
gb__sub_code$ is returned as the body of the event-handler subroutine.
If type="i", the error was in internal (generated) code:
• line = error line number within the generated program source file.
• msg = text of error reported by the tokenizer.
• arg1 = ""
• arg2 = ""
• arg3 = ""
fngb__get_event_desc$ (gb_func) - Get Event Description for a Given

Event Code
Syntax
def fngb__get_event_desc$(gb__event_code$)
Description
This function returns the event description (free-format text) for a given event code. If the event code is invalid or
unknown, “ is returned.
98
fngb__get_event_label$ (gb_func) - Get Event Label for a Given Event
Code
Syntax
def fngb__get_event_name$(gb__event_code$)
Description
This function returns an event label for a given event code. The label can contain up to 16 characters, is uppercase, and
is suitable for inclusion in a Visual PRO/5-format label or variable name. If the event code is invalid or unknown, “ is
returned.
fngb__get_event_list$ (gb_func) - Get Event Codes for a Given Control

Type
Syntax
def fngb__get_event_list$(gb__ctl_type)
Description
This function returns a comma-delimited string of event codes for a given control type. If the control type is invalid or
unknown, “ is returned.
fngb__get_control_desc$ (gb_func) - Get Control Description for a Given

Control Type
Syntax
def fngb__get_control_desc$(gb__ctl_type)
Description
This function returns a control description for a given control type. If the control type is invalid or unknown, “ is returned.
fngb__event_visible (gb_func) - Determine Event Visibility

Syntax
def fngb__event_visible(gb__event_code$,gb__event_mask$)
Description
This function determines whether an event code for a given event mask is visible. It returns 0 if an event will not be
visible, or 1 if the event will be visible. If the argument is invalid or the event code is unknown, -1 is returned.
gb_func::gb__make_gbf - Generate Framework .gbf String

Syntax
call "gb_func::gb__make_gbf",gb__resource$,gb__program$,gb__gbf_data$,
gb__err,gb__err$
Description
This routine generates a framework gb__gbf_data$ (.gbf file information) based on the resources (forms/child
windows/controls) found in the resource file gb__resource$, creates [Program] variables "Resource File" and "Program
Name", and generates [Event] blocks for all possible event codes for all controls in the resource file, plus "X" event for
all top-level and child windows.
99
gb_func::gb__get_block - Get Initial Code Block from gb_def.cod File
Syntax
call "gb_func::gb__get_block",gb__event_id$,gb__code_block$,
gb__code_file$,gb__err$
Description
This routine retrieves an initial code block from the gb_def.cod file.
gb__event_id$ - single character identifying an event, optionally followed by an integer qualifier to be tested against
gb__event.flags (e.g. 'f0'). Notify event codes will be formatted with the control type appended to the event code, like
'N1:20' or 'N3:107'.
Pass gb__code_file$ as a variable; don't manipulate it. It will be retained in memory between calls.
gb__code_block$ is returned as the default block of code for this event.
gb__err$ will be returned as non-null if there was a problem.
gb_func::gb__run_program - Run Generated Program

Syntax
call "gb_func::gb__run_program",gb__gbf_data$,gb__err,gb__err$
Description
This routine runs the generated program.
_qres Code Library
_qres::Enumerate_Sysgui_Forms - Get All Forms for a Given SYSGUI

Channel
Syntax
call "_qres::Enumerate_Sysgui_Forms",gb__sysgui,window_list$,status,errmsg$
Description
This routine returns a list of all forms on the SYSGUI channel.
Parameter Description
gb__sysgui The channel that the SYSGUI device is opened on.
Window_list$ Returns a string that contains a list of the existing windows. Each window will have an
entry that contains the window name, the current context, the HTA() of the event mask
and the HTA() of the window flags, in the following format:
"WINDOWNAME1" + $00$ + "3" + $00$ + "FFFFFFFF" + $00$ +
"00000810" + $0A$ +
"WINDOWNAME2" + $00$ + "1" + $00$ + "FFFFFFFF" + $00$ +
"00000810" + $0A$
All fields are terminated with a null and the record is terminated with a $0A$.
Windows with no names will be formatted as follows:
$00$ +"3" + $00$ + "FFFFFFFF" + $00$ + "00000810" + $0A$ +
"WINDOWNAME" + $00$ + "1" + $00$ + "FFFFFFFF" + $00$ +
"00000810" + $0A$
Above, the window on context 3 has no name and the window on context 1 is named
WINDOWNAME.
Status Returns 1 for successful operation and 0 for unsuccessful operation.
100
Errmsg$ In the case of unsuccessful operation, this returns a description of the problem
encountered.
This routine does not check to see if there is enough memory to get the window information (WININFO). An error 31
may result in cases where the window being evaluated is very complex and contains many controls.
_qres::Enumerate_Sysgui_Child_Windows - Get All Child Windows for a

Given Context
Syntax
call "_qres::Enumerate_Sysgui_Child_Windows",gb__sysgui,context_id,
window_list$,status,errmsg$
Description
This routine returns a list of all child windows on the specified context.
Context_id The context of a top level window on which to look for children.
Window_list$ Returns a string that contains a list of the existing child windows. Each window will
have an entry that contains the window name, its window ID with full genealogy (with
the exception of the form ID which is not available at runtime), its context, the HTA() of
the window's event mask, and the HTA() of the window's flags, in the following format:
"WINDOWNAME1" + $00$ + "301" + $00$ + "1" $00$ + "FFFFFFFF" +
$00$ + "00000810" + $0A$ +
"WINDOWNAME2" + $00$ + "301.302" + $00$ + "4" + $00$ +
"FFFFFFFF" + $00$ + "00000810"+ $0A$
All fields are terminated with a null and the record is terminated with a $0A$. In the
above example, WINDOWDOWNAME1 is a child window that has a control ID of 301.
It is a child of the top level window and its context is 1. WINDOWNAME2 is a child
window that has a control ID of 302. It is a child of 301 that is a child of the top level
window. Its context is 4.
Windows with no names will be formatted as follows:
$00$ +"301" + $00$ + "1" + $0A$ + $00$ + "301.302" + $00$ +
"4" + $0A$
Above, the child window with ID 301 is on context 1 and has no name. Its parent is the
top level window. The next child window has an ID of 302, is a child of 301 and is on
context 4.
Status Returns 1 for successful operation and 0 for unsuccessful operation.
encountered.
_qres::Enumerate_Sysgui_Controls - Get All Controls for a Given Context

Syntax
call "_qres::Enumerate_Sysgui_Controls",gb__sysgui,context_id,
control_list$,status,errmsg$
Description
This routine returns a list of all controls on the specified context.
101
context_id The context of a top level window on which the target controls reside.
control_list$ Returns a string that contains a list of all the controls on the specific top level context.
Each control will have an entry that contains the type of control (as specified in
CTRL(4)) Window ID with full genealogy of its parent (excluding the top level Form ID
that is not available at runtime), control name, Control ID, and x, y, w, h. Each control
segment can be interpreted using a template that looks like this:
Temp$="Type:n(2*=0),Window_id:C(16*=0),Name:C(30*=0),Ctl_id:n(3
*=0), x:n(3*=0),y:n(3*=0),w:n(3*=0),h:n(3*=10)"
All fields are terminated with nulls and the height field (h) is terminated with a $0A$.
status Returns 1 for successful operation and 0 for unsuccessful operation.
errmsg$ In the case of unsuccessful operation, this returns a description of the problem
encountered.
_qres::Enumerate_Res_Forms - Get All Forms for a Given Resource

Syntax
call "_qres::Enumerate_Res_Forms",reshandle,resource_list$,
status,errmsg$
Description
This routine returns a list of all forms on a resource.
reshandle The handle that the target resource is opened on.
resource_list$ Returns a string that contains a list of the top level resources contained in the
resource file. Each resource will have an entry that contains the resource name, the
window ID, the HTA() of the event mask, and the HTA() of the form flags. In the
following format:
"RESOURCENAME1" + $00$ + "10" + $00$ + "FFFFFFFF" + $00$ +
"00000810" + $0A$ +
"RESOURCENAME2" + $00$ + "20" + $00$ + "FFFFFFFF" + $00$ +
"00000810"+ $0A$
All fields are terminated with a null and the record is terminated with a $0A$.
encountered.
This routine does not check to see if there is enough memory to get the resource information (RESINFO). An error 31
may result in cases where the resource being evaluated is very complex and contains many controls.
_qres::Enumerate_Res_Child_Windows - Get All Child Windows for a

Given Top Level Window
Syntax
call "_qres::Enumerate_Res_Child_Windows",
reshandle,resource_id,child_list$,status,errmsg$
Description
This routine returns a list of all child windows on a top-level window in a resource.
102
resource_id The ID of a top level window on which to look for children.
child_list$ Returns a string that contains a list of the child windows on the given top level window.
Each window will have an entry that contains the window name, window ID
(genealogy), context (always -1) for compatibility with
Enumerate_Sysgui_Child_Windows, the HTA() of the window's event mask, and the
HTA() of the window's flags, in the following format:
"WINDOWNAME1" + $00$ + "10.20" + $00$ + "-1" + $00$ +
"FFFFFFFF" + $00$ + "00000810" + $0A$ + "WINDOWNAME2" + $00$ +
"10.20.30" + "-1" + $00$ + "FFFFFFFF" + $00$ + "00000810" +
$0A$
All fields are terminated with null and the records is terminated with a $0A$.
The above example shows a child window called WINDOWNAME1 that is control ID
20 on top level window (form) 10 and a child window called WINDOWNAME2 that is
control ID 30 on a child window that is control ID 20 on the top level window (form) 10.
encountered.
This routine does not check to see if there is enough memory to get the window information (RESINFO). An error 31
_qres::Enumerate_Res_Controls - Get All Controls for a Given Form

Syntax
call "_qres::Enumerate_Res_Controls",reshandle,resource_id,
control_list$,status,errmsg$
Description
This routine returns a list of all controls on the specified form in a resource.
Resource_id The ID of a top level window on which the target controls reside.
Child_list$ Returns a string that contains a list of all the controls on the specific top level window.
Each control will have an entry that contains the type of control (as specified in
CTRL(4)), window ID, control name, control ID, and x, y, w, h. Each control segment is
formatted with the following template:
Temp$="Type:n(2*=0),Window_id:c(16*=0),Name:C(30*=0),
Ctl_id:C(3*=0),x:n(3*=0),y:n(3*=0),w:n(3*=0),h:n(3*=10)"
All fields are terminated with null and the height field (h) is terminated with a $0A$.
If the given control has an ID of “2001 and is on a child window that is control ID “200
on the top level window that has a window ID of “10 the Ctl_id field will contain “2001
and the Window_id field will contain the complete genealogy of the controls container,
“10.200.
encountered.
103
Conversions and File Formats
Character-GUI Conversions Using Batch Procedures

Your existing code base is your biggest asset, but it’s also your biggest hurdle in moving to a GUI environment. The
GUIBuilder Visual Programming Environment offers some help with the ability to cut-and-paste code from existing
programs into a new GUI program. But if you have a lot of data entry programs and you’d like to put together a batch
update procedure, you’ll need to step outside of the Visual Programming Environment. If your existing code base and
screen layouts are sufficiently well structured, you might be able to partially automate the conversion process. This is
possible because the components that make up GUIBuilder are implemented as independently callable procedures.
Here’s a very brief overview of the process:
1 Write a program to read your existing screen formats (from screen files or directly from the program source) and
write ASCII Resource files. See “ResCompiler: Another Path to the User Interface Dictionary at
<http://www.basis.com/advantage/mag-v2n1/rescompiler.html>. One way to simplify this process is to create your
ASCII Resource files with the unit of measure defined as “Characters (as opposed to “Pixels or “Semichars).
Because character screens don’t map directly to GUI screens, you’ll need to make some decisions about how to
convert various screen elements. The easiest way to start is to convert static text to TEXT controls, string fields to
INPUTE controls, numeric fields to INPUTN controls, and boxes and lines to GROUPBOX and LINE controls. For a
more complete discussion of this process, see “A New Approach to Going GUI at
<http://www.basis.com/advantage/mag-v1n3/goinggui.html>.
2 Compile each ASCII Resource file (sample.arc) to a Binary Resource file (sample.brc) using the ResCompiler
program (rescomp.exe).
3 Generate the framework for a GUIBuilder control file (sample.gbf) by calling the GUIBuilder module
“gb_func::gb__make_gbf.
4 Write a program to analyze your legacy program and extract pieces that can be used in a GUI version of the
program. To help with this process, you might find a use for the called program “_label, which converts all line
number references in a program to line label references, and the pro5lst.exe utility, which converts a program file to
text. As you extract these pieces, write them to the GUIBuilder control file (sample.gbf) using the function
fngb__put_code$() included in gb_func.src. Think in terms of the following functional areas:
Initialization. Open data files; define record templates and other global variables. Note that GUIBuilder generates
an ENTER line with a single variable (gb__arg$), which can have an associated template to allow for passing
multiple values. Initialization code is written to the GUIBuilder control file with a header of [Init].
End of Job. Close data files; clean up global variables. End of Job code is written to the GUIBuilder control file
with a header of [EOJ].
Event handlers. This is the most difficult, because this is where the structures of character and GUI programs are
the most different. As a very rough approximation, consider using the “Got Focus and “Lost Focus events.
Subroutines, Functions, and non-executing code blocks. These can be relatively easy to move into the
GUIBuilder control file, but it’s up to you to ensure that they’re being used properly. Subroutines must include a
label and a return statement, and non-executing code blocks (IOLIST, DATA, and TABLE) should have an
associated label so you can refer to them from elsewhere in the program. These code blocks are written to the
GUIBuilder control file with a header of [Function (unique_name)]. If you have standard subroutines, functions,
IOLISTs, TABLEs, or other blocks of code that should be included in all of your programs, put them in the standard
include file gb_std.cod. This file is merged into the end of all programs generated by GUIBuilder. The standard
error and escape handlers are stored in ASCII text files (gb_err.cod and gb_esc.cod); if necessary, you can replace
them with customized error and escape handlers.
5 Confirm that the structure of the GUIBuilder control file (sample.gbf) is acceptable by calling the GUIBuilder module
“gb_func::gb__val_data .
6 Generate the final program (sample.bbx) by calling the GUIBuilder module “gb_func::gb__build_program.
7 At this point, the generated GUI program can be maintained within the GUIBuilder Visual Programming
Environment.
gb.ini File Parameters

The following identifies the parameters of the gb.ini file.
Parameter Initial Value Comments
about_box_win -1,-1 X,Y location of the “About GUIBuilder dialog box.
bitmap_dir Tells GUIBuilder where to find the .BMP files used in the
toolbar.
104
check_syntax No If set, GUIBuilder will syntax-check each code block before
saving it to the .gbf structure. The user can also check
syntax at any time with the menu selection Program -
>Check for Errors.
config_bbx ..\..\config.min Location of the user’s config.bbx file (used by Tools-
>VPRO/5 and by Program- >Run).
copyright If set, this will be copied to the Copyright= line in .gbf files,
which will cause a REM to be put at the beginning of
generated programs.
ddbuilder ..\..\vpro5\ddbuild.exe DDBuilder program (should be ddbuild.exe).
editor If set, GUIBuilder will call this external editor rather than
using the built-in TXEDIT controls.
error_list_win -1,-1 X,Y location of the error list window used to report syntax
errors to the user.
event_list_win -1,-1 X,Y location of the event list window used to prompt the
user to pick an event for a selected control.
find_win -1,-1 X,Y location of the “find text window.
help_file guibuild.hlp Name of the Windows Help file used by GUIBuilder.
include_comments Yes If set, this will be copied to the Remarks= line in .gbf files,
which determines if the program will be tokenized with the -
r flag (omit comments).
interpreter ..\..\vpro5\vpro5.exe Fully qualified name of the Visual PRO/5 interpreter.
Intro_video_file Name of the file, if any, that displays an introductory video
tutorial of GUIBuilder.
Lister ..\..\vpro5\pro5lst.exe Fully qualified name of the Visual PRO/5 stand-alone lister
program.
main_win -1,-1 X,Y[,W,H] location of the GUIBuilder main window.
memory_check_pages If set, this will be copied to the Pages= line in .gbf files,
which will cause a test for minimum required memory to be
put at the beginning of generated programs.
new_program_win -1,-1 X,Y location of the help screen that describes how to create
a new program using GUIBuilder.
options_win -1,-1 X,Y location of the program options window (Program-
>Options).
other_code_win -1,-1 X,Y location of the Other Code window.
pick_event_help_win -1,-1 X,Y location of the “Pick Events help window.
precision If set, this will be copied to the Precision= line in .gbf files,
which will generate a PRECISION line at the beginning of
generated programs. (Range - 1..16)
prefix If set, this will be copied to the Prefix= line in .gbf files,
which will generate a PREFIX line at the beginning of
generated programs.
program_extension bbx The extension for generated programs. A null setting
(program_extension=) is legal, and will cause tokenized
programs to be created with no extension. Source files have
a hard- coded extension of .src.
recent_files 4 Number of .gbf files to keep in the Most Recently Used list
on the Files menu (range 0..9).
recent_file1.. recent_file9 The most recently used .gbf files (updated when each .gbf
file is opened and when it is saved).
Release Yes If set GUIBuilder will release Visual PRO/5, returning to
Windows when you exit.
Resbuilder ..\..\vpro5\resbuild.exe Name of the resource editor program (Usually
105
RESBUILD.EXE, but could be RESEDIT.EXE).
select_control_win -1,-1 X,Y location of the “Select Control window, for selecting
among controls that overlap at the same screen location.
show_all_events Yes If set, the Event drop-down box will display all events, even
if they will not be visible in the event loop of the generated
program.
select_form_win -1,-1 X,Y location of the “Select Form window.
show_forms All This will be copied to the ‘Show Forms=’ line in .gbf files,
which determines how to initialize windows in generated
programs. Legal values are None (or 0): initially hide all
windows; First (or 1): initially hide all windows except for the
first one found in the resource file; and All (or 2), the default:
initially show all windows.
show_pick_event_help Yes Determines whether the user will see a dialog explaining
that he/she is about to attach code to a given event.
show_welcome_window Yes Determines whether the user will see the initial welcome
window when starting GUIBuilder. The user can click a
checkbox on the welcome window to suppress it in the
future.
splash_screen_win -1,-1 X,Y location of the initial copyright screen that comes up
when starting GUIBuilder.
subroutine_win -1,-1 X,Y location of the window for typing in the name of a new
subroutine or function.
tokenizer ..\..\vpro5\pro5cpl.exe Fully qualified name of the Visual PRO/5 stand-alone
tokenizer program.
use_carriage_returns No If set, GUIBuilder will create certain output files using CRLF
line terminators default is LF only).
welcome_win -1,-1 X,Y location of the GUIBuilder welcome window.
.gbf File Format

When you define a new program in GUIBuilder, the information relating to the new program is stored in a GUIBuilder
control file, with an extension of ‘.gbf’. This .gbf file works in concert with a BASIS resource file, which must be created
first. BASIS resource files can be created in ResEdit (Visual PRO/5 v.1 .brf format), ResBuilder (Visual PRO/5 v.2 .brc
format), or any text editor (Visual PRO/5 v.2 .arc format). ASCII Resource files (.arc format) must be converted to .brc
format before they can be used by GUIBuilder. This conversion can be done within ResBuilder (File- >Import- >ASCII
Resource), or you can use the stand-alone ResCompiler program (rescomp.exe).
This section identifies the .gbf file format and lists the variables in the [Program] section of the file.
File Sections
The GUIBuilder control file is an ASCII text file with a series of sections, each of which is identified by a token in square
brackets [] starting at the left margin. The overall file format is:
File Section Description
[Program] variable name = value
Click here for a list of the section variables.
[Init] Program initialization code goes here.
[EOJ] Program end-of-job cleanup code goes here.
[Remark] Optional remarks go here; they are ignored by GUIBuilder.
[Event …] Event handler sections are formatted as follows:
[Event Win=window_id ID=control_id
Code=event_code <event_name>
(subroutine_name)]
window-id identifies the form or child window within the resource file. A top-level
106
form with an ID of 10 would appear as Win=10. A child window with an ID of 1001
within a form with an ID of 10 would appear as Win=10.1001. A child window of
2001 within window ID 10.1001 would appear as Win=10.1001.2001.
control_id is a number assigned to a particular control in the resource file. It’s in the
range of from 1 to 32767. Control ID 0 indicates the window itself; window events are
identified with ID=0.
Event_code is a single case-sensitive letter or digit (e.g. ‘B’=button pushed,
‘X’=window closed) or a letter or digit followed by an integer qualifier (e.g. ‘f0’=focus
lost, ‘f1’=focus gained). For Notify events, ‘:’+control-type is appended to the base
event code. For example, “N2:19 (list button selection made), “N24:107 (grid row
inserted). Each control type supports a different set of event codes.
Event_name is a short description of the event code. For example, Code=X would
have an event name of <WIN_CLOSE>.
Subroutine_name is the internally-generated name of the event-handler subroutine
within the generated program. The following example demonstrates the usual format
of a subroutine name:
[Event Win=101.1002 ID=1001 Code=f0 <FOCUS_LOST>
(W101_1002_C1001_FOCUS_LOST)]
If GUIBuilder generates an event-handler subroutine name that exceeds 32
characters, the user will be prompted for a new subroutine name.
[Program] Section Variables

The following illustrates the variables in the [Program] section of the .gbf file. Most of these values are set in the
Program Options dialog.
Variable Name Sample Value Description
Resource File myprog.brc Name of the resource file used to create the .gbf file. The
directory path is never given; the resource file must be in
the current directory, or must be locatable using the Visual
PRO/5 PREFIX.
Program Name myprog Base name of the program, with no extension specified.
The program source is written to myprog.src; the extension
for the tokenized program is in the gb.ini parameter,
program_extension; it defaults to bbx.
Remarks Yes Determines whether REMs (comments) are to be copied to
the tokenized program. REMs will always appear in the .src
version.
Creation Date 1998-06-15 Date .gbf file created.
Creation Time 11:20:43 Time .gbf file created.
Copyright Copyright (C) 1998 BASIS If set, this causes the specified copyright notice to be
International Ltd. inserted near the beginning of the generated program.
Show Forms All Determines the initial visibility of forms in the generated
program. The possible values are “All (make all forms
visible), “First (make the first form visible, but initially hide
any others), or “None (start with all forms invisible; it is up to
the developer to determine when they will be made visible).
Prefix c:/data/ d:/data/ c:/prog/ If set, this causes a PREFIX statement to be created near
the beginning of the generated program.
Precision 4 If set, this causes a PRECISION statement to be created
near the beginning of the generated program. Precision is
in the range 0..16 places, or -1 for floating point.
Pages 1024 If set, this causes a memory test to be inserted near the
beginning of the generated program. If the program was not
started with at least this many pages, it will be restarted
with more memory. Note this parameter is ignored if the
program is CALLed.
107
Called Programs
gb_rec - Copy Fields Between Records

Syntax
call “gb.rec,gb__rec1$,gb__rec2$,gb__skip$,gb__copied$,gb__skipped$,gb__rec_err
Description
This called program is used to copy data from one record to another on a field-by-field basis. Data is copied based on
identically named fields; data types are more or less unimportant, and data will be converted as necessary. Data that
cannot be converted (e.g. copying “X to a numeric field) is reported in the gb__skipped$ list.
Argument Explanation
gb__rec1$ Fields are copied from here (the source record)
gb__rec2$ Fields are copied to here (the target record)
gb__skip$ Linefeed-delimited list of fieldnames to skip from the copy (optional)
gb__copied$ Returns a linefeed-delimited list of each fieldname:dim that was copied
gb__skipped$ Returns a linefeed-delimited list of each fieldname:dim that was skipped
gb__rec_err 0 = success
-1 = gb__rec1$ doesn't have a template
-2 = gb__rec2$ doesn't have a template
_label Utility - Convert Line Numbers to Line Labels

Syntax
call “_label,inpgm$,outpgm$,errmsg$,always_create
Description
The _label utility scans a tokenized Visual PRO/5 program for all line number references, converts them to line label
references, and generates line labels as necessary. The output is written to a separate program file. This utility is used
by the GUIBuilder “Get Existing Code function.
Argument Description
inpgm$ Name of the source program. It will not be modified in any way.
outpgm$ Output (target) program. If it exists, it will be erased.
errmsg$ • Returned as "" if outpgm$ was created correctly.
• Returned as "OK" if no conversions were necessary and outpgm$ was not
created.
• Returned as an error message if a problem was encountered.
always_create If 0: Don't create outpgm$ if there are no line labels to convert.
If 1: Create outpgm$ even if there are no line labels to convert.
Mini-Tutorial
This section takes you through the process of creating a new .gbf file, moving to ResBuilder to open a resource file,
viewing properties for the form, button, and static text controls contained in the resource file, returning to GUIBuilder,
setting the options for the program to be created, creating the event handler code, running the program, and checking
for errors. This overview of GUIBuilder will concentrate on three main points:
• The relationship between GUIBuilder and ResBuilder.
• The process of writing event handlers.
• The use of GUIBuilder built-in functions for managing the windows and controls.
108
To introduce the features of GUIBuilder, we will create a simple GUI "Hello World" program. This program will display a
window with a title of "Hello GUIBuilder!" It will have a push button called "Push Me" that, when pushed, will bring up the
message "Hello from GUIBuilder!"
The GUIBuilder screen consists of a menu, a tool bar, four list buttons (drop-down boxes), and an edit window. One of
the things we can do here is edit code. But there are a lot more features than that. Look at the tool buttons at the top
and the list buttons just below them. The tool buttons enable us to do things like edit subroutines, check syntax, and
build and run the program. The list buttons hold information about the forms, controls, and events that are available for
use in the program.
Creating a New .gbf File

As with other Windows programs, we start with the File menu. On the File menu, select New.
We are asked for a name for the GUIBuilder file. Let’s be original and call it "Hello." Once the file has been named, we
are asked if we need to use ResBuilder to build a resource for our program.
Moving to ResBuilder
A resource is related to a Windows screen the way a data dictionary is related to a database. It is a file that stores the
properties of the windows and controls for a given program. Controls like push buttons and radio buttons provide the
means by which the user communicates with the GUI program.
109
ResBuilder enables you to create a window and define the properties of the controls on it, all without having to write any
code.
Let’s answer "Yes" to the question and bring up ResBuilder.
110
As you can see, ResBuilder has a flexible interface for designing windows and controls. On the left side is a tree view
that shows all the components of the resource. On the right is the work area where forms are designed. The tool buttons
across the top of the ResBuilder screen can be used to create forms or windows and populate them with controls like
push buttons, edit boxes, grids, tabs, etc.
111
Opening a Resource File in ResBuilder
Although a new resource file can be created in ResBuilder, in our example we will use Hello.brc, an existing resource
file. If you would like more information on ResBuilder, please consult the product documentation.
Even a simple program like "Hello World" requires a window with some controls. Let’s go to the File menu and open
Hello.brc.
112
Resource File Properties
As you can see on the left side of the screen, the Hello.brc resource contains a form named "Hello" with two controls, a
push button named "Push Me," and a static text control called "Message." Accompanying each control and the form is a
properties page, which contains various details about it, including its size, position, and ID. Once the form or control is
selected, clicking Properties on the View menu displays the properties page.
Viewing Form Properties

The following illustrates the properties page for the form:
When we click on the Flags property, the Flags dialog displays a list of options that determine the appearance and
behavior of the window. You can see that we have checked the flags "Close box," "Minimizable," and "Sizeable." These
flags will generate the familiar three buttons on the right side of the title bar to enable the user to resize and close the
window.
113
Viewing Button Properties
The following displays the properties page for the button control. Notice that the initial contents—the button caption— is
"Push Me!"
114
Viewing Static Text Properties
The following displays the properties page for the static text control. Even though we couldn’t see the static text control
until we clicked on it, it is present on the form. This is the area of the screen where we will display the message, "Hello
from GUIBuilder!" You can see from the properties page that the name of the static text control is "Message" and that it
is initially empty.
Returning to GUIBuilder
Let’s close ResBuilder and go back to GUIBuilder by selecting Exit from the File menu. The Open Resource File
dialog appears. Let’s select "Hello.brc", the resource file we just reviewed in ResBuilder. After we have selected the
resource file, the Program Options dialog appears.
Program Options
The Program Options dialog enables you to enter global parameters for the generated program. You can specify a
prefix, numeric precision, and memory requirements. You can determine whether one, all, or none of the forms in the
resource are initially visible at start up. You can also include remarks in the generated program and specify a copyright
string to be included in the program source file.
115
116
Object List
The Object list now contains the name of the screen object, Form 101, which shows that we are dealing with the
resource we just created. There is only one window in the Hello.brc resource, hence the Window list button is disabled.
Control List
The Control list shows three controls: the form itself, the push button, and the static text control. Notice how GUIBuilder
has used the names for these controls as defined in ResBuilder. Also shown are the ID and type for each control. Let’s
select the Push Me button.
117
Event List
The Event list shows three events: "Button Pushed," "Control Lost Focus," and "Control Got Focus. In this program, we
are only interested in the "Button Pushed" event, so we select it.
118
Event Handler Code
Now we can decide what should be done when the events associated with the selected control are generated. Notice
that GUIBuilder has put a REM statement in the edit window. This is where we create the “event handler for this event.
The event handler is a block of Visual PRO/5 code that gets executed automatically whenever the event occurs. We
have decided that when the user presses the Push Me button, we will display a message in the static text area called
“Message.
119
GUIBuilder comes with several built-in functions to help you manage data in the controls. We will use the following data
management functions to simplify the process of updating the screen:
Function Description
fngb__template$() Takes one argument—a window identifier. It returns a template with data
fields based on the controls from the specified window.
fngb__put_screen$() Takes two arguments—a window identifier and a string to act as a
screen buffer. The screen buffer must have been previously
dimensioned using the template returned by fngb__template$().
All GUIBuilder built-in functions are named with the prefix fngb__ (two underscores) followed by a function name.
Variables are named similarly, with the prefix gb__ followed by a variable name.
The template in this example has two fields: Push_Me corresponds to the push button control, and Message
corresponds to the static text control. Using Visual PRO/5 template notation, we can refer to these fields as:
Hello.Push_Me$ and Hello.Message$.
Let’s use the built-in functions to update the screen. First, we dimension a string, Hello$, with the template returned from
fngb__template$():
dim Hello$:fngb__template$(gb__win_id$)
Then we assign the message text to the template field, Message$:
Hello.Message$=Hello from GUIBuilder!
Next we use the fngb__put_screen$ function to update the screen (but note we’ve made a typo at the end of this line):
Hello$=fngb__put_screen$(gb__win_id$,Hello$
120
Running the Program
Let’s save our work and run the program by selecting Run Program from the Program menu.
121
GUIBuilder then asks us to name the program. Let’s call it hello.bbx. Now GUIBuilder builds the program using its
framework and our code, and runs it. GUIBuilder displays a message box to inform us of an error.
Checking for Errors

Let’s click the OK button to bring us back to the edit window. GUIBuilder highlights the line that contains the error.
122
Looking at the end of the line, we see the error: the terminating parenthesis in the fngb__put_screen$() line was left off.
Let’s fix the error and save and run the program again.
This time, GUIBuilder was able to successfully build and run the program. When we push the Push Me! button, the
message appears:
123
This is a very simple example of a GUI program created using GUIBuilder. We were able to focus on the functional
behavior of the program, without having to worry about the details of the GUI environment. The built-in functions further
simplify your work, enabling you to work with controls using names rather than numbers.
GUIBuilder can also simplify the migration of programs from character to GUI. The Get External Code selection on the
Program menu enables you to load an existing character program into an edit window. This code is automatically
converted into ASCII text with all line number references converted to line labels. You can then copy and paste the
relevant "business rule" code into your new program.
124
Developers with well structured code and screen libraries can put together procedures to automatically generate
GUIBuilder files directly from their current code.
There are many more things that GUIBuilder can do. This simple example shows you how to get started. Please visit the
BASIS web site, http://www.basis.com, for more information and examples.
125
GUI CONTROLS AND EVENTS
SYSGUI Device
The purpose of the SYSGUI device is to facilitate the creation and manipulation of custom graphical windows from a Visual PRO/5
program.
The purpose of the SYSGUI device is to facilitate the creation and manipulation of custom graphical windows from a Visual PRO/5
program. To use SYSGUI device, do the following:
1 Add an alias line like the following to config.bbx:
ALIAS X0 SYSGUI
(Any alias starting with X may be used, but there is no advantage to using other than X0, which is provided by default when
Visual PRO/5 is installed. Note that the installation process should add this line to your config.bbx file for you.)
2 Open X0 and start interacting with it. Multiple windows, controls, etc. may be created and destroyed without closing or
reopening X0.
Multiple SYSGUI Opens

It is permissible for an application to have more than one channel open to the SYSGUI device. However, the current context,
scaling, units, and the like, are all global parameters. Changing these on one SYSGUI channel immediately affects the behavior of
all SYSGUI channels. Also, there is only one event queue and one input stream. (For example you could theoretically send
'LISTADD'(101,-1,10) to one SYSGUI channel, then send the ten items to the other.)
When the last channel to SYSGUI is closed, all SYSGUI windows and all of their contents are destroyed automatically.
Querying the SYSGUI Device

At any time, you may use the CTRL() function to get information about the current state of the SYSGUI device, including current
context, contents of controls, and the like.
FIN(chan) also returns useful information including current context, number of active contexts, and first available context. Get the
TMPL(chan,IND=0) to see the template. For more information, see the FIN() function in the Commands Manual.
Historical Color Palette

Under Visual PRO/5 Revision 1.0, all SYSGUI windows automatically received a custom “color cube” palette to accurately display
colors in bitmapped images. However, this lead to several problems. The first is that Microsoft's WIN32s products, Windows and
Windows for Workgroups, can crash if focus is shifted between windows repeatedly, thus forcing many swift palette changes. The
second is that colors in controls, which are always rendered in the stock system palette, often did not exactly match the colors in
the window. For example, an attempt to create a light gray “3d-look” dialog box could lead to mismatched colors on some
systems. As a result, the custom “color cube” palette is now optional, and by default is not used. In Visual PRO/5 Revision 1.01,
SYSGUI windows normally inherit the stock system palette. If you display photographic bitmaps and would like to use the custom
“color cube” palette as before for better color accuracy, you must use the window creation flag $00400000$.
Whenever a SYSGUI window with a custom palette gains focus, and your display has 256 colors or fewer, you may notice some
color “flashing” as focus shifts between windows. This is normal and you will also observe this behavior with other applications that
require accurate color displays. If you find the flashing to be a problem, the best way to avoid it is to use a display mode that
permits more than 256 colors (usually 65,536 colors or 16M colors). Sometimes using simpler wallpaper or not using wallpaper
can help.
Windows and Dialogs

Traditionally, there are two distinct types of graphical windows: the window and the dialog (sometimes known as a dialog box).
Each has its own capabilities:
Window Capabilities Dialog Capabilities
Can be drawn or plotted into. Can be navigated from the keyboard.
Can have menus. Can have hot keys.
Can accept keyboard characters as input. Can be modal (whole application pauses until user responds).
Can use the mouse outside of operating controls. Can stay on top (immune to being obscured by other windows).
Can be set to be resized by the user. Can have a distinctive frame style.
126
While it is always a good idea to know how graphical systems generally work, we have tried to avoid imposing these rules on you.
Our SYSGUI device opens one type of item, a 'WINDOW', which can possess almost any combination of the above attributes.
(Note that this is not to be confused with PRO/5 terminal screens which are also created with 'WINDOW', but on a different type of
device.) You can simply decide how you want a window to work and create it as such. If you want to draw in a dialog, or have hot
keys where there is no keyboard navigation, you can.
Prepared Resources
If you have prepared a window/dialog resource with the BASIS Resource Editor, and you have retrieved that resource using the
RESGET() function, you can create it simply by issuing the 'RESOURCE' mnemonic in an empty context. The size parameter
should be the length of the resource string returned by RESGET(), and the mnemonic must be followed immediately by the
resource string.
Coordinate Systems
Since the SYSGUI device contains so much information, two coordinate systems are needed:
• Placement and manipulation of GUI objects such as the controls and the windows themselves.
• Drawing and plotting commands. Each has its own set of customizable units.
In the default condition the two coordinate systems match up, but this can cease to be true even if the window is simply resized by
the user. It is important to be aware of the two coordinate systems and how they work.
For clarity, this guide refers to these two systems as CONTROL coordinates and DRAWING coordinates.
CONTROL Coordinates
All operations that manipulate GUI objects, such as controls and the windows that contain them, are performed with coordinates in
the CONTROL coordinate system. CONTROL coordinateshave their origin (0,0) at the upper-left corner of the window, and are
initially measured in pixels, though there are three units of measure to choose from. The axes may be scaled by arbitrary
multipliers (which need not even be integers), but the origin may not be translated.
CONTROL scaling and units are SYSGUI-wide parameters. If you are in the process of creating several windows simultaneously,
and you change the scaling or units, all sizes in the new mode are subsequently specified. In other words, these parameters are
global and not dependent on the current context. Changing the scaling or units does not affect any data that has already been
entered.
CONTROL Coordinates: Scaling and Units

By default, all CONTROL coordinatesand dimensions are specified in pixels. The problem with this approach is that a window or
dialog box that looks good in one display resolution might look bad on another, due to a different system font size. In order to
make it easy to write portable GUI code, we provide alternative units of measure that are based on character size, as well as the
ability to scale both axes.
The 'PIXELS', 'CHARS', and 'SEMICHARS' mnemonics select the current unit of measure in the CONTROL coordinate system, in
which subsequent coordinates will be specified. The default units are 'PIXELS', which always match the display, dot for dot. When
a program is moved to a system with a different system font, some GUI objects containing text (such as push buttons) might not
look right if specified in pixels. 'CHARS' are always the width and height of a character cell in the current system font.
'SEMICHARS' are smaller units based on character cells. Contrary to what its name would suggest, a semichar is not half a
character or even a quarter of a character. A semichar is defined as one quarter the width of a character and one eighth the height
of a character. If you use chars or semichars, the actual pixel coordinates and dimensions are adjusted to the font in use, as
needed to compensate for the system font size.
The 'SCALE' mnemonic can be used to enter multipliers for CONTROL coordinates. For example, if you entered a dialog box
using 'PIXELS', but now want to realize the benefits of the automatic adjustment available when you use 'CHARS' or
'SEMICHARS', you can achieve this with a 'SCALE' setting. (Using .5 for both XSCALE and YSCALE can convert pixels to
semichars on some systems.)
DRAWING Coordinates.
DRAWING coordinates are used to plot or draw into a SYSGUI window. By default, one unit equals one pixel, and the origin is at
the upper left. (Note that there is an absolute unit of measure available. See the 'DRAWUNITS' mnemonic.) However, the axes
can be translated, scaled, and reversed.
Keyboard Focus, Keyboard Navigation, and the Default Button

Keyboard focus determines which window or control will receive information typed at the keyboard. Windowing systems show
which control has focus by highlighting it. MS Windows uses various means to highlight the control that has keyboard focus. The
'FOCUS' mnemonic can be used to force the focus to a particular window or control.
127
Keyboard navigation allows the use of standard keys to change keyboard focus. Without keyboard navigation, it is almost always
necessary to use the mouse to operate controls. (The exception is if you provide hot keys, or if you detect key presses and act on
them yourself. In effect, you are creating your own keyboard navigation when you do this.)
If keyboard navigation is enabled, and a window contains any buttons, there is always a default button. The default button is
identifiable by a black rectangle drawn around the outside. Normally the default button is the button with the lowest ID number, but
if another button has focus, that button temporarily becomes the default button and shows the black rectangle. (If a button is inside
a group box, the black rectangle will not be visible. However, the user can still tell which button is the default because it will also
have keyboard focus.)
If the keyboard navigation flag was specified when a window or child window was created, key pressed ("t") events for arrow
keys and the tab key will not be reported.
Standard keyboard navigation proceeds as follows:
Key Action
<Tab> Move to the next focusable control. Controls that are disabled or invisible cannot receive keyboard
focus, nor can controls that do absolutely nothing, like static text or group boxes. Also, grouped
controls are treated as a set.
<BackTab> Move to the previous focusable control.
<Enter> Operate default button (often OK).
<Space> Operate the control that has focus.
Arrow Keys Move among grouped controls.
<Escape> Operate button with ID=2, if present (usually Cancel).
Standard Button IDs

If you use ID 1 for OK buttons and ID 2 for Cancel buttons, they will behave in standard ways when keyboard navigation is
enabled. Pressing <Enter> will choose OK, provided that no other button has focus. Initially the OK button will have focus since it
has the lowest ID. Pressing <Escape> will choose Cancel.
Note that the <Enter> key will always operate the default button, regardless of its ID, (provided that keyboard navigation is
enabled), but the <Escape> key will only work if a button with ID 2 exists.
The title of the button with ID 1 does not have to read “OK”, nor does the one with ID 2 have to read “Cancel”, nor does your code
have to behave in any particular way when these buttons are pressed. The <Enter> key simply operates the default button, and
<Escape> operates the button with ID 2, if there is one. ID 1 is suggested for the default button if it is used as an OK type
operation, but this is not the only way it can be used.
Hot Keys
Whether or not keyboard navigation is enabled, it is possible to assign hot keys to push buttons, check boxes, and radio buttons.
To do this, specify an ampersand, “&”, before the letter or symbol in the title text which is to be the hot key. It is possible to have a
hot key that is not in the title text. To do this, create the control with one title, then change titles. Only the initial title determines the
hot key used for a control. Ampersands in subsequent titles merely appear in the displayed title.
Pressing the hot key character when the window has keyboard focus will operate the control. It won't work, however, if some other
control in the window has keyboard focus. This is necessary, since some controls accept text. Under MS Windows, holding down
the <Alt> key while pressing the hot key will work any time the window has focus, even if another control currently has focus.
Top-level menu mnemonics can work the same way. For example, to access the File menu, <Alt>+<F> could be used. If
this is the case, avoid assigning F as the hot key for a control. It may operate both the menu and the control (but the
behavior is not guaranteed).
Accelerator Key Values

The following key values can be used for menu accelerators, and are identical to the key values returned when Keypress "t"
Events are enabled in a window:
Key Hex Value
Delete $007F$
Up arrow $012D$
Down arrow $012E$
Right arrow $012F$
Left arrow $0130$
128
Page up $0131$
Page down $0132$
Home $0133$
End $0134$
Insert $0138$
Backtab $013B$
Keypad 0 (numeric keypad with Num Lock off) $013E$
Keypad 1 $013F$
Keypad 2 $0140$
Keypad 3 $0141$
Keypad 4 $0142$
Keypad 5 $0143$
Keypad 6 $0144$
Keypad 7 $0145$
Keypad 8 $0146$
Keypad 9 $0147$
F1 $014B$
F2 $014C$
F3 $014D$
F4 $014E$
F5 $014F$
F6 $0150$
F7 $0151$
F8 $0152$
F9 $0153$
F10 $0154$
F11 $0155$
F12 $0156$
Keypad * (* on numeric keypad) $0174$
Keypad - (- on numeric keypad) $0175$
Keypad + (+ on numeric keypad) $0176$
Keypad / (/ on numeric keypad) $0177$
Combination Key Values

To include <Shift>, <Ctrl>, and/or <Alt> key combinations in accelerators, add the following values to the base key number:
Combination Hex
Value
<Shift> $1000$
<Ctrl> $2000$
<Shift> + <Ctrl> $3000$
<Alt> $4000$
<Shift> + <Alt> $5000$
<Ctrl>+ <Alt> $6000$
129
<Shift> + <Ctrl> + <Alt> $7000$
<Alt> key combinations are only available in Visual PRO/5 Rev. 2.0x and later.
For example, the following identifies the values for the possible combinations to be used with the <F1> key (value $014B$):
Combination Hex Value
<Shift> + <F1> $114B$
<Ctrl> + <F1> $214B$
<Shift> +<Ctrl> + <F1> $314B$
<Alt> + <F1> $414B$
<Shift> + <Alt> + <F1> $514B$
<Ctrl> + <Alt> + <F1> $614B$
<Shift> + <Ctrl> + <Alt> + <F1> $714B$
GUI Controls
Button Controls
Button controls function as push buttons and usually contain labels. Common uses include creating standard OK, Cancel, and Exit
buttons for dialogs.
Creating
Mnemonic Description
'BUTTON' Create a Push Button Control.
Manipulating
'TITLE' Set Control Title.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the control title.
4 Returns the control class and type.
8 Returns the visible/invisible and enabled/disabled status of the control.
15 Returns the background color of the control.
16 Returns the foreground color of the control.
Check Box Controls

Check box controls appears as square boxes with accompanying labels. Check boxes support options that are either on or off,
and are used for independent or nonexclusive choices.
In contrast radio button controls are used to set one option from two or more available options.
Creating
'CHECKBOX' Create a Check Box Control.
Manipulating
130
'CHECK' Check Object (By default, check boxes are initially unchecked.)
'UNCHECK' Uncheck Object.
Querying
2 Returns the checked/unchecked status of the check box.
Child Windows
Child windows are simpler versions of windows and are frequently used to create tool bars. They are always contained within
another window. Child windows may contain buttons, check boxes, edit boxes, list objects, other child windows — all the objects
that can be placed in a top level window. However, a child window cannot have a menu or a title bar, cannot be modal, and is not
user-resizable.
If the child window has the gravity flag enabled, all controls within the child window will automatically arrange themselves to fit.
The controls will appear left to right and top to bottom in ID sequence order.
An optional docking flag may be used with a child window. If docking is enabled, the child window automatically attaches itself to
the top edge of the parent window and will initially size itself to the full width of the parent. If the parent is resized, the child resizes
itself as well. This is useful for creating tool bars. A child window with docking enabled is placed in the parent window and the
objects for the tool bar are placed within the child window. The 'DOCK' mnemonic may be used to change the docking location
from the top of the parent window to the bottom, left, or right.
All of the optional events that may be placed on top level windows may be used with child windows as well. However, the flags for
child windows are not the same. All SYSGUI drawing and printing commands are valid for child windows.
Creating
'CHILD' Create Child Window.
Manipulating
'CONTEXT' Set Device Context.
'DOCK' Change Child Window Docking Position.
Querying
4 Returns the class and type of the control.
Custom Edit Controls

Custom edit controls can hold one or more lines of text (known as "paragraphs"), each of which may occupy one or more physical
lines, depending on the “wrap” setting. If the text will be limited to one line, use the edit box control instead.
131
Creating
'TXEDIT' Create A Custom Edit Control.
Modifying
'TXADD' Add Paragraphs To A Custom Edit Control.
'TXAPPEND' Append Text To Custom Edit Control Paragraphs.
'TXCLR' Clear Custom Edit Control Text.
'TXDEL' Delete Custom Edit Control Paragraphs.
'TXLIMIT' Limit Custom Edit Control Paragraph Length.
'TXRESUME' Resume Custom Edit Control Updates.
'TXSELECT' Perform Custom Edit Control Text Selection.
'TXSETTAB' Change Custom Edit Control Tab Settings.
'TXSUSPEND' Suspend Custom Edit Control Updates.
Querying
1 Returns the text of the current paragraph.
2 Returns the current paragraph number (zero based).
3 Returns the total number of paragraphs in the custom edit control.
5 Returns the text of a specified paragraph.
7 Returns the text of all paragraphs.
12 Returns the current text selection.
Edit Controls
Edit controls are capable of displaying a single line of text for editing. (If multiple lines of text are needed, use a custom edit
control.) One special use of the edit box is for password entry, when the password flag is enabled. As the password is typed,
asterisks are displayed in the control, one for each character entered.
Creating
'EDIT' Create an Edit Control.
Manipulating
'SELECT' Select Text (Used to position the caret or select text.)
'TITLE' Set Control Title.
Querying
132
1 Returns the text of the edit control
12 Returns the current text selection.
Group Box Controls

A group box control is a box with a light gray border surrounding items that the programmer wishes to visually combine for the
user.
Creating
'GROUPBOX' Create a Group Box Control.
Querying
Horizontal Scroll Bar Controls

Horizontal scroll bar are used for scaled value selections. Horizontal scroll bars should not be confused with scroll bars that can be
created with optional flags on windows, child windows, and multi-line edit controls.
Creating
'HSCROLL' Create a Horizontal Scroll Bar Control.
Manipulating
'SCROLLPOS' Set Scroll Bar Position.
'SCROLLPROP' Set Scroll Bar Proportion.
'SCROLLRANGE' Set Scroll Bar Range.
Querying
2 Returns a 2-byte integer containing the location and value of the thumb position.
133
Images
The image object displays a bitmapped graphic on the window of the current context and is typically used to display a background
bitmap. The bitmap will not obscure any controls currently visible.
Images use the DRAWING coordinate system, while controls use the CONTROL coordinate system. To draw an image and have
it appear in a particular position relative to controls (and you are using the 'SEMICHAR' mnemonic) the most reliable method is to
place an invisible group box in the desired position. By switching to pixels briefly (with the 'PIXELS' mnemonic) and using
CTRL(chan,id,0) to retrieve the group box's bounding rectangle in pixels, the image can then be placed at that position. Switch
back to 'SEMICHARS' before placing additional controls.
Creating
'IMAGE' Draw Bitmapped Image.
Manipulating
'TRACK' Toggle Tracking On/Off (Setting this to 0 prevents the image from being resized when the
window is resized.
Graphical Edit (INPUTE) Controls

INPUTE controls provide the capability to accept user input from the keyboard, but with input masking and character padding
capabilities.
Creating
'INPUTE' Create a Graphical Edit (INPUTE) Control.
Querying
INPUTE SENDSMSG() Function Number

Get Error 35
Get Mask 22
Get Pad Character 26
Get Position 24
Get Restore String 28
Get Title 20
Numeric Edit (INPUTN) Controls

INPUTN controls provide the capability to accept user input from the keyboard, but with input numeric masking and character
padding capabilities.
Creating
134
'INPUTN' Create a Numeric Edit (INPUTN) Control.
Querying
2 Returns an 8-byte string representing a business math value using:
DIM B$:"BUS:B"B.BUS$=CTRL(sysgui,controlid,2)

INPUTN SENDSMSG() Function Number

Get Error 25
Get OMask 22
Get Position 24
Get Restore String 26
Get Title 20
List Box Controls

The list box control presents the user a selection of choices in a box. Multiple selections may be made if the multi-selections flag is
set. To select a range of choices, the user selects the first item, then holds the <Shift> key while selecting the last item in the
range. Various keys may be used to navigate in the list including the Home (first selection), End (last selection), Page Up and
Page Down, and arrow keys.
The list of choices available may be modified only under program control. The values in the list may be accessed using a zero
based list index integer.
Creating
'LISTBOX' Create a List Box Control.
Manipulating
'LISTADD' Add List Item.
'LISTCLR' Clear List.
'LISTDEL' Delete List Item.
'LISTMSEL' Select Multiple List Items.
'LISTRESUME' Resume List Updates.
'LISTSEL' Select List Item.
'LISTSUSPEND' Suspend List Updates.
'LISTUNSEL' Deselect List Item.
Querying
1 Returns the text of selected items, delimited by $0A$ (but no final $0A$).
135
2 Returns the indices of all selected items.
3 Returns the number of selected items followed by the total number of items in the list.
7 Returns the text of all items with ($0A$) after each paragraph, including the last item.
List Button Controls

The list button control allows the user to select an item from a list. Unlike the list edit control, it does not allow a value to be
entered manually. As the user types, the first matching selection in the list is placed in the edit area. Various keys may be used to
navigate in the list including the Home (first selection), End (last selection), Page Up and Page Down, and arrow keys. The list of
choices available for list controls may be modified only under program control. Values in the list may be accessed using a zero
based list index integer.
Creating
'LISTBUTTON' Create a List Button Control.
Manipulating
Querying
1 Returns the text of selected items, delimited by $0A$ (but no final $0A$).
2 Returns the indices of all selected items.
7 Returns the text of all items with ($0A$) after each paragraph, including the last item.
List Edit Controls

The list edit control allows the user to enter a selection in the edit area, or, by left-clicking on the arrow, will display a drop-down
list of possible choices. If the user clicks on an item in the list, the item is copied into the edit area.
The list of choices available for list edit objects may be modified only under program control. Values in the list may be accessed
using a zero based list index integer.
136
Creating
'LISTBUTTON' Create a List Button Control.
Manipulating
Querying
1 Returns the text of the item in the edit area.
2 Returns the text of the item in the edit area and is the same as function 1.
Menus
Menus list commands available to the user and are contained within a menu bar, a special area displayed across the top of a
window directly beneath the title bar. A window created with the $00000800$ (Include Default Menu Bar) flag includes a default
menu bar that serves as a placeholder. The 'SETMENU' mnemonic is used to replace the window's default menu bar with a
custom menu.
Each menu item in the menu is defined by a line of text separated by commas into four fields. All fields except title can be empty,
but all commas must be present.
title,{tag},{accelerator},{flags}
title Menu title text, which can contain spaces but cannot begin with a space or contain a comma. If a
comma in a menu item title is required, create the menu with a different title and use the 'TITLE'
mnemonic to change the title. The comma can be a concern if the menu returned by CTRL(x,0,6)
is parsed.
Including the “&” symbol before a letter in the title designates the letter as a menu mnemonic. It
allows the item to be activated when the letter is pressed, but only if the menu is displayed and has
keyboard focus. In the menu, the letter is automatically underlined, indicating which key the user must
press. For example, entering &New as the title of a menu item allows it to be activated by pressing
the letter N, once the menu containing it has been activated.
tag Numerical ID, a positive number in decimal form between 1 and 32767. Do not use the values 32000
through 32767, except as follows:
ID Function
32027 Clipboard "Cut"
32028 Clipboard "Copy"
32029 Clipboard "Paste"
137
A tag can have the same number as a control or child window in the same context because the
negative of the tag is used with the various mnemonic and CTRL() functions. The same tag can also
be used in more than one window. Using the same tag more than once in the same menu will not
cause an error, but will make it impossible to determine which selection was made.
accelerator Hexadecimal value delimited by dollar signs, listed in the table below.
Accelerators make it possible to activate a menu item without requiring the menu containing it to be
activated. For example, entering $014B$ designates the <F1> key as accelerator key, and causes
"F1" to appear in the menu to the right of the title. If an accelerator is omitted or assigned the value
$00$, no accelerator is assigned to the item.
flags Menu flags, as follows:
Flag Description
C Sets the menu item to be checkable and initially checked.

D Sets the menu item to be initially disabled.
S Menu item separator. Title and hot key are ignored.
U Sets the menu item to be checkable and initially unchecked.
The 'CHECK', 'DISABLE', 'ENABLE', 'TITLE', and 'UNCHECK' mnemonics can also be used with menus. In using these
mnemonics with menus, the negative of the menu item's tag is used in place of the control ID.
Accelerator Key Values

The following key values can be used for menu accelerators, and are identical to the key values returned when Keypress "t"
Events are enabled in a window:
Key Hex Value
Delete $007F$
Up arrow $012D$
Down arrow $012E$
Right arrow $012F$
Left arrow $0130$
Page up $0131$
Page down $0132$
Home $0133$
End $0134$
Insert $0138$
Backtab $013B$
Keypad 0 (numeric keypad with Num Lock off) $013E$
Keypad 1 $013F$
Keypad 2 $0140$
Keypad 3 $0141$
Keypad 4 $0142$
Keypad 5 $0143$
Keypad 6 $0144$
Keypad 7 $0145$
Keypad 8 $0146$
Keypad 9 $0147$
F1 $014B$
F2 $014C$
F3 $014D$
138
F4 $014E$
F5 $014F$
F6 $0150$
F7 $0151$
F8 $0152$
F9 $0153$
F10 $0154$
F11 $0155$
F12 $0156$
Keypad * (* on numeric keypad) $0174$
Keypad - (- on numeric keypad) $0175$
Keypad + (+ on numeric keypad) $0176$
Keypad / (/ on numeric keypad) $0177$
Combination Key Values

To include <Shift>, <Ctrl>, and/or <Alt> key combinations in accelerators, add the following values to the base key number:
<Shift> $1000$
<Ctrl> $2000$
<Shift> + <Ctrl> $3000$
<Alt> $4000$
<Shift> + <Alt> $5000$
<Ctrl>+ <Alt> $6000$
<Shift> + <Ctrl> + <Alt> $7000$
<Alt> key combinations are only available in Visual PRO/5 Rev. 2.0x and later.
For example, the following identifies the values for the possible combinations to be used with the <F1> key (value $014B$):
<Shift> + <F1> $114B$
<Ctrl> + <F1> $214B$
<Shift> +<Ctrl> + <F1> $314B$
<Alt> + <F1> $414B$
<Shift> + <Alt> + <F1> $514B$
<Ctrl> + <Alt> + <F1> $614B$
<Shift> + <Ctrl> + <Alt> + <F1> $714B$
Example
The following data string is used to create a menu bar that contains File and Fruit menu items, each containing submenus.
menu$="File,1,,"+$0a$
menu$=menu$+" &New,2,," +$0a$
menu$=menu$+" separator,3,,S" +$0a$
menu$=menu$+" E&xit <F7>,4,$3151$," +$0a$
menu$=menu$+"&Fruit,5,," +$0a$
menu$=menu$+" Yellow Fruit,6,," +$0a$
139
menu$=menu$+" Bananas,7,,C" +$0a$
menu$=menu$+" Lemons,8,,U" +$0a$
menu$=menu$+" Orange Fruit,9,," +$0a$
menu$=menu$+" Oranges,10,," +$0a$
menu$=menu$+" Peaches,11,,D" +$0a$
menu$=menu$+" Tangerines,12,," +$0a$
menu$=menu$+$0a$
In the data string, indentation is used to describe the hierarchy. Items in the menu bar are not indented. Items in the menus that
drop from the menu bar are indented one space. If any items of the dropped menus have submenus, the submenu are indented
one more space, and so on. Tabs may not be used. The whole group is terminated by two $0A$ characters.
Radio Button Controls

Radio button controls present the user with a variety of choices. Two or more radio buttons may be placed together in a group box
to form a group of like items. Unlike check boxes, the buttons in a radio group are mutually exclusive. Thus, only one button may
be selected at any given time.
Creating
'RADIOBUTTON' Create a Radio Button Control.
Manipulating
'CHECK' Check Radio Button (By default, radio buttons are initially unchecked).
'GROUPBOX' Create a Group Box Control.
'RADIOGROUP' Create A Radio Button Group.
'UNCHECK' Uncheck Radio Button.
Querying
2 Returns the checked/unchecked status of the radio button.
Status Bar Controls

Status bars display messages for the user along the bottom of the window.
In Visual PRO/5 Rev. 2.x and later, the status bar control can be divided into up to 255 segments, and each can contain left-
justified, right-justified, or centered text. Text justification within a segment is achieved by using the tab character $09$. Text to the
right of a single tab character is centered, and text to the right of a second tab character is right-aligned.
By default, the status bar contains a single segment which is left-justified and behaves like the original status bar control of Visual
PRO/5 1.0. This initial segment or part is identified as part 0.
Creating
'STATBAR' Create a Status Bar Control
140
Querying
1 Returns the status bar text.
7 Returns the status bar text. Results are identical to those of function 1.
Tab Controls
Tab controls provide the capability to multiple logical pages or sections of information within the same window.
Creating
'TABCTRL' Create a Tab Control.
Querying
1 Returns the index of the currently-selected tab.
7 Returns the status bar text. Results are identical to those of function 1.
TABCTRL SENDSMSG() Function Number

Get Bounding Rectangle 21
Get Current Tab 38
Get/Set Display Rectangle 20
Get Number of Tab Rows 22
Get Tab Count 31
Get Tab Image List ID 30
Get Tab Index 29
Get Tab Information 27
Tool Button Controls

Tool buttons are similar to push buttons, with some significant differences. A tool button:
• Displays more information (mouse position, mouse button, <Ctrl> and <Shift> key status, etc.).
• Can display either text or a picture (bitmap).
• Can operate normally or as a toggle (click on, click off), which can be queried.
• Can use the 'COLORSET' or 'OPTIONS' mnemonic to modify the displayed color.
• Cannot be focused with keyboard navigation commands.
141
• Does not include a “focus rectangle” when it has focus.
Typically, tool buttons are grouped together in a tool bar.
Creating
'TBUTTON' Create a Tool Button Control
Manipulating
'TITLE' Set Control Title (Sets the tool button text).
Querying
1 Returns the tool button title or bitmap image filename.
2 Returns the up/down status of the tool button.
Vertical Scroll Bar Controls

Vertical scroll bars are used for scaled value selections. Vertical scroll bars should not be confused with scroll bars that can be
created with optional flags on windows, child windows, and multi-line edit controls.
Creating
'VSCROLL' Create a Vertical Scroll Bar Control.
Manipulating
'SCROLLPOS' Set Scroll Bar Position.
'SCROLLPROP' Set Scroll Bar Proportion.
'SCROLLRANGE' Set Scroll Bar Range.
Querying
2 Returns a 2-byte integer containing the location and value of the thumb position.
142
SYSGUI Event Queue
SYSGUI Events
The SYSGUI device employs an event queue to provide notification of user interaction with graphical objects. An application using
this mechanism must READ the SYSGU channel to watch for events. There is only one event queue, regardless of how many
contexts are active on the SYSGUI channel, and regardless of how many channels are opened to SYSGUI.
Retrieving the Event Template

Each event is returned as a fixed-size string in a standard format. A template for the event structure may be obtained with
TMPL(channel).
OPEN(channel)"X0"
DIM E$:TMPL(channel)
READ RECORD (channel,siz=len(E$))E$
Event Template Structure

context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
Activation Event
Activation events indicate when users switch between applications, and between windows within an application. When an
Activation event occurs, the event code is set to "A."
For application activation and deactivation, the context is irrelevant. For window activation and deactivation, examining the x field
indicates if the window is minimized and indicates when a top level window is activated or deactivated.
Previously, when users switched between applications via keyboard entries such as the <Alt>+<Tab> combination, Visual PRO/5
did not always send a focus change event to the application's top level window because the change was passed to the frame
window that manages the top level window. The following table identifies the Activation event parameters.
Mandatory/Optional: Optional
Mask Bit: $40000000$
Event Template
Field Description
context Application activated/deactivated events = current context.
Window activated/deactivated events = window which was activated or deactivated.
code A
id 0 = Application deactivated.
1 = Application activated.
2 = Window deactivated.
3 = Window activated by mouse click.
4 = Window activated by other than mouse click.
flags 0
x If id is 2, 3, 4:
1 = window is minimized
0 = window is not minimized.
y 0
143
Push Button Event
Mandatory/Optional: Mandatory
Event Mask bit: None. Event is always visible.
Event Template
Field Description
context Window containing the button that was pushed.
code B
id ID of the button control that initiated this event.
flags 0
x 0
y 0
Check/Uncheck Event
Event Mask bit: $02000000$
Event Template
Field Description
context Window containing the control (radio button, check box, checkable menu item, and tool button) that was checked
or unchecked.
code c
id ID of the control that initiated the event.
flags Check status:
$00$ = unchecked
$01$ = checked
x 0
y 0
Close Box Event

Event Template
Field Description
context Window that was closed.
code X
id 0
flags 0
x 0
y 0
144
Control Focus Gained/Lost Event
Event Template
Field Description
context Radio button, check box, button, list box, list button, edit, list edit, or custom edit control that gained or lost focus.
code f
id ID of the control that gained or lost focus.
flags 0
x 0
y 0
Edit Control Modify Event

Event Template
Field Description
context Window containing the edit, list edit, custom edit, or CEDIT control.
code e
id Control ID of an edit, list edit, custom edit, or CEDIT control.
flags 0
x 0
y 0
Keypress Event
Event Template
Field Description
context Window containing resource that had focus when the key was pressed.
code t
id Hexadecimal key value, as follows:
Hex Value Key
$0009$ Tab (not available if keyboard navigation is enabled).
$007F$ Delete
$012D$ Up arrow (not available if keyboard navigation is enabled).
$012E$ Down arrow (not available if keyboard navigation is enabled).
145
$012F$ Right arrow (not available if keyboard navigation is enabled).
$0130$ Left arrow (not available if keyboard navigation is enabled).
$0131$ Page up
$0132$ Page down
$0133$ Home
$0134$ End
$0138$ Insert
$013B$ Backtab
$013E$ Keypad 0 (numeric keypad with Num Lock off).
$013F$ Keypad 1
$0140$ Keypad 2
$0141$ Keypad 3
$0142$ Keypad 4
$0143$ Keypad 5
$0144$ Keypad 6
$0145$ Keypad 7
$0146$ Keypad 8
$0147$ Keypad 9
$014B$ F1
$014C$ F2
$014D$ F3
$014E$ F4
$014F$ F5
$0150$ F6
$0151$ F7
$0152$ F8
$0153$ F9
$0154$ F10
$0155$ F11
$0156$ F12
$0174$ Keypad * (* on numeric keypad).
$0175$ Keypad - (- on numeric keypad).
$0176$ Keypad + (+ on numeric keypad).
$0177$ Keypad / (/ on numeric keypad).
flags 0
x 0
y 0
List Item Click Event
Event Mask bit: $01000000$.
146
Event Template
Field Description
context Window containing the list button, list edit, or list box control.
code l (lower case L)
id Control ID of the list button, list edit, or list box control that generated the event.
flags Click type:
$00$ = Single
$01$ = Double
x 0
y 0
Menu Selection Event

Event Template
Field Description
context Window containing the menu bar.
code C
id Control ID of the menu item that initiated this event.
flags $01$ = Shift
$02$ = Ctrl
$04$ = Selection is currently checked.
x 0
y 0
Mouse Button Down Event
Event Template
Field Description
context Current window.
code d
id Mouse button:
$00$ = Left
$01$ = Right
$02$ = Middle
147
flags Key pressed:
$01$ = Shift
$02$ = Ctrl
x Horizontal pixel location of the mouse click.
y Vertical pixel location of the mouse click.
Mouse Button Up Event

Event Template
Field Description
code u
id Mouse button:
$00$ = Left
$01$ = Right
$02$ = Middle
flags Key pressed:
$01$ = Shift
$02$ = Ctrl
Mouse Double-Click Event
The mouse was double clicked.
Event mask bit: $00000200$
Event Template
Field Description
code 2
id Mouse button:
$00$ = Left
$01$ = Right
$02$ = Middle
flags $01$ = Shift key pressed.
$02$ = Ctrl key pressed.
148
Mouse Move Event
Event Template
Field Description
code m
id Mouse button:
$00$ = Left (or none)
$01$ = Right
$02$ = Middle
flags Key pressed:
$01$ = Shift
$02$ = Ctrl
x 0
y 0
Notify Events
Notify events create notice strings that contain event information that cannot be contained in the event string of grid, edit, INPUTE
and INPUTN, list edit, list button, and tab controls. When a Notify event occurs in an application, the event code is set to "N".
Notify events are mandatory and are always visible.
To retrieve the notice string, execute the NOTICE() function . To retrieve the template string definition for the notice code and
object that caused the event, execute the NOTICETPL() function .
The following illustrates a standard method for decoding Notify events, and is to be followed by the body of the event loop:
sysgui=unt; open (sysgui)"X0"
dim event$:tmpl(sysgui)
dim generic$:noticetpl(0,0); rem ' Generic Notice Template
repeat
read record (sysgui,siz=len(event$))event$
if event.code$="N" then
: generic$=notice(sysgui,event.x%);
: dim notice$:noticetpl(generic.objtype%,event.flags%);
: notice$=generic$
Edit Control Notify Events
The following Notify event applies to edit controls:

Code Notice Template Event Description
1 context:u(2),code:i(1), Keypress Notify event. The Keypress Notify event-generating keys are identical to
id:u(2),objtype:i(2), those returned in the keypress event ("t").
key:u(2)
The special key values for the edit control Notify event are identical to those used for INPUTE and INPUTN control Notify events.
149
INPUTE and INPUTN Notify Events
The INPUTE and INPUTN controls can generate two types of Notify events:
The following Notify event codes and templates apply to INPUTE and INPUTN controls:
Code Notice Template Event Description
context:u(2),code:i(1),
1 id:u(2),objtype:i(2), Keypress Notify event. The Keypress Notify event-generating keys
key:u(2) are identical to those returned in the keypress event ("t").
2 context:u(2),code:i(1), Error Code Notify event. An error occurred either by specifying a

id:u(2),objtype:i(2), invalid mask, a invalid length, or invalid restore text. An error can also
error:u(2) be generated by several SENDMSG() functions. See the individual
function for the error description.
The following table lists each special key that can generate the Keypress Notify event in the INPUTN, INPUTE, and edit controls
and its corresponding returned value. The values are stored in the key field of the Keypress Notify event template.
Key Hexadecimal Key Value Key Hexadecimal Key Value
<Tab> $0009$ <Keypad 7> $0145$
<Escape> $001B$ <Keypad 8> $0146$
<Delete> $007F$ <Keypad 9> $0147$
<Up arrow> $012D$ <F1> $014B$
<Down arrow> $012E$ <F2> $014C$
<Right arrow> $012F$ <F3> $014D$
<Left arrow> $0130$ <F4> $014E$
<Page Up> $0131$ <F5> $015F$
<Page Down> $0132$ <F6> $0150$
<Home> $0133$ <F7> $0151$
<End> $0134$ <F8> $0152$
<Back tab> $013B$ <F9> $0153$
<Keypad 0> $013E$ <F10> $0154$
<Keypad 1> $013F$ <F11> $0155$
<Keypad 2> $0140$ <F12> $0156$
<Keypad 3> $0141$ <Keypad *> $0174$
<Keypad 4> $0142$ <Keypad -> $0175$
<Keypad 5> $0143$ <Keypad +> $0176$
<Keypad 6> $0144$ <Keypad /> $0177$
The following values added to the key codes indicates if the <Shift>, <Alt>, and <Ctrl> keys were pressed when the Keypress
Notify event was issued:
Value Key/Key Combination Value Key/Key Combination
$1000$ <Shift> $5000$ <Shift> + <Alt>
$2000$ <Ctrl> $6000$ <Ctrl>+ <Alt>
$3000$ <Shift> + <Ctrl> $7000$ <Shift> + <Ctrl> + <Alt>
$4000$ <Alt>
The following lists the errors generated by the INPUTE and INPUTN controls:
Error Possible Cause(s)
Code
16 The SENDMSG() function was issued to retrieve the restore string, but the destination buffer in Visual PRO/5
was too small. This indicates a start size that is not large enough for the application.
150
The SENDMSG() function was issued to retrieve the title of the INPUTE or INPUTN control, but the string
buffer was too small. The start size was not large enough for the application.
The SENDMSG() function was issued to set the !EDIT value, but the string passed was greater than 256
characters.
17 The SENDMSG() function was issued to set the position of the caret, but the position was not within the valid
range of positions for the text in the control.
41 The SENDMSG() function was issued to set the length of the INPUTE or INPUTN buffer, greater than 256
characters.
43 The user executed the restore command. However, the restore string was invalid for the control's output mask.
The high bit will be set.
The user pasted text that does not fit the mask used by the control. The high bit will be set.
The SENDMSG() function was issued to set the restore string, but the string was not valid for the control's
output mask. This error can be ignored if the mask will be correctly set afterwards.
Errors that result from user action set the high bit in the Error Code Notify event error value. (The high bit is the first bit in the
ERROR field in the Notice string returned by the NOTICE() function.) At this time, the only user action that can cause an error is
pasting text from the clipboard by using either the <Ctrl>+V or <Shift>+<Insert> key combinations.
List Button and List Edit Notify Events

The following describes the Notify events for list button and list edit controls:
Name Value Description
LISTOPEN 1 The user clicked the drop-down arrow on the list edit or list button control to display the list.
LISTSELECT 2 The user selected an item from the displayed list.
LISTCLOSE 3 List was closed, and is no longer displayed.
LISTCANCEL 4 The user canceled the selection process.
LISTCHANGE 5 Selected item(s) in the list were changed.
Scrollbar Move Event
Event Template
Field Description
context Window containing the scrollbar that was moved.
code p
id 0
flags 0
x New scrollbar location.
y 0
System Color Change Event

Event Template
Field Description
151
code s
id 0
flags $01$ = system colors changed.
x 0
y 0
Tool Button Push Event
Event Template
Field Description
context Window containing the button that was pushed.
code b
id ID of the tool button control that initiated this event.
flags Mouse button:
$00$ = Left
$01$ = Right
$02$ = Middle
Function key:
$04$ = Shift
$08$ = Ctrl
$10$ = Alt
x 0
y 0
Window Focus Gained/Lost Event
Event Template
Field Description
context Window that gained or lost focus.
code F
id 0
flags 0
x 0
y 0
152
Window Resize Event
Event Template
Field Description
context Window that was resized.
code S
id 0
flags 0
x New horizontal window size, in pixels.
y New vertical window size, in pixels.
Grid Control Notify Events
Event Types
Table Information Notify Events
Table Information Notify events report changes to cells, rows, and columns and general grid changes such as focus, sizing and
drag/drop notification. Table Information Notify events use the TI$ templated string, as follows:
context:u(2),code:i(1),id:u(2),objtype:i(2),msg:i(4),wparam:i(4),lparam:i(4),col:i(4),
row:i(4),textcolor:c(3),backcolor:c(3),alignment:u(1),style:i(4),imgidx:i(4),
x:i(2),y:i(2),w:u(2),h:u(2), ptx:i(2),pty:i(2),buf:c(1*)
Each Table Information Notify event uses some or all of the fields contained in the template. The individual Notify event section
identifies the actual fields used.
The following identifies the Table Information Notify events.
Code Name
1 COLUMNSIZED
2 COLCHANGE
3 DCLICKED
4 DRAGDROP
5 EDITCHANGE
6 EDITKEY
7 EDITKILL
8 EDITSET
9 ENTER
10 HITBOTTOM
11 HITTOP
12 KEYBOARD
13 KILLFOCUS
14 LCLICKED
15 LCLICKED2
153
16 LEFTCOLCHANGE
17 MOUSECAPTURE
18 RCLICKED
19 ROWCHANGE
20 SETFOCUS
21 TOPROWCHANGE
28 EDITSTART
Request Update Notify Events

Request Update Notify events report grid requests to redraw the cells in the range specified. Request Notify events use the
REQUPD$ templated string, as follows:
context:u(2),code:i(1),id:u(2),objtype:i(2),leftcol:u(6),toprow:u(6),rightcol:u(6),botrow:u(6)
The following identifies the Request Update Notify event:
Code Name
22 TABLEUPDATE
Data Aware Record/Row Operation Notify Events

Data Aware Record/Row Operation Notify events report the occurrences of row insert, delete, update or modification cancel
operations. Data Aware Record/Row Operation Notify events use the RCDNFY$ templated string, as follows:
context:u(2),code:i(1),id:u(2),objtype:i(2),row:i(4),rcd:c(1*=)
Data Aware Record/Row Operation Notify events use some or all of the fields contained in the template. The individual Notify
event section identifies the actual fields used. The following identifies the Data Aware Record/Row Operation Notify events.
Code Name
24 ROWINSERT
25 ROWDELETE
26 ROWCANCEL
27 ROWUPDATE
Error Notify Events

Error Notify events report errors that have occurred in the grid control. Error Notify events strings use the ERROR$ templated
string, as follows:
context:u(2),code:c(1),id:u(2),objtype:i(2),griderror:i(2),bberr:i(2),tcberr:i(2),rcd:c(1*)
Code Name
29 ERROR
COLUMNSIZED Grid Notify Event

Description
A user resized a column.
Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),msg:i(4),wparam:i(4),lparam:i(4),col:i(4),row:i(4),
textcolor:c(3),backcolor:c(3),alignment:u(1),style:i(4),imgidx:i(4),x:i(2),y:I(2),w:u(2),h:u(2),
ptx:i(2),pty:i(2),buf:c(1*)
Significant Field Description
context Context the event occurred in.
code 1.
154
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
wparam Updated width of the resized column.
col Number of the resized column
COLCHANGE Grid Notify Event

Description
The currently-selected column in the grid has changed.
Event Template
context Context in which the event occurred.
code 2.
wparam Extended key status flag, which identifies the status of the <Shift>
and <Ctrl> keys:
• Bit $01$ set = <Ctrl> pressed.
• Bit $02$ set = <Shift> pressed.
col Number of the column that was just changed (zero-based).
DCLICKED Grid Notify Event

Description
The mouse was double-clicked.
Event Template
code 3.
and <Ctrl> keys:
155
col Column containing the clicked cell.
row Row containing the clicked cell.
x, y, w, h Rectangle containing the clicked cell.
ptx,pty Point within the cell that was clicked.
DRAGDROP Grid Notify Event

Description
A drag/drop operation was performed.
Event Template
code 4.
wparam Number of strings dropped.
col Number of the column receiving the drag/drop operation.
row Number of the row column receiving the drag/drop operation.
buf List of dropped strings.
Each string is field-terminated. A list of strings that was sent is also contained within the buf$ field. See Drag Accept - GRID
SENDMSG() Function 33.
EDITCHANGE Grid Notify Event

Description
The contents of the edit control changed. To retrieve the text, execute Get Edit Title - GRID SENDMSG() Function 35. No TI$
fields are affected.
Event Template
code 5.
156
EDITKEY Grid Notify Event
Description
A special key was pressed while the grid was in edit mode.
Event Template
code 6.
wparam A special key was pressed. The following indicates the special
keys and the corresponding returned values:
<Enter> = 1
<Tab> = 2
<Shift> + <Tab> = 3
<Up Arrow> = 4
<Down Arrow> = 5
<Page Up> = 6
<Page Down> = 7
<Esc> 8
<F1> = 11
<F2> = 12
<F3> = 13
<F4> = 14
<F5> = 15
<F6> = 16
<F7> = 17
<F8> = 18
<F9> = 19
col Number of the current column.
row Number of the current row.
EDITKILL Grid Notify Event

Description
The edit control lost focus.
Event Template
157
code 7.
col Number of the column being edited.
row Number of the row being edited.
buf Edit control text.
EDITSET Grid Notify Event

Description
The edit control gained focus.
Event Template
code 8.
ENTER Grid Notify Event

Description
The <Enter> key was pressed while the control was not in edit mode.
Event Template
code 9.
and <Ctrl> keys:
158
HITBOTTOM Grid Notify Event

Description
The user tried to scroll past the bottom row of the grid. This message allows users to change the number of rows while they are
using the grid.
Event Template
code 10.
wparam Attempted number of rows scrolled.
lparam Number of current rows in the grid.
If the data source contains an unknown number of records, set the number of rows in the grid to 1, then trap the HITBOTTOM
Notify event message. Next, check wparam for more records and readjust the number of rows in the grid using Set Number of
Rows - GRID SENDMSG() Function 67.
HITTOP Grid Notify Event

Description
The user tried to scroll past the top row of the grid. This message can be used to adjust the grid positioning.
Event Template
code 11.
wparam Attempted number of rows scrolled.
lparam Number of current rows in the grid.
159
KEYBOARD Grid Notify Event
Description
The grid has focus and a key that is not processed by the grid itself (such as a cursor key) was pressed.
Event Template
code 12.
wparam Value of the key pressed. Returns the same information as a key
press event for the SYSGUI channel.
KILLFOCUS Grid Notify Event

Description
The grid control lost focus.
Event Template
code 13.
LCLICKED Grid Notify Event

Description
The left mouse button was clicked on a cell that is not the current cell. This event is sent each time the button is pressed or
released. (If the left mouse button is clicked on the currently selected cell, an LCLICKED2 Notify event is sent.)
Event Template
160
code 14.
and <Ctrl> keys:
lparam Mouse button position:
• 1 Button pressed.
• 0 Button released.
col Number of the column containing the clicked cell.
row Number of the row containing the clicked cell.
x, y,w,h Rectangle containing the clicked cell.
LCLICKED2 Grid Notify Event

Description
The left mouse button was clicked when the cursor was positioned over the current cell. (If the left mouse button is clicked on a
cell that is not the current cell, an LCLICKED Notify event is sent.)
Event Template
code 15.
and <Ctrl> keys:
161
LEFTCOLCHANGE Grid Notify Event
Description
The left column of the grid has been changed. (The current row/cell does not have to change for this message to be sent.)
Event Template
code 16.
and <Ctrl> keys:
col Number of the new left column (zero-based).
MOUSECAPTURE Grid Notify Event

Description
A mouse capture event has taken place.
Event Template
code 17.
and <Ctrl> keys:
162
This event is returned 10 times per second while a mouse button is held down but must be enabled via Set Mouse Capture - GRID
SENDMSG() Function 64. Once the mouse button is released, Set Mouse Capture mode is automatically set to False (0), which
disables the message.
RCLICKED Grid Notify Event

Description
The right mouse button was clicked. The message is sent each time the button is pressed and each time it is released.
Event Template
code 18.
and <Ctrl> keys:
ROWCHANGE Grid Notify Event

Description
The current row in the grid has changed.
Event Template
code 19.
163
and <Ctrl> keys:
row Number of the row that was just selected (zero-based).
SETFOCUS Grid Notify Event

Description
The grid gained focus.
Event Template
code 20.
TOPROWCHANGE Grid Notify Event

Description
The top row of the grid has changed. (The current row/cell does not have to change for this message to be sent.)
Event Template
code 21.
and <Ctrl> keys:
164
row Number of the row that was just selected (zero-based).
TABLEUPDATE Grid Notify Event

Description
Indicates that the grid requires information from the application before it can be redrawn. When one or more cells in a grid need to
be redrawn, this event is issued. It is the programmer's responsibility to provide code to redraw the cell(s) specified in the
TABLEUPDATE event.
It is imperative that an event loop managing a standard grid check for Notify event 22 from the main grid control and the row
header grid, if present, and respond to them. Otherwise blank cells and headers may appear in the grid (see the Standard Grid
Tutorial 1: Display-Only Grid and Standard Grid Tutorial 2: User-Modifiable Grid for examples of how this can be done).
Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),leftcol:u(6),toprow:u(6),rightcol:u(6),botrow:u(6)
code 22
leftcol Last four fields define the range of cells that need to be redrawn. Note that row and column
numbering is zero-based. The leftcol field indicates the leftmost column with cells that need
to be redrawn.
toprow Top row with cells that need to be redrawn.
rightcol Rightmost column with cells that need to be redrawn.
botrow Bottom row with cells that need to be redrawn
ROWINSERT Grid Notify Event

Description
A row was added to the grid and the corresponding record on the grid channel was written. The grid control automatically adjusts
the number of managed rows by adding 1.
Event Template
code 24
row Number of the inserted row.
rcd Record inserted, deleted or updated. (This field is empty if a
record/row insert cancellation is identified.)
ROWDELETE Grid Notify Event

Description
A row was deleted from the grid and the corresponding record on the grid channel was removed. The grid control automatically
adjusts the number of managed rows by subtracting 1.
165
Event Template
code 25
row Number of the deleted row.
ROWCANCEL Grid Notify Event

Description
A row insertion was canceled by the user, which causes the row to be removed from those managed by the grid. (row is the only
significant field in RCDNFY$.)
Event Template
code 26
row Number of the row whose insertion was canceled.
ROWUPDATE Grid Notify Event

Description
A row was updated in the grid and the corresponding record on the grid channel was also updated with the row information.
Event Template
code 27
row Number of the updated row.
EDITSTART Grid Notify Event

Description
A data-aware grid entered edit mode.
166
Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),msg:i(4),wparam:i(4),lparam:i(4),
col:i(4),row:i(4),textcolor:c(3),backcolor:c(3),alignment:u(1),style:i(4),
imgidx:i(4),x:i(2),y:I(2),w:u(2),h:u(2), ptx:i(2),pty:i(2),buf:c(1*)
code 28.
ERROR Grid Notify Event

Description
An error has occurred in the grid.
Event Template
context:u(2),code:c(1),id:u(2),objtype:i(2),griderror:i(2),bberr:i(2),tcberr:i(2),
rcd:c(1*)
code 29.
griderror Grid error code, as identified in the following table.
bberr Error a business basic program would see if the operation were attempted by a user
program. The validity of this field depends upon the grid error code, as identified in the
following table.
tcberr Error a business basic program would see if the program issued a TCB(10) after the
operation failed. The validity of this field depends upon the grid error code, as identified in
the following table.
rcd Record in use when the operation failed.
Grid Error Code Notify Event Descriptions

The following identifies and describes the ERROR Notify event griderror field, and indicates the validity of the bberr and tcberr
fields (these three fields are defined .)
griderror Description bberr tcberr
code valid valid
1 An unrecoverable input channel error occurred. The application should reset the data aware Yes Yes
parameters in the grid control.
2 An unrecoverable write error occurred. The application should reset the grid control data Yes Yes
aware parameters.
3 An unrecoverable read error occurred on the user data channel. The application should reset Yes Yes
the grid control data aware parameters.
4 An unrecoverable read error occurred on the temporary grid data channel. The application Yes Yes
should reset the grid control data aware parameters.
5 The user attempted to perform a command that is not allowed in edit mode. No No
6 A grid destroy event occurred while operating on the grid data. User's data will be lost. This No No
167
error is simply to notify the user program that this condition is unexpected.
7 An unrecoverable I/O error occurred during the removal of a record. The application should Yes Yes
reset the grid control data aware parameters.
8 An unrecoverable I/O error occurred during the extraction of a record. The application should Yes Yes
reset the grid control data aware parameters.
9 The end of the file contained on the user channel was reached. This is a notification rather Yes Yes
than an error.
10 A missing key error occurred during the removal of a record. The record is marked as Yes Yes
deleted.
11 During the setup for an edit operation, the grid attempted to extract the user record but Yes Yes
received a missing key error. The record is marked as deleted and the edit operation is
cancelled.
12 During the setup for an edit operation, the grid attempted to extract the user record but Yes Yes
received a record busy error. The record is marked as busy and the edit operation is
cancelled.
13 During an update operation, the grid attempted an extract operation on the update channel to Yes Yes
verify that the new record does not exist, returning a record busy error. The record is marked
as busy, the current row is returned to the edit state, and program intervention is awaited.
The application should be set to either cancel the edit operation or retry the update by
sending an "End Edit" message to the grid control.
14 During an insert operation, the grid attempted an extract operation on the update channel to Yes Yes
verify that the new record does not exist, returning a record busy error. The record is marked
as busy, the current row is returned to the edit state, and program intervention is awaited.
The application should be set to either cancel the edit operation or retry the update by
sending an "End Edit" message to the grid control.
During an insert operation, an EXTRACT was attempted on the update channel to verify that
the new record does not exist and the operation succeeded. This is considered a conflict
because the record should not exist. The application should be set to either cancel the edit
operation or retry the update by sending an "End Edit" message to the grid control.
15 Fatal grid data aware error. Please report it to BASIS Technical Support and describe the No No
conditions under which it occurred.
16 A grid update request occurred and a busy record was discovered while updating the rows of Yes Yes
the grid. The user program need not do anything, this is simply a notification. The row is
marked as busy.
17 A grid update request occurred and a missing record was discovered while updating the rows Yes Yes
of the grid. The user program need not do anything, this is simply a notification. The row is
marked as deleted.
18 During a remove record operation, a busy record was found. The user's program should Yes Yes
attempt the remove at a later time.
19 The grid control has run out of memory while processing. This is unrecoverable. Application Yes No
code should attempt a graceful shut down.
20 A masking error occurred while editing. The grid control remains in the edit state, but the No No
application program should reset the mask for the current column to accommodate the data
in the file. It should cancel the editing of the row and allow the user to retry after fixing the
mask.
21 A template error occurred. Application code needs to respond to this. This is probably No No
happening because the template doesn't match the record.
22 A template error occurred. Application code needs to respond to this. This is probably No No
happening because the template doesn't match the record.
23 A masking error occurred while displaying a field. The grid control either goes back to the edit No No
state or to the idle state, but the application program should reset the mask for the current
column to accommodate the data in the file. It should cancel the editing of the row and allow
the user to retry after fixing the mask.
168
Tab Control Notify Events
Keypress Notify Event

Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),keycode:u(2),syskey:u(1)
This Notify event is generated when a key is pressed while the tab control has focus--as indicated by the text on a tab label being
highlighted. The key that was pressed can be determined from the value of the keycode parameter, and the state of system keys
(shift, Ctrl, etc.) can be determined from the value of the syskey parameter. The principle is similar to the Key pressed event
returned by windows (event code="t"), but some of the values are different and the format in which the pressed key is reported is
different.
Field Description
code Always 1.
id Tab control's ID.
objtype Always 106.
keycode Hexadecimal representation of the key that was pressed. If a letter key is pressed, the code
returned corresponds to the ASCII representation of the letter in upper case, regardless of the
state of the shift key. Note that the next field indicates the status of the shift key, Ctrl key, etc. The
following codes are returned for special keys and other keys that do not return ASCII codes:
$0008$ Backspace
$0009$ Tab
$000C$ Keypad 5 (numeric keypad with Num Lock off)
$000D$ Enter
$0013$ Break
$0014$ Caps Lock
$001B$ Escape
$006E$ Keypad . decimal (numeric keypad with Num Lock on)
$007F$ Delete
$0090$ Num Lock
$0091$ Scroll Lock
$00BA$ ;
$00BB$ =
$00BC$ ,
$00BD$ - (dash)
$00BE$ . (period)
$00BF$ /
$00C0$ `
$00DB$ [
$00DC$ \
$00DD$ ]
$012D$ Up arrow
$012E$ Down arrow
$012F$ Right arrow
$0130$ Left arrow
$0131$ Page up
169
$0132$ Page down
$0133$ Home
$0134$ End
$0138$ Insert
$013B$ Backtab
$013E$ Keypad 0 (numeric keypad with Num Lock on)
$013F$ Keypad 1
$0140$ Keypad 2
$0141$ Keypad 3
$0142$ Keypad 4
$0143$ Keypad 5
$0144$ Keypad 6
$0145$ Keypad 7
$0146$ Keypad 8
$0147$ Keypad 9
$014B$ F1
$014C$ F2
$014D$ F3
$014E$ F4
$014F$ F5
$0150$ F6
$0151$ F7
$0152$ F8
$0153$ F9
$0154$ F10
$0155$ F11
$0156$ F12
$0174$ Keypad * (* on numeric keypad)
$0175$ Keypad - (-on numeric keypad)
$0176$ Keypad + (+ on numeric keypad)
$0177$ Keypad / (/ on numeric keypad)
syskey Indicates the state of the system keys:
$00$ No system key pressed.
$01$ <Shift>
$02$ <Ctrl>
$03$ <Shift>+<Ctrl>
$04$ <Alt>
$05$ <Alt>+<Shift>
$06$ <Ctrl>+<Alt>
$07$ <Ctrl>+<Alt>+<Shift>
170
Example
The following statements trap the F1 key when the focus is on a tab and display a message box. These statements would appear
in an event loop, and assume that the generic$ variable has been templated:
generic$=notice(sysgui,event.x);
dim notice$:noticetpl(generic.objtype,event.flags);
notice$=generic$
if event.code$="N" and notice.code=1 and event.id=tab_control_id then
if notice.keycode$=$014B$ and notice.syskey$=$00$ then
result=msgbox("Help not available.")
Tab Selection Notify Event

Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),tabidx:i(2)
This Notify event is generated when a tab index is selected. Typically, an application program will display data on the associated
child window after detecting this event. The notice string returns the selected tab index. Tab indices are defined in ResBuilder or
with the 'TABCTRL' mnemonic. The left tab has an index of 1, the next tab to the right has an index of 2, and so on.
Field Description
code Always 2.
objtype Always 106.
tabidx Index of the tab that was just selected.
Example
The following statements check for the user selecting different tabs. These statements would appear in an event loop, and
assume that the generic$ variable has been templated:
generic$=notice(sysgui,event.x);
dim notice$:noticetpl(generic.objtype,event.flags);
notice$=generic$
if event.code$="N" and notice.code=2 and event.id=tab_control_id then
if notice.tabidx=1 then
gosub display_tab1_values
else if notice.tabidx=2 then
else
Tab Deselection Notify Event

Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),tabidx:i(2)
This Notify event is generated when a tab index is deselected. Typically, an application program will validate and store data that
has been entered in the deselected tab's controls after detecting this event. The notice string returns the selected tab index. Tab
171
indices are defined in ResBuilder or with the 'TABCTRL' mnemonic. The left tab has an index of 1, the next tab to the right has an
index of 2, and so on.
Field Description
code Always 3.
objtype Always 106.
tabidx Index of the tab that was just deselected.
172
RESBUILDER
Introduction
ResBuilder is a utility that allows you to visually create window, control, image list, and menu resources and store them in .brc
format binary resource files that can be called by Visual PRO/5 applications. Using ResBuilder to create your resource information
provides the following benefits:
• The ResBuilder-created binary resource files are external to the program code, which helps reduce the size and complexity of
the program files.
• ResBuilder simplifies the interface prototyping process because it allows you to create GUI resources without writing program
code. You can build, modify, and finalize the interface design before writing any code. Setting default values for resources
makes it easy to create multiple resources without having to continually reset custom parameters.
• ResBuilder makes it easier to modify interfaces at a later date by allowing you to open and modify existing binary resource
files.
ResBuilder operates under Windows 95, and Windows NT 3.51 and 4.0.
Using ResBuilder
The following describes the normal sequence of events for using ResBuilder to create, define, and store resources:
1 Start ResBuilder.
2 Create a new file, open an existing .brc, .arc, or .brf resource file.
3 Create and define forms and child windows. (It is possible to set default values for forms, child windows, and images.)
4 Create and define controls.
5 Create and define menus.
6 Create image lists.
7 Save the file.
8 Exit ResBuilder
The ResBuilder Interface

The ResBuilder interface consists of the menu bar, the toolbars, tree view, status bar, and edit area.
173
Getting Started
Starting ResBuilder
To start ResBuilder, do one of the following:
• In the Windows 95 or Windows NT Explorer, navigate to the directory that contains the resbuild.exe file, and double-click the
file’s icon.
Creating New ResBuilder Files

Each time you start ResBuilder, the program automatically creates and loads a new .brc file. To create a new file at any other
time, do the following:
You can only work on one file at a time and must exit one file before creating another. Issuing the following commands
will close a saved file or will prompt you to save or discard changes to an edited file.
To create a new binary resource file, do one of the following:
• Press <Ctrl>+N.
• On the Main toolbar, click the New File button.
Opening Existing .brc Resource Files

To open and modify existing .brc files, do the following:
1 Display the Open dialog by doing one of the following:
• On the File menu, select Open.
• Press <Ctrl>+O.
• On the Main toolbar, click the Open button.
174
2 If you currently working on a file, ResBuilder will prompt you to save or discard your changes before closing the file and
displaying the Open dialog:
• Click Yes to save changes to the file.
• Click No to discard changes to the file.
• Click Cancel to continue working on the open file.
3 As a default, the files of type list box is set to display .brc files. To find .arc or .brf files, click the Files of type list box drop
down arrow and select ResBuilder Files [*.arc] or ResBuilder Files [*.brf], respectively.
4 Browse through the Open dialog to locate the desired file.
5 Select the file and click Open.
Saving Files
All files created or modified in ResBuilder are saved in the .brc binary resource file format. To save a resource file, do the
following:
1 To save a file, do one of the following:
• Press <Ctrl>+S.
175
2 The first time you save a file, ResBuilder will display the Save As dialog. Move to the directory into which you want to save
the file, enter the filename into the File name box and click OK. If you have already named and saved the file, no dialog
appears. ResBuilder resaves the file with the same filename and path.
To save a file under a new name, do the following:
1 On the File menu, select Save As to display the Save As dialog.
2 Move to the directory into which you want to save the file.
3 Enter the new filename into the File name box and click OK.
Exiting ResBuilder
1 To exit ResBuilder, do one of the following:
• On the File menu, click Exit.
• Click the Close box.
2 If you are working on a file and have modified it since the last time you saved it, ResBuilder will prompt you to save or discard
the changes before exiting:
• Click Yes to save changes to the file and exit.
• Click No to discard changes to the file and exit.
• Click Cancel to return to ResBuilder and keep working on the open file
Forms and Child Windows
Creating Forms and Child Windows

Do the following to create a form or child window:
Note: To learn how to create default values that can be applied to the creation of forms and child windows, click here.
1 To create forms or child windows, do one of the following:
• On the Main toolbar, click the Add Form or Add Child Window.
• On the tree view, click the Form or Child Window icon, right-click to display the context-sensitive menu, then click Add.
2 The form or child window then appears in the edit area, and a corresponding form or child window icon appears in the tree
view. The gray rectangle defines the dimensions of the form or child window.
Using the Layout Grid

ResBuilder allows you to display a grid in forms and child windows to make it easier to position controls.
• In addition to displaying or hiding the grid, you can change the grid size and set the snap to grid or snap to size option.
• The grid serves as a layout and alignment tool only, and it does not appear in resource file printouts nor in applications that
utilize the resource file.
Displaying and Hiding the Layout Grid

To display the grid in a form or child window, do the following:
1 Click the form or child window, then do one of the following:
• On the Layout menu, select Grid.
• On the Align toolbar, click Grid.
2 The grid then appears inside the selected form or child window. To hide the grid, repeat step 1.
Changing the Layout Grid Size

The default grid size is 10 pixels by 10 pixels. To change the grid size, do the following:
On the Options menu, select Grid Spacing to display the Grid Spacing dialog:
176
Set the grid width and/or height, as follows:
• In the Width box, enter the number of pixels for the desired grid width.
• In the Height box, enter the number of pixels for the desired grid height.
Click OK.
Setting Snap-to-Grid
The snap-to-grid option moves the upper left corner of controls to the closest intersection of two gridlines. To set the snap-to-grid
option, do one of the following:
• On the Layout menu, select Snap On.
• On the Align toolbar, click the Snap On button.
Setting Snap-to-Size
The snap-to-size option enlarges or shrinks controls to fit it to the intersections of gridlines closest to their upper left and lower
right boundaries. To set the snap-to-size option, do one of the following:
• On the Layout menu, select Snap Size On.
• On the Align toolbar, click the Click Snap Size On button.
Sizing Forms and Child Windows

The gray rectangle within the Edit area represents the dimensions of the form or child window.
To change the width of a form or child window, do the following:
1 Move the mouse over the vertical boundary of the gray rectangle until the mouse pointer changes to a horizontal, two-headed
arrow.
2 Click and drag the boundary left or right to the desired size.
To change the height of a form or child window, do the following:
1 Move the mouse over the lower boundary of the gray rectangle until the mouse pointer changes to a vertical, two-headed
arrow.
2 Click and drag the boundary up or down to the desired size.
Aligning Child Windows

Within a form, you can align two or more child windows along the boundary of the last child window selected, as follows:
1 Press and hold down <Shift>, then click each child window to be aligned.
2 On the Align toolbar, select the desired alignment option, as follows:
• Click Left Align to align the child windows along the left boundary of the last selected child window.
• Click Right Align to align the child windows along the right boundary of the last selected child window.
• Click Top Align to align the child windows along the upper boundary of the last selected child window.
• Click Bottom Align to align the child windows along the lower boundary of the last selected child window.
A layout grid can be can be displayed within the form to make it easier to align and distribute child windows.
Defining Form and Child Window Properties

To define properties for forms and child windows, do the following:
1 Click the form or child window, then do one of the following:
177
• On the Main toolbar, click Properties.
• On the tree view, right-click the form or child window’s icon to display the context-sensitive menu, then click Properties.
2 The form or child window’s property page, then appears.
Properties pages are used to set properties for the selected item and are organized into four property types, as identified below.
String properties use text entries to define settings such as Name, Initial Contents, Short Cue, and Long Cue.
Integer properties use integer entries to define settings such as Control ID, X position, Y position, Height, and Width.
List properties define settings such as Justification, Fore Color, and Back Color that are selected via list box selections. A list
property field can be identified by the drop-down button that is positioned along its right edge. Some of these properties allow
178
you to choose between the windows system defaults and customized settings defined via common Windows dialogs such as
color palettes and font lists.
Dialog properties define settings such as flags that are established via common Windows dialogs. A dialog property field can
be identified by the ellipsis (...) button that is positioned along its right edge.
3 In the Value column of the properties page, define the form or child window properties, as follows:
• To define string properties, enter a text string.
• To define integer properties, enter a numeric value.
• To define list properties, click the list button and click the desired property.
• To define dialog properties, click the ellipsis icon to display the appropriate Windows dialog.
• To display help for properties page entries, click anywhere within the Value and press F1.
Setting Default Values

Defining a set of default values frees you from the necessity of defining them each time you create a form or child window. The
default values are set via the Set Default Value form, which is similar to the properties page:
1 Display the Set Default Value form by doing one of the following:
• On the Edit menu, select Set Default Value.
• On the context-sensitive menu, select Set Default Value.
2 Select the resource type for which to define default values.
3 The defaults will be applied to resources created after the values are set.
Defining the Status Bar

To define a status bar for a form, do the following:
1 Click the form to select it.
2 Display the properties page, click the arrow in the Has Status Bar box, and select True.
3 Enter the property information.
Attaching Child Windows to Forms

Once you have created and defined a child window, do the following to attach it to a form during runtime:
179
1 Make note of the ID of the child window you want to attach to a form. For example, the following child window has an ID of
101:
2 Click the form to select it.

3 On the Controls toolbar, click the Child Window button, then click the form.
4 Position the child window button so that its upper left corner occupies the desired xy location of the child window to be
attached. A layout grid can be can be displayed within the form to make it easier to align and distribute child windows.) The
following shows a child window placed on a form that is placed in an x,y position of 30,60:
180
5 Enter the child window's control ID into the Child Window field. The above picture shows that a child window control ID of
101 has been entered.
6 Child windows can be shared by more than one form. To insert the child window in another form, repeat steps 1-5.
Setting Form and Child Window Display Options

The ResBuilder Window menu provides three options for displaying forms and child windows in the edit area:
1 To stack non-minimized form and child windows so that all title bars are visible, select Cascade.
2 To display all non-minimized form and child windows side-by-side, select Tile.
3 To arrange the icons of all minimized form and child windows along the bottom of the edit area, select Arrange Icons.
Hiding and Redisplaying Forms and Child Windows

The following procedures do not delete forms and child windows and their contents. Rather, they can be used to reduce
clutter in the edit area by decreasing the number of items displayed.
To hide forms and child windows contained in the edit area, do the following:
1 Click inside the form or child window.
2 Click the form or child window’s close box.
3 To redisplay the form or child window, click its icon in the tree view.
Deleting Forms and Child Windows

To delete forms and child windows, do the following:
1 Select the form or child window in one of two ways:
• In the edit area, click the form or child window.
• On the tree view, click the form or child window’s icon.
2 Delete the form or child window in one of three ways:
• Press <Delete>.
• Right-click to display the context-sensitive menu, then click Delete.
• On the Edit menu, select Delete.
3 To confirm deleting the form or child window, click Yes. Otherwise, click No to return to ResBuilder.
Controls
If you create controls that will be overlapped, the last control created is the first to be drawn by Visual PRO/5. To learn
how to create default values that can be applied to the creation of controls, click here.
Creating Single Controls

To create a single control, do the following:
1 On the Controls toolbar, click the desired control.
2 Move the mouse pointer over the desired point of insertion on the form or child window.
3 Click to place the control in the form or child window.
Creating Multiple Controls

To create multiple versions of the same control, do the following:
1 Ensure that the Revert to Pointer setting is turned off:
• If Revert to Pointer on the Main toolbar is depressed, click it to turn off the Revert to Pointer setting.
• If the Revert to Pointer command on the Options menu is checked, select it to turn off the Revert to Pointer setting.
2 On the Controls toolbar, click the desired control.
3 Move the mouse pointer over the desired point of insertion on the form or child window.
4 Click to place the first control.
181
5 For each subsequent control, move the mouse pointer over the desired point of insertion and click to place it.
Sizing Controls
To change the width of a control, do the following:
1 On the Controls toolbar, click the Pointer Button.
2 Move the mouse over the vertical boundary of the control until the mouse pointer changes to a horizontal, two-headed arrow.
3 Click and drag the boundary left or right to the desired size.
A layout grid can be displayed within a form or child window to make it easier to size controls.
To change the height of a control, do the following:
1 On the Controls toolbar, click the Pointer button.
2 Move the mouse over the lower boundary of the control until the mouse pointer changes to a vertical, two-headed arrow.
3 Click and drag the boundary up or down to the desired size.
To adjust two or more controls to the same size, do the following:
1 On the Controls toolbar, click the Pointer Button.
2 Select one control to serve as the prototype, and size it to the desired height and width.
3 Press and hold down <Ctrl>, then click each control to be sized, selecting the prototype control last.
4 Size the controls by doing one of the following:
• On the Layout menu, select Set Same Size.
• On the Align toolbar, click the Same Size Button.
Moving Controls
To move one or more controls within a form or child window, do the following:
1 Select the control(s) as follows:
• To select a single control, click that control.
• To select multiple controls, press and hold down <Ctrl>, then click each control to be moved.
2 Move the mouse pointer over the control(s) until the pointer changes to an arrow tipped crosshair.
3 Click and drag the control(s) to the desired location.
A layout grid can be displayed within a form or child window to make it easier to place controls.
Aligning Controls
To align two or more controls along the boundary of the last control selected, do the following:
1 Press and hold down <Ctrl>, then click each control to be aligned.
2 On the Align toolbar, select the desired alignment option, as follows:
• Click Right Align to align the controls along the right boundary of the last selected control.
• Click Top Align to align the controls along the upper boundary of the last selected control.
• Click Bottom Align to align the controls along the lower boundary of the last selected control.
A layout grid can be displayed within a form or child window to make it easier to align controls.
Distributing Controls
To evenly distribute the vertical and horizontal spacing between two or more selected controls, do the following:
1 Press and hold down <Ctrl>, then click each control to be included in the distribution.
2 To distribute the horizontal spacing, do one of the following:
• On the Align toolbar, click the Horizontal Same Space button.
• On the Layout menu, select Distribute/Horizontal.
3 To distribute the vertical spacing, do one of the following:
• On the Align toolbar, click the Vertical Same Space button.
182
• On the Layout menu, select Distribute/Vertical.
A layout grid can be displayed within a form or child window to make it easier to distribute controls.
Grouping and Ungrouping Controls

Grouping controls together maintains their relative positions, allowing them to be moved as a unit.
To group controls together, do the following:
1 Select the controls to be included in the group in one of two ways:
• Click and drag the a box around the controls to select them.
• Click a control, then press the <Ctrl> button and click the additional controls to select them.
2 On the Layout menu, select Group Controls.
A control can only be part of one group at a time. If it is selected to be part of second group, it will be removed from the first group
when it is added to the second group.
To ungroup controls, do the following:
1 Select one of the controls, which causes all controls in the group to be selected.
2 On the Layout menu, select Ungroup Controls.
Defining Control Properties

Each time you create a control in ResBuilder, you also create a property page that allows you to define the control properties. To
display property pages and enter property definitions, do the following:
1 Click the control, then do one of the following:
• On the Main toolbar, click Properties.
• On the tree view, right-click the control’s icon to display the context-sensitive menu, then click Properties.
• On the tree view, double-click the control’s icon.
2 The control’s properties page then appears. Properties pages are used to set properties for the selected item and are
organized into five property types, as identified below. Click a property type to display its description.
Properties descriptions are contained in the Resource Properties Index.
183
String properties use text entries to define settings such as Name, Initial Contents, Short Cue, and Long Cue.
Integer properties use integer entries to define settings such as Control ID, X position, Y position, Height, and Width.
List properties define settings such as Justification, Fore Color, and Back Color that are selected via list box selections. A list
property field can be identified by the drop-down button that is positioned along its right edge. Some of these properties allow
you to choose between the windows system defaults and customized settings defined via common Windows dialogs such as
color palettes and font lists.
Common Flag properties use check boxes to define flags that are common to many types of controls, such as Client Edge,
Raised Edge, Invisible, and Disabled.
Dialog properties define settings such as flags that are established via common Windows dialogs. A dialog property field can
be identified by the ellipsis (...) button that is positioned along its right edge.
3 In the Value column of the properties page, define the control properties, as follows:
• To define string properties, enter a text string. In all controls except tab, grid, INPUTN and INPUTE, Visual PRO/5 interprets \t
and \n in text property entries as a tab and a new line, respectively. To insert a backslash character, use \\.
• To define integer properties, enter a numeric value.
• To define list properties, click the list button, and click the desired property.
• To define common flag options, click the check box to insert a check mark.
• To define dialog properties, click the ellipsis button (...) to display the appropriate Windows dialog.
4 For tab controls, the Tab Number box identifies the tab to be defined in the following box, Tab Number.
5 To display help for properties page entries, click anywhere within the Value column and press F1.
Setting Default Values

Defining a set of default values frees you from the necessity of defining them each time you create a control. The default values
are set via the Set Default Value form, which is similar to the properties page:
184
1 Display the Set Default Value form by doing one of the following:
• On the Edit menu, select Set Default Value.
• On the context-sensitive menu, select Set Default Value.
2 Select the resource type for which to define default values.
3 The defaults will be applied to resources created after the values are set.
Modifying the Tab Order of Controls

Although ResBuilder sets the tab order of controls in the order in which you create them, the program allows you to modify the tab
order.
To modify the tab order, do the following:
1 Click the form or child window.
2 On the Options menu, select Tab Order.
3 A message appears and warns that modifying the tab order also modifies the control ID order.
Visual PRO/5 uses control IDs to process resource events. Modifying the tab order also modifies the control ID
order. If you modify the tab order of a resource file that has been incorporated into a Visual PRO/5 application, the
modified control ID order will prevent the application from functioning properly.
• To proceed to the Change Tab Order dialog, click OK.
• To return to ResBuilder, click Cancel.
4 The Change Tab Order dialog appears, and displays the name and control ID of each control on the form or child window.
185
5 To change the tab order of a control, click the line containing its name and ID, then click Up or Down once for each change
of position within the list. Repeat this step for each control as necessary until you have set up the desired tab order.
6 Accept or cancel the newly defined tab order, as follows:
• To accept the tab order and return to ResBuilder, click Accept.
• To return to ResBuilder without changing the previously defined tab order, click Cancel.
Deleting Controls
To delete individual controls, do the following:
1 Select the control in one of two ways:
• On the Controls toolbar, click the Pointer button, then click the control in the edit area.
• On the tree view, click the control’s icon.
2 Delete the control in one of two ways:
• Press <Delete>.
To delete multiple controls, do the following:
1 On the Controls toolbar, click the Pointer button.
2 Press and hold down <Ctrl>, then click each control in the edit area to be deleted.
3 Delete the control in one of two ways:
• Press <Delete>.
Menus
Creating a Menu Bar

To create a menu bar, do the following:
1 Add a menu window to the edit area by doing one of the following:
186
• On the Main toolbar, click the Add Menu button.
• On the Edit menu, select Add Menu.
• On the tree view, click the Menu icon, right-click to display the context-sensitive menu, then click Add.
2 A menu window containing a blank menu bar then appears, and a corresponding menu icon appears in the tree view.
3 To define the menu bar, display its properties page, then enter the following information:
• Enter a text string into the Menu Text box to define the text that will appear on the menu bar.
• Enter a text string into the Name box to define the menu bar name that will appear in the tree view.
Adding Menus to the Menu Bar

To add menus to the menu bar, do the following:
1 On the left side of the menu bar in the Menu window, a rectangular box serves as a placeholder for the first menu. Click the
box to select it, then display the Properties page.
2 Enter a text string into the Menu text field to set the text that appears on the menu bar.
3 Enter a text string into the Name field to set the name that appears in the tree view. By default, the Pop-up check field is
checked, which allows you to add menu items to the menu. If you do not plan to add menu items to the menu, click the check
box to clear it.
4 To define another menu, click the blank rectangular box that appears to the right of the menu you just defined. Repeat steps
1-3 until you have created the desired number of menus.
Adding Menu Items to Menus

To define menu items that will appear underneath a menu, do the following:
1 On the menu bar in the Menu window, click the rectangular box beneath the desired menu.
2 Enter the following information into the property page:
• To define the text that will appear on the menu item, enter a text string into the Menu Text box To include text that identifies
the accelerator key (for example Ctrl+X),.type \t and enter the text.
• To define the menu item name, enter a text string into the Menu Name box.
• To define the menu item ID, enter an integer into the Menu Item ID box.
• To include the menu item in a pop-up menu, click the Pop-up box.
• To insert a line after the menu item, click the Separator box.
• To set the menu item to be initially enabled and checked, click the Check box.
• To display a check mark to the left of the menu item to be checked when it is enabled, click the Checkable box.
• To define an accelerator key combination for the menu item, click the ellipsis (...) button in the Accelerator Key box to display
the Accelerator Key dialog:
• To set a <Ctrl>, <Alt>, and/or <Shift> key combination with function or cursor movement keys, do the following: Click the
Select from table button, click the desired <Ctrl>, <Alt>, and/or <Shift> check boxes, click the Table box drop down arrow
and select the desired key, and click OK. (Clicking Clear removes the setting.)
• To set a <Ctrl>, <Alt>, and/or <Shift> key combination with a single, printable character, do the following: Click the User
Defined button, click the desired <Ctrl>, <Alt>, and/or <Shift> check boxes, click the User defined field, enter a single key,
and click OK. (Clicking Clear removes the setting.)
3 When you have defined the menu item, click outside the property page. To define another menu item, click the rectangular
box beneath the menu item you have just defined.
4 Repeat steps 2 and 3 until you have created the desired number of menu items.
Attaching Menus to Forms

To attach a menu to a form, do the following:
1 Display the form’s property page.
2 Click the form’s Menu ID box, and enter the integer contained in the menu’s Menu ID box.
187
Image Lists
Creating Image Lists

To create an image list, do one of the following:
• On the Main toolbar, click the Image List button.
• On the tree view, click the Image List icon, right-click to display the context-sensitive menu, then click Add.
The image list file is actually made by joining images of equal width together end-to-end to create a single image. For example,
the following is an imagelist file that consists of seventeen images joined together.
Defining Image Lists

To define an image list, do the following:
1 Click the image list, then do one of the following to display the Image properties page:
• On the Main toolbar, click the Properties button.
• On the tree view, right-click the image list icon to display the context-sensitive menu, then click Properties.
• On the tree view, double-click the image list icon.
2 To enter a name for the image string, enter a text string in the Name box.
3 To enter an image list ID, enter an integer in the Image List ID box
4 To enter the width of the image in current units, enter an integer in the Width box.
5 To define a path and filename for the image list file, click the ellipsis (...) button of the Image List File box to display a
Windows file dialog. Browse through the dialog to locate the desired file and click OK.
Printing
ResBuilder allows you to preview an image of the contents of forms and child windows, set up the printer , and print the image.
ResBuilder Print Preview

To display an image of the contents of forms and child windows, do the following:
1 Click anywhere within a form or child window to select it.
2 On the File menu, select Print Preview to open the standard Windows print preview dialog.
3 The buttons allow you to view successive pages of the image, display one or two pages, zoom in or zoom out, and print the
image.
• To print the image, click the Print button.
• To return to ResBuilder, click the Close button.
Print Setup
To set up the printer from within ResBuilder, do the following:
1 On the File menu, select Print Preview to open the standard Windows print preview setup dialog.
2 Select the desired printer properties, paper size and source, and print orientation settings, then click OK.
Printing
To print the contents of a form or child window in ResBuilder, do the following
1 Click anywhere within a form or child window to select it.
2 Open the Print dialog in one of two ways:
• Press <Ctrl>+P.
3 A confirmation box appears. Do one of the following:
188
• To print the selected item, click OK.
• To return to ResBuilder, click Cancel.
189
RESCOMPILER
Introduction
ResCompiler is a stand-alone executable that compiles an ASCII Resource file (.arc) into a BASIS Resource file (.brf).
Using ResCompiler
Creating binary resource files for use in Visual PRO/5 applications involves the following steps:
1 Create an ASCII resource file in a text editor.
2 Define the following resources:
3 Optionally define preprocessor commands.
4 Run ResCompiler to compile the ASCII resource file.
Resource File Contents and Structure
Resource files create and define resources for use in Visual PRO/5 applications, and contain the following:
Resource File Example

The following resource file defines a window that contains two edit controls. The first line contains the version indicator, followed
by definitions of the window and edit controls and comments. While the window and first edit control contain only the mandatory
definitions, the second edit control contains optional settings.
Version "3.0"
Window 1 "Status" 0 0 200 100
Begin
Edit 1 "OK" 10 10 50 25
//The second edit control contains optional settings
Edit 2 "Done" 50 10 50 25 Begin
Initialcontents "Figures" //Default Contents
Font "Arial" 12, Bold, CS_DEFAULT
Foregroundcolor Rgb(128,255,128)
Backgroundcolor Rgb(64,128,64)
Passwordentry Disabled Invisible Clientedge
Raisededge Passhomedel End
End
Resource File Contents

Version Number
The first line of a resource file must contain the ResCompiler version number. At the time of publication, the current version of
ResCompiler is 3.0.
Mandatory Resource Properties
Resource files can contain definitions for both mandatory and optional properties. The mandatory properties, for example,
resource type, ID number, title, and position, are defined on the first line pertaining to the resource. The following lists the
mandatory properties of the window and two edit controls:
Edit 1 "OK" 10 10 50 25
Edit 2 "Done" 50 10 50 25
190
The following describes the properties listed in the previous example:
Property Resource Entry Description
resource Window Window Identifies each resource, in this case one window
and two edit controls.
First edit control Edit
Second edit control Edit
resource-id Window 1 Defines a unique resource ID number that
identifies the window in the resource file. It must
be an integer between 1 and 32767.
control-id First edit control 1 Defines the control ID number, which must be an
integer between 1 and 32767.
Second edit control 2
“title Window “Status Defines the resource title and is contained in
quotation marks.
First edit control “OK
Second edit control “Done
x Window 0 Defines the horizontal position of the upper-left
corner of the resource in current units.
First edit control 10
y Window 0 Defines the vertical position of the upper-left
corner of the resource in current units.
width Window 200 Defines the width of the resource in current units.
height Window 100 Defines the height of the resource in current units.
Optional Resource Properties
The second and following lines of information pertaining to a resource define its optional properties, for example, color, text
justification, and borders. The following lists the optional properties for the example’s second edit control:
Name Description Type Default Setting
Backgroundcolor Sets the background color of the edit Color System default
control.
Clientedge Creates a recessed client edge around Flag False
the edit control.
Disabled Sets the edit control to be initially Flag False
disabled.
Font Sets the font of the edit control. Font Windows default
Foregroundcolor Sets the foreground color of the edit Color System default
control.
Initialcontents Sets the initial contents of the edit String Null
control.
Invisible Sets the edit control to be initially Flag False
invisible.
Passhomedel Passes the <Home> and <Delete> Flag False
keys as Keypress Notify events.
Raisededge Creates a raised client edge around Flag False
the edit control.
The Resource Properties Index identifies and describes all optional properties for each resource.
191
Comments
ResCompiler ignores all text that follows two forward-slash [//] characters. Comments can either be placed alone on a line or at the
end of a line of code. The following lists the use of comments in the example. The first line contains only comments, while the
second line contains code followed by comments.
// The second edit control contains optional settings
Resource File Structure

Resource file contents are hierarchically structured, as illustrated in the following example. Top level resources include windows,
referenced menus, and referenced child windows. Lower level resources are nested within top-level resources. Nesting levels are
defined by either "begin" and "end" or by "{" and "}".
Version "3.0"
Window 1 "Status" 0 0 200 100 //This is a top level resource.
Begin
Edit 1 "OK" 10 10 50 25 //This is a lower level resource.
//The second edit control contains optional settings
Edit 2 "Done" 50 10 50 25 Begin //This is a lower level resource.
Raisededge Passhomedel End
End
Property Types
ResCompiler uses the following property types to define resources:
• String Properties
• Integer Properties
• Flag Properties
• Color Properties
• Font and Justification Properties
• Character Properties
The Resource Properties Index identifies and describes all properties contained in this section.
Common Properties Example
The following lists common properties for button and edit controls:
Version "3.0"
Begin Not Sizable
Button 1 "OK" 10 10 50 25 Begin Justification
JUSTIFICATION_LEFT end
edit 1 "Done" 50 10 50 25 Begin
Initialcontents "The first initalcontents line\n"
"The second initalcontents line\n"
192
Justification $2000$
Backgroundcolor Color_magenta
Disabled Invisible Clientedge Vscrollbar
Hscrollbar End
End
String Properties
String properties define name, title, mask, and default text entries for resources. String properties are always contained in double
quotes. Null is the default setting for all string properties. In the example, "Status" defines the title text of Window 1, while "OK"
and "Done" define the title text for the edit and button controls, respectively.
Integer Properties
Integers set numeric value-related definitions such as resource size, position, number of columns, and tab height. In the example,
integer properties define the size and position of the window button and edit controls. For the window, the settings 50, 250, 250,
and 125 define in current units the horizontal and vertical positions of the upper-left corner, width, and height, respectively. Default
settings for integer properties are listed in the Resource Properties Index.
Flag Properties
Flag (“Boolean) properties define a wide range of resource settings. For example, they are used to include scroll bars and titles in
windows, set controls to be initially disabled or invisible, replace input text with asterisks, and set menu items to be initially
checked. Flag properties are designated as true or false by default.
The following guidelines apply to flag properties:
• Properties designated as false by default will not be applied, unless the property name is included in the resource definition.
• Properties designated as true by default will be applied, unless NOT and the property name are included in the resource
definition.
• Properties for a single resource can be entered on more than one line.
In the example, because the Disabled, Invisible, Clientedge, Vscrollbar, and Hscrollbar properties are false by
default, they are only applied if they are included in the resource definition. Because the Sizeable property is true by default, it
is only excluded if Not Sizeable is included in the resource definition.
Color Properties
Color properties define the foreground and background colors of resources. To define colors, use the predefined color name listed
in the stdincl.h file or use the RGB value.
In the example, the settings Foregroundcolor Rgb(128,255,128) and Backgroundcolor Color_magenta illustrate
colors defined by RGB values and predefined color names, respectively. The Predefined Constants section identifies and
describes the predefined color properties.
Font and Justification Properties
Font and justification properties define the attributes of text contained or entered into resources. Font properties define the text
font, point size, style, and character set. Justification properties define the alignment of text within the control.
Font Properties
The following lists the font property syntax:
"Fontname" pointsize{,style{,charset}}
In the example, the Font "Arial" 12, Bold, CS_DEFAULT settings define the text font, point size, style, and character set.
ResCompiler uses the Window-defined font and point size, normal style, and ANSI character sets as defaults and supports
normal, bold, italic, strikeout, and underline text styles. The Predefined Constants section identifies and describes the predefined
character set options. Style settings are only required if a nondefault character set is used.
Justification Properties
The following lists the justification syntax:
Justification setting
In the example, the Justification $2000$ and Justification JUSTIFICATION_LEFT settings define the alignment
of text in the button and edit controls, respectively. The Predefined Constants section identifies and describes the hex value and
predefined justification settings.
193
Character Properties
Character properties define row and column separations in grid controls and line separations in the Initialcontents settings
of all text entry controls.
In the example, \n forces a line break in the edit control Initialcontents lines.
Defining Windows
This section provides the mandatory and optional properties and sample resource file examples for the following window
resources:
• Windows and Dialogs
• Event Masks
• Status Bars
The Resource Properties Index identifies and describes the optional properties for windows, dialogs, and status bars. The
Predefined Constants section identifies and describes the event mask settings.
Windows and Dialogs

Windows serve as the principal resource placeholders. All resources contained within a window are nested within the window’s
resource file description. A window can also serve as a dialog box.
The following lists the mandatory properties for windows and dialogs:
Window resource-id "title" x, y, width, height
The following describes the window and dialog properties:
Property Definition
Window Identifies the resource as a window.
resource-id Defines a unique resource ID number that identifies the window in the resource file. The ID number
must be an integer between 1 and 32767.
"title" Defines the control title and is always contained in quotation marks.
x Defines the horizontal position of the upper-left corner of the control in current units.
y Defines the vertical position of the upper-left corner of the control in current units.
width Defines the width of the control in current units.
height Defines the height of the control in current units.
Example
The following example contains three windows: the first contains only the mandatory definitions, the second contains dialog box
settings, and the third contains optional settings.
Version "3.0"
Window 1 "First Window" 0 0 200 100
Window 2 "Second Window" 0 0 200 100 Begin
Name "Dialog Box"
currentunits UNITS_PIXELS
Backgroundcolor $0f0f05$
Foregroundcolor $01070c$
Defaultfont "Timesroman" 14, Bold Italic, CS_DEFAULT
Alwaysontop Dialogbehavior Dialogborder
Keyboardnavigation Gravity
Not Sizable Not Minimizable
194
Eventmask $ffff$
Button 1 "OK" 10 10 50 25
End
Window 3 "Third Window" 0 0 200 100
Begin
Button 1 "OK" 10 10 50 25 Begin
End
Checkbox 2 "Done" 10 10 50 25 Begin
End
End
Current Units Settings

Setting the current units determines the unit type for a window and its contained controls and elements. This is set at the window
level only. Use the following settings rather than the numbers contained in the stdincl.h file:
Unit Type Current Unit Setting
Pixels currentunits UNITS_PIXELS
Characters currentunits UNITS_CHARS
Semicharacters currentunits UNITS_SEMICHARS
Dialog Box Settings

Setting the following properties defines a window as a dialog box:
Alwaysontop, Dialogbehavior, Dialogborder, Gravity, Keyboardnavigation, Not Maximizable, and Not
Sizable.
Event Masks
Event masks filter the events reported by the current window. To prompt the window to report only specific events, all events, or a
combination of events, use the logical operators “| (OR), “~ (NOT), “& (AND), and parentheses to group elements of the
expression. Predefined Constants identifies and describes the event mask settings.
The following contains two examples that illustrate event mask properties. The first example defines three individual event masks,
while the second defines all events except mouse events.
Version "3.0"
// Example 1
Window 1 "Order Main Window" 50 250 250 125
Begin
…
// Only Focus, Resize, And Mouse Move Events
Eventmask EM_FOCUS | EM_RESIZE |EM_MOUSEMOVE
End
// Example 2
Window 1 "Order Main Window" 50 250 250 125
Begin
…
Eventmask EM_ALL & ~(EM_MOUSEDOWN | EM_MOUSEMOVE|
EM_MOUSEDOUBLE| EM_MOUSEUP)
End
195
Status Bars
Status bars are located at the bottom of a window and display information about a process, menu command, or selection.
The following lists the mandatory properties for status bars:
Statusbar control-id
The following describes the scroll bar properties:
Property Description
Statusbar Defines the resource as a status bar.
control-id An integer between 1 and 32767 that defines the status bar ID number. The number must be
unique within the top-level window.
The following example contains a window with two status bars: the first contains only the mandatory definitions, while the second
also contains optional settings.
Version "3.0"
Window 1 "Basic Statusbar Window" 25 25 250 150
Begin
Statusbar 5
End
Window 2 "Fully-Loaded Statusbar Window" 25 25 250 150
Begin
Statusbar 6 Begin
Backgroundcolor $ffccff$
Font "Arial" 12, Bold, 0
Justification JUSTIFICATION_CENTER
Longcue "Longcue Status Bar Control?"
Shortcue "Remarks"
Name "Statbar" Disabled Invisible
End
End
Defining Menus
This section provides the mandatory properties for menu bars, menus, and menu items. Additionally, it provides sample files to
illustrate resource file menu definitions.
The Resource Properties Index identifies and describes the optional properties for all resources contained in this section.
Menu bars are either assigned as placeholders for which menus can be created at runtime, or are directly or indirectly defined
within the resource file.
Menu Bars
Default Menu Bars
The default menu bar serves as a placeholder for which menus can be created at runtime through a standard section of code and
is defined as follows:
Menubar Default
Directly- and Indirectly-Defined Menu Bars

The following describes the differences between directly-defined and indirectly-defined menu bars:
• Definitions for directly-defined menu bars are listed within the nested structure of top-level windows. Directly-defined menu
bars do not need menu ID numbers because they cannot be shared with other windows.
196
• Definitions for indirectly-defined menu bars consist of two components: a menu bar definition that is a separate top-level
resource, and a reference within the nested structure of the top-level window that points to the definition. Indirectly-defined
menu bars can be shared with other windows.
Directly-Defined Menu Bars

The following lists the mandatory properties for directly-defined menu bars:
Menubar
Begin
...
End
The following describes the menu bar properties:
Menubar Defines the resource as a menu. Directly-defined menu bars do not require ID numbers.
Indirectly-Defined Menu Bars

As described above, indirectly-defined menu bar definitions are comprised of two components. The following lists the mandatory
properties for the reference component of indirectly-defined menu bars:
Menubar menu-resource-id
The following describes the menu bar properties:
Menubar Defines the resource as a menu bar.
menu-resource-id Defines the menu resource ID.
Example
The following example contains three windows. Window 2 contains a directly-defined menu bar. Window 3 contains an indirectly-
defined menu bar. Window 4 contains a default menu bar that is empty and serves as a placeholder.
version "3.0"
window 2 "Second window" 3 13 200 100 begin
eventmask EM_ALL
menubar begin //Directly-defined menu bar
menu-item 1001 "&File" begin
menu-item 1011 "&Open"
menu-item 1012 "&Save"
menu-item 1013 "E&xit"
end
menu-item 1002 "&Edit" begin
menu-item 1021 "&Cut"
menu-item 1022 "C&opy"
menu-item 1023 "&Paste"
end
end
end
window 3 "Third window" 10 20 200 100
begin
menubar 1000 //Indirectly-defined menu bar reference
button 1 "OK" 10 10 50 25
197
checkbox 2 "Done" 10 10 50 25
end
window 4 "Forth window" 10 20 200 100
begin
menubar default //sets menu status for this window
button 1 "OK" 10 10 50 25
checkbox 2 "Done" 10 10 50 25
end
menu 1000 begin //Indirectly-defined menu bar definition
menu-item 1001 "&File"
begin
separator
end
menu-item 1002 "&Edit"
begin
menu-item 1020 "&Undo"
separator
menu-item 1021 "&Cut"
menu-item 1022 "C&opy"
menu-item 1023 "&Paste"
end
menu-item 1003 "&Options"
begin
menu-item 1031 "&Disabled" begin disabled end
menu-item 1032 "&CheckMe" begin checkable end
menu-item 1033 "&ImChecked" begin checkable checked end
end
end
menu 2000
begin
menu-item 1001 "&File"
begin
begin
begin
menu-item 1013 "&Save As"
begin
menu-item 1014 "&Restore"
begin
198
menu-item 1015 "&Restore As"
begin
menu-item 1016 "&Print"
begin
menu-item 1017 "&Print Setup"
begin
menu-item 1018 "&Oops"
begin
menu-item 1019 "&Exit"
end
end
end
end
end
end
end
end
end
end
Menus
A menu consists of a list of pull-down command options accessed from the menu bar. The following lists the mandatory properties
for menus:
Menu resource-id
Begin
Menu-item menu-id "title" {accelerator-key}
...
End
The following describes the menu properties:
Menu Identifies the resource as a menu. (Specified once only.)
resource-id Defines the resource ID number and must be an integer between 1 and 32767. (Specified
once only.)
Menu-item Defines the resource as a menu item. (Specified for each menu item.)
menu-id Defines the menu ID number and must be an integer between 1 and 32767. (Specified for
each menu item.)
“title Defines the menu item title contained in quotation marks. (Specified for each menu item.)
accelerator-key Defines optional key combination settings that provide quick access to commands.
Menu items defined between begin and end statements are positioned on the same level. Submenus positioned between begin
and end statements are positioned on the next level.
Accelerator Keys
Accelerator keys are key combinations that provide quick access to commands. Although accelerator key settings are optional,
they are defined on the mandatory properties line of a menu. To specify the text of the accelerator key, separate the text of the
menu item and the accelerator label with a tab character in the title.
199
Accelerator keys can also be defined by using regular characters enclosed in single quotation marks. The modifiers <Ctrl>,<Alt>,
and <Shift> can be used with either method.
Key(s) Hex Code Character Code
<Ctrl>+f $2066$ <Ctrl> + ‘f’
<F1> $014B$ or KEY_F1 none
<Up Arrow> $012D$ or KEY_UP_ARROW none
<Shift>+6 $1036$ or $005E$ <Shift> + ‘6’ or ‘^’
<Alt>+x $4078$ <Alt> + ‘x’
<Ctrl>+<Alt>+<Shift>+6 $7036$ or $605E$ <Ctrl> + <Alt> + <Shift> + ‘6’ or
<Ctrl> + <Alt> + ‘^’
The following example defines a menu item with an ID of 10001, a title of “Open, and accelerator keys of <Ctrl>+O.
Menu-item 10001 "&Open..." "\tCtrl+O" ctrl+’o’
Menu items that are defined between begin and end statements are positioned on the same level. Submenus are positioned on
the next level.
Separators
Separators are denoted by the word SEPARATOR where a menu item would be placed.
Defining Child Windows

This section describes the mandatory properties and syntax for child windows and includes sample files that illustrate child window
definitions.
Child windows share certain attributes with top-level windows; both can possess borders, scroll bars, controls, and other child
windows (with no limit to the nesting depth for child windows). Child windows can also use the same event mask options as top-
level windows. Unlike top-level windows, child windows cannot contain menus or title bars.
Child windows inherit their default font and units properties from the parent windows and can be either directly or indirectly
defined. The following identifies the differences between directly- and indirectly-defined child windows:
• Definitions for directly-defined child windows are listed within the nested structure of top-level windows. Directly-defined child
windows cannot be shared with other windows. The child window ID number must be unique within a resource file.
• Definitions for indirectly-defined child windows consist of two components: a child window definition that is a separate top-
level resource, and a reference within the nested structure of the top-level window that points to the definition. Indirectly-
defined child windows can be shared with other windows.
Directly-Defined Child Windows

The following lists the mandatory properties for directly-defined child windows:
child-window window-id x y width height
The following describes the child window properties:
child-window Defines the resource as a child window.
window-id Defines the child window ID number. The number must be an integer between 100 and 32767 but
cannot be the same as other controls or child windows in a top-level window.
x Defines the location of the horizontal position of the upper-left corner of the child window in current
units.
y Defines the location of the vertical position of the upper-left corner of the child window in current
units.
width Defines the width of the child window in current units.
height Defines the height of the child window in current units.
200
Indirectly-Defined Child Windows
Indirectly-defined child windows definitions are comprised of two components: the reference component, and the definition
component. The following lists the mandatory properties for the reference component of indirectly-defined child windows:
Child-window resource-id window-id x y
resource-id Defines the ID number of the referenced child window.
window-id Defines the child window ID number. The number must be an integer between 100 and 32767
but cannot be the same as other controls or child windows in a top level window.
x Defines the location of the horizontal position of the child window in current units.
y Defines the location of the vertical position of the child window in current units.
The following lists the mandatory properties for the definition component of indirectly-defined child windows:
Child-window resource-id width height
resource-id Defines the child window resource ID number and must be an integer between 1 and 32767.
width Defines the width of the child window in current units.
height Defines the height of the child window in current units.
For indirectly-defined child windows, the x and y parameters in the reference component are not defined because the reference
determines the location of the child window. In the reference component, the context should be the same as the window ID. The
child window IDs must be unique within a resource file.
Example
The following example contains two windows: the first window contains a directly-defined child window, and the second window
contains an indirectly-defined child window:
Child Window Example
Version "3.0"
Window 1000 "First Window" 0 0 400 200
Begin
Button 1 "OK" 10 10 50 25
Checkbox 2 "Done" 10 10 50 25
//Directly Defined Child Window
Child-window 5000 0 0 100 100
Begin
Button 1 "OK" 10 10 50 25
End
End
Window 2000 "Second Window" 0 0 400 200
Begin
Button 1 "OK" 10 10 50 25
//Reference to Indirectly-Defined Child Window
201
Child-window 3000 3000 0 0
End
//Indirect definition of Child Window
Child-window 3000 100 100 begin
Button 1 "OK" 10 10 50 25
End
Defining Controls
This section provides the mandatory properties and syntax for each control and provides sample resource files that illustrate
examples of control definitions
Lines and images are considered elements. Although their display properties can be defined, they cannot interact with other
controls, forms, child windows, or other resources.
The Resource Properties Index identifies and describes the optional properties for all controls contained this section.
Mandatory Control Properties

The following properties are mandatory for all controls except the line element:
control_type Specifies the control type, for example, EDIT, BUTTON, CHECKBOX.
control-id Defines the control ID number. The number must be an integer between 1 and 32767 and be
unique within a given top-level window.
Button Controls
The following lists the mandatory properties for button controls:
Button control-id "title" x y width height
button Specifies the control as a button control.
The Resource Properties Index identifies and describes the optional properties for this control.
Example
The following example contains a window with two button controls: the first contains only the mandatory definitions, and the
second contains optional settings.
Version "3.0"
Window 1 "Control Window" 0 0 200 100
202
Begin
Button 1 "OK" 10 10 50 25
Button 2 "Done" 50 10 50 25 Begin
Shortcue "Short Cue"
Longcue "Long Cue"
Backgroundcolor $debabe$
Foregroundcolor $ccffcc$
Clientedge Raisededge
Justification JUSTIFICATION_LEFT
End
End
Check Box Controls

The following lists the mandatory properties for check box controls:
Check Box Control Mandatory Properties
Checkbox control-id "title" x y width height
checkbox Specifies the control as a check box control.
Example
The following example contains a window with two check box controls: the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Checkbox 1 "OK" 10 10 50 25
Checkbox 2 "Done" 50 10 50 25 Begin
Checked Group Clientedge Raisededge
Justification $2000$
End
End
203
Custom Edit Controls
The following lists the mandatory properties for custom edit controls:
Customedit control-id "title" x y width height
customedit Specifies the control as a custom edit control.
Example
The following example contains a window with two custom edit controls: the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Customedit 1 "OK" 10 10 50 25
Customedit 2 "Done" 50 10 50 25 Begin
Initialcontents "Some Really Long Contents\n"
"A Second Line Of Contents\n"
"A Third Line Of Contents\n"
"A Fourth Line Of Contents\n"
Readonly Wordwrap Vscrollbar Hscrollbar Border
Oneparagraph Overstrike
Ignoretabs Clientedge
End
End
Edit Controls
The following lists the mandatory properties for edit controls:
Edit control-id "title" x y width height
edit Specifies the control as an edit control.
204
Example
The following example contains a window with two edit controls: the first contains only the mandatory definitions, and the second
contains optional settings.
Version "3.0"
Begin
Edit 1 "OK" 10 10 50 25
Edit 2 "Done" 50 10 50 25 Begin
Initialcontents "Editbox Contents"
Raisededge Passhomedel
End
End
Grid Controls
The following lists the mandatory properties for grid controls:
Grid control-id "title" x y width height
grid Specifies the control as a grid control.
Example
The following example contains a window with two grid controls: the first contains only the mandatory definitions, and the second
contains optional settings.
Version "3.0"
Begin
Grid 1 "OK" 10 10 50 25
Grid 2 "Done" 50 10 50 25 Begin
205
Initialcontents "(1,1):(1,2):(1,3):(1,4):(1,5)-"
"(2,1):(2,2):(2,3):(2,4):(2,5)-"
"(3,1):(3,2):(3,3):(3,4):(3,5)-"
"(4,1):(4,2):(4,3):(4,4):(4,5)-"
"(5,1):(5,2):(5,3):(5,4):(5,5)-"
Rows 5
Columns 5
Maxcols 5
Interspace 2
Font "Helvetica" 12, Bold, CS_DEFAULT
Columnhead 24, 3
Rowhead 24, 4
Usersize Clientedge Raisededge Horizlines
Vertlines Disabled Invisible
End
End
Group Box Controls

The following lists the mandatory properties for group box controls:
Groupbox control-id "title" x y width height
Groupbox Specifies the control as a group box control.
Example
The following example contains a window with two group box controls; the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Groupbox 1 "Group One" 10 10 50 25
Groupbox 2 "Group Two" 50 10 50 25 Begin
Invisible Disabled Clientedge Raisededge
206
End
End
Image Elements
The following lists the mandatory properties for image elements:
Image control-id x y width height
image Specifies the control as an image element.
Example
The following example contains a window with three image elements; the first contains only the mandatory definitions, and the
second and third contain optional settings.
Version "3.0"
Begin
Image 1 10 10 50 25
Image 2 50 10 50 25 Begin
Imagefile "\\images\\tool.bmp"
Invisible
End
Image 3 50 10 50 25 Begin
Image "872146213094791238648621386482136482718"
Invisible
End
End
INPUTE Controls
The following lists the mandatory properties for INPUTE controls:
Inpute control-id "title" x y width height
inpute Specifies the control as an INPUTE control.
207
Example
The following example contains a window with three INPUTE controls; the first contains only the mandatory definitions, and the
second and third contain optional settings.
Version "3.0"
Begin
Inpute 1 "Hello" 10 10 50 25
Inpute 2 "Goodbye" 50 10 50 25 Begin
Initialcontents "(000) 555 1212"
Initialposition 15
Mask "(###) ### ####"
Padcharacter '\n'
Restorestring "(000) 555 1212"
Disabled Invisible Passtab Passenter Highlight
End
Inpute 3 "" 50 10 50 25 Begin
Maxlength 15
Padcharacter '\n'
End
End
INPUTN Controls
The following lists the mandatory properties for INPUTN controls:
Inputn control-id "title" x y width height
inputn Specifies the control as an INPUTN control.
Example
The following example contains a window with two INPUTN controls; the first contains only the mandatory definitions, and the
208
Version "3.0"
Begin
Inputn 1 "Hello" 10 10 50 25
Inputn 2 "Goodbye" 50 10 50 25 Begin
Initialcontents "(000) 555 1212"
Initialposition 15
Imask "(###) ### ####"
Omask "(###) ### ####"
Rightmostentry Copycommas Decimalreplace Beep
End
End
Line Elements
The following lists the mandatory properties for line elements. The x1, y1, x2, and y2 properties define the location of the starting
and ending points of the line:
Line control-id x1 y1 x2 y2
Example
The following example contains a window with two line elements; the first contains only the mandatory definitions, while the
Version "3.0"
Begin
Line 1 10 10 50 25
Line 2 50 10 50 25 Begin
Name "Line2"
Linewidth 2
Linestyle 2
Foregroundcolor Color_red
End
End
List Box Controls

The following lists the mandatory properties for list box controls.
Listbox control-id "title" x y width height
listbox Specifies the control as a list box control.
209
Example
The following example contains a window with two list box controls; the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Listbox 1 "OK" 10 10 50 25
Listbox 2 "Done" 50 10 50 25 Begin
Initialcontents "Item1\nitem2\nitem3\nitem4\n"
Multiselect Clientedge Raisededge Disabled
Invisible
Readonly
End
End
List Button Controls

The following lists the mandatory properties for list button controls.
Listbutton control-id "title" x y width height
listbutton Specifies the control as a list button control.
Example
The following example contains a window with two list button controls; the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Listbutton 1 "OK" 10 10 50 25
210
Listbutton 2 "Done" 50 10 50 25 Begin
End
End
List Edit Controls

The following lists the mandatory properties for list edit controls.
Listedit control-id "title" x y width height
listedit Specifies the control as a list edit control.
Example
The following example contains a window with two list edit controls; the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Listedit 1 "OK" 10 10 50 25
Listedit 2 "Done" 50 10 50 25 Begin
End
End
Radio Button Controls

The following lists the mandatory properties for radio button controls.
Radiobutton control-id "title" x y width height
radiobutton Specifies the control as a radio button control.
211
Example
The following example contains a window with two radio button controls; the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Radiogroup 1, 2
Radiobutton 1 "OK" 10 10 50 25
Radiobutton 2 "Done" 50 10 50 25 Begin
Group Checked Clientedge Raisededge
End
End
Radiogroup Option
The radio button control has an optional setting that can be used to group buttons within a window definition. A radio button can
only be a member of one radio group. All radio buttons that are not part of a specific radio group are considered to be in a group
by themselves. The following lists the radiogroup option syntax:
radiogroup control_id, control_id...
Radiogroup Option Example

The following example defines a window that contains six radio buttons. Radio buttons 1 and 2 are contained in one radiogroup,
while radio buttons 5, 6, 7, and 8 are contained in another radiogroup:
Version "3.0"
Window 1 "First Window" 0 0 200 100 Begin
Radiogroup 1, 2
Radiobutton 2 "Done" 50 10 50 25
Button 3 "OK" 10 10 50 25
Radiogroup 5,6,7,8
212
End
Scroll Bar Controls

The following lists the mandatory properties for scroll bar controls:
Scrollbar control-id x y width height
scrollbar Specifies the control as a scroll bar control.
Example
The following example contains a window with two scroll bar controls; the first contains only the mandatory definitions, and the
second contains optional settings, including definitions for both vertical and horizontal scroll bars:
Version "3.0"
Begin
Scrollbar 1 10 10 50 25
Scrollbar 2 50 10 50 25 Begin
Initialposition 0
Initialproportion 10
Initialsize 100
Orientation Vertical
Disabled Invisible Clientedge Raisededge
End
Scrollbar 2 50 10 50 25 Begin
Initialposition 0
Initialproportion 10
Initialsize 100
Orientation Horizontal
Disabled Invisible Clientedge Raisededge
End
End
Static Text Controls

The following lists the mandatory properties for static text controls:
Statictext control-id "title" x y width height
213
statictext Specifies the control as a static text control.
Example
The following example contains a window with two static text controls; the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Statictext 1 "OK" 10 10 50 25
Statictext 2 "Done" 50 10 50 25 Begin
Invisible Clientedge Raisededge
Initialcontents "More Static Text"
End
End
Tab Controls
The following lists the mandatory properties for tab controls:
Tabcontrol control-id "title" x y width height
tabcontrol Specifies the control as a tab control.
Defining Tabs
The following lists the mandatory properties for tabs contained within tab controls:
Tab "title" imagelist-index childwindow-or-control-id
The following describes the tab properties:
Tab Identifies the control as a tab.
214
"title" Defines the tab’s title, contained in quotation marks.
imagelist-index Defines an integer that represents the index value of an image list.
childwindow-id or control-id Defines the ID of the child window or control.
Attributes and flags used in child window definitions can also be used in tab definitions.
Example
The following example contains a window with two tab controls; the first contains only the mandatory definitions, and the second
contains optional settings. The second tab control contains three tabs:
Version "3.0"
Begin
Tabcontrol 1 "Tab Control 1" 10 225 100 50
Tabcontrol 2 "Tab Control 2" 50 10 300 200
Begin
Initialtab 0
Width 400
Height 200
Verticalpadding 15
Horizontalpadding 15
Imagelist "\\foo.bmp"
Automanagement
Buttons Fixedwidth Focusnever
Focusonbuttondown Forceiconleft Multiline
Raggedright Rightjustify
Singleline Clientedge Raisededge
Tab "Tab 1" 0 1000
Tab "Tab 2" 1 2000
Tab "Tab 3" 2 3000
End
End
Child-window 1000 100 100
Begin
Button 1 "OK" 10 10 50 25
End
Begin
Button 1 "Yes" 10 10 50 25
End
Begin
Button 1 "Finish" 10 10 50 25
End
215
Tool Button Controls
The following lists the mandatory properties for tool button controls:
Toolbutton control-id "title" x y width height
toolbutton Specifies the control as a tool button control.
Example
The following example contains a window with two tool button controls; the first contains only the mandatory definitions, and the
Version "3.0"
Begin
Toolbutton 1 "OK" 10 10 50 25
Toolbutton 2 "Done" 50 10 50 25 Begin
End
End
Preprocessor Commands and Predefined Constants
Preprocessor Commands
A preprocessor command removes comments from the source code; expands macros; performs conditional inclusions; and
includes other files. It is separated from the programming language itself and takes effect before the file is compiled.
ResCompiler supports the preprocessor commands listed in the following table. All preprocessor command statements must:
• Begin with a pound (#) sign (except defined(name)).
• Contain only the preprocessor command.
• Be written in lower case (except for strings enclosed in quotes).
Command Description
#define name Defines the name as 1.
#define name value Sets name to value. If value contains other preprocessor values, they are expanded
and used. The value can be either numeric, for example, -Dversion=5, or a string
enclosed in quotes such as -Dname=“Order.
#undef name Undefines the specified macro.
#if expression If the expression evaluates to a nonzero value, the expression is true, and the code
following the #if expression is included in the resource file.
216
If the expression evaluates to zero, the expression is false, and the code following the
#else statement, up to a #endif statement, is included in the resource file.
If there is no #else defined, then no code is executed.
Expressions can be complete algebraic expressions and can include arithmetic
operators (+,-,*, and /), flag operators (&&, ||, and ~), and use parentheses for
grouping.
#else Defines the code to be compiled in an #if expression if the expression is false.
#endif Ends an #if or #else code section.
defined(name) This can be used in an #if expression. If the specified name is currently defined, the
defined macro expands to 1, otherwise it expands to 0.
#include "filename" Inserts the file specified by filename at the point the preprocessor is specified. The
current directory is searched first followed by the directories given in the -I command
line option in the order specified. A maximum of 32 files can be included.
Predefined Constants
This section lists the predefined constants listed in the stdincl.h file located in the ResCompiler home directory
Accelerator Key Constants

Key Description Setting–Text Setting–Hex
<Tab> KEY_TAB $0009$
<Escape> KEY_ESCAPE $001B$
<Delete> KEY_DELETE $007F$
<Up Arrow> KEY_UP_ARROW $012D$
<Down Arrow> KEY_DOWN_ARROW $012E$
<Right Arrow> KEY_RIGHT_ARROW $012F$
<Left Arrow> KEY_LEFT_ARROW $0130$
<Page Up> KEY_PAGE_UP $0131$
<Page Down> KEY_PAGE_DOWN $0132$
<Home>* KEY_HOME $0133$
<End>* KEY_END $0134$
<Ctrl>+<Home> KEY_CTRL_HOME $0135$
<Ctrl>+<End> KEY_CTRL_END $0136$
<Insert> KEY_INSERT $0138$
<Ctrl>+<Right Arrow> KEY_CTRL_RIGHT_ARROW $0139$
<Ctrl>+<Left Arrow> KEY_CTRL_LEFT_ARROW $013A$
<Backtab> KEY_BACKTAB $013B$
<Keypad 0> KEY_KEYPAD_0 $013E$
<Keypad 1> KEY_KEYPAD_1 $013F$
<Keypad 2> KEY_KEYPAD_2 $0140$
217
<F1> KEY_F1 $014B$
<F2> KEY_F2 $014C$
<F3> KEY_F3 $014D$
<F4> KEY_F4 $014E$
<F5> KEY_F5 $014F$
<F6> KEY_F6 $0150$
<F7> KEY_F7 $0151$
<F8> KEY_F8 $0152$
<F9> KEY_F9 $0153$
<F10> KEY_F10 $0154$
<F11> KEY_F11 $0155$
<F12> KEY_F12 $0156$
<Keypad asterisk (*)> KEY_KEYPAD_STAR $0174$
<Keypad minus sign (-)> KEY_KEYPAD_MINUS $0175$
<Keypad plus sign (+)> KEY_KEYPAD_PLUS $0176$
<Keypad forward slash (/)> KEY_KEYPAD_SLASH $0177$
<Shift> KEY_SHIFT $1000$
<Ctrl> KEY_CTRL $2000$
<Alt> KEY_ALT $4000$
* In the GUI Guide, the hex key settings for the <Home> and <End> keys were incorrectly defined as $0135$ and $0136$,
respectively.
Character Set Constants

Character Set Platform Value Setting–Text
ANSI All Windows 0 CS_ANSI
DEFAULT All Windows 1 CS_DEFAULT
SYMBOL All Windows 2 CS_SYMBOL
SHIFTJIS All Windows 3 CS_SHIFTJIS
HANGEUL All Windows 4 CS_HANGEUL
GB2312 All Windows 5 CS_GB2312
CHINESEBIG5 All Windows 6 CS_CHINESEBIG5
OEM All Windows 7 CS_OEM
JOHAB Windows 95 only 8 CS_JOHAB
HEBREW Windows 95 only 9 CS_HEBREW
ARABIC Windows 95 only 10 CS_ARABIC
GREEK Windows 95 only 11 CS_GREEK
TURKISH Windows 95 only 12 CS_TURKISH
THAI Windows 95 only 13 CS_THAI
EASTEUROPE Windows 95 only 14 CS_EASTEUROPE
RUSSIAN Windows 95 only 15 CS_RUSSIAN
BALTIC Windows 95 only 16 CS_BALTIC
MAC Macintosh 17 CS_MAC
218
Color Name Constants
Color Setting–Text Setting–RGB Specification
Black COLOR_BLACK RGB(0,0,0)
Blue COLOR_BLUE RGB(0,0,255)
Cyan COLOR_CYAN RGB(0,255,255)
Dark Gray COLOR_DKGRAY RGB(64,64,64)
Gray COLOR_GRAY RGB(128,128,128)
Green COLOR_GREEN RGB(0,255,0)
Light Gray COLOR_LTGRAY RGB(192,192,192)
Magenta COLOR_MAGENTA RGB(255,0,255)
Red COLOR_RED RGB(255,0,0)
White COLOR_WHITE RGB(255,255,255)
Yellow COLOR_YELLOW RGB(255,255,0)
Current Unit Constants

Unit Setting–Text Value
Pixel UNITS_PIXELS 0
Char UNITS_CHARS 1
Semichar UNITS_SEMICHARS 2
Event Mask Constants

Event(s) Reported Setting–Text
Activation messages. EM_ACTIVATE
All events. EM_ALL
Check box or radio button check or uncheck. EM_CHECK
Window close. EM_CLOSE
Edit or list edit modified EM_EDITMODIFY
Edit, list edit, or custom edit focus change. EM_EDITFOCUS
Focus movement in or out of a window. EM_FOCUS
Key press. EM_CHAR
List item click or double-click. EM_LISTCLICK
Mouse button press. EM_MOUSEDOWN
Mouse button release. EM_MOUSEUP
Mouse double-click. EM_MOUSEDOUBLE
Mouse movement. EM_MOUSEMOVE
None. EM_NONE
Scroll bar position changed by clicking the scroll bar arrows. EM_SCROLLPOS
Scroll bar position by dragging the scroll bar thumb. EM_SCROLLTRACK
System events. EM_SYSEVENT
Window resize. EM_SIZE
Scroll Bar Orientation Constants

Scroll Bar Setting–Text Value
219
Vertical VERTICAL 0
Horizontal HORIZONTAL 1
Text Justification Constants

Justification Setting–Hex Setting–Text
Native (or Default) $0000$ JUSTIFICATION_NATIVE
Left $2000$ JUSTIFICATION_LEFT
Center $4000$ JUSTIFICATION_CENTER
Right $8000$ JUSTIFICATION_RIGHT
Running ResCompiler
ResCompiler is a stand-alone executable that “compiles an ASCII Resource file (.arc) into a BASIS Resource file (.brf).
To run ResCompiler, enter the following command:
rescomp {command_line_options} input_files
command_line_options Command line options, contained in the table below.
input_files ASCII resource files to be compiled.
Command Line Guidelines

The following guidelines apply to ResCompiler command lines:
• Enter all command line information on one line.
• Command line options and input files can be specified in any order, but command line options do not have to be specified
before input files.
• Input files typically have an .arc (ASCII resource file) extension, while output files typically have a .brc. (binary resource
file) extension.
• If the command line options do not specify an output filename for an input file coming from stdin, the output file will be
named stdin.brc.
Command Line Options

The following command line options can be used to modify and/or limit ResCompiler operations, according to 5he following
guidelines:
• All command line options are case sensitive.
• The -n and -v options are global options and affect all resource files, regardless of location on the command line.
• The -D, -I, and -U command line options take effect in the order specified on the command line.
Option Description
-Dname Defines the name.
-Dname=value Defines the name as a value. The value can be either numeric, for example, -Dversion=5, or a string
enclosed in quotes, such as -Dname=“Order.
-Idirectoryname Adds an additional directory to the list of directories ResCompiler searches for include files. The current
directory is searched first. Forward slashes should be used in the paths. Currently, limited to 32 directory
names.
-n Instructs ResCompiler to check only the syntax. No binary resource files are created.
-ooutfilename Specifies the output file name of the binary resource file. This option can only be used with a single input
file or when reading from the stdin file. Only a single -o option is allowed per command line.
-p Causes ResCompiler to pause until the <Enter> key is pressed if an error occurs. This is useful when
invoking ResCompiler from the interpreter with an SCALL() function.
220
-Uname Undefines a name. This happens after stdincl.h has been loaded but before the file is preprocessed.
-v Displays the ResCompiler version and copyright information.
- Indicates that the input file comes from stdin and is used in place of a file name.
Example
The following command starts ResCompiler and defines the DEBUG symbol for both the application.arc and support.arc
files:
rescomp -DDEBUG application.arc -I/home/includes support.arc
After application.arc has been compiled, the /home/includes directory is added to the include file search path before the
support.arc file is compiled.
ResCompiler Error Messages

The following describes the errors that ResCompiler can generate upon compilation:
Error Message Explanation
Error. Output filename not specified on -o option. The command line contained the -o option but did not
specify an output filename. Check for blank spaces
between the -o option and the filename; e.g., -o
order.brc.
Error. Only one -o option allowed. The -o option was used more than once on the
command line. Remove all extra -o options.
Error. Only one input file may be specified with -o. The command line contains more than one input file.
When using the -o command line option, only one input
file can be specified. Remove all extra input file names.
Error. Out of memory. The system is out of memory. This message may be
followed by more specific information about the
subsystem that ran out of memory.
File: FFF.arc Line nnn: Out of memory. The system is out of memory. This message may be
followed by more specific information about the
subsystem that ran out of memory.
Error. Unknown option ’-X’. An unrecognized command line option was used. Check
to ensure that only valid options are used.
Error. Unable to close resource file ’XXX’. ResCompiler opened and wrote the compiled .brc file
but was unable to close the .arc file. This indicates that
another process could be using the resource file, or that
there is no free disk space available to save the file.
Warning. Input file ’XXX’ not found. The file is being ResCompiler could not find one of the .arc files
skipped. specified on the command line. The other .arc files will
be compiled.
Error. Unable to find the default header file. The default header file stdincl.h could not be found in
ResCompiler’s home directory.
File: FFF.arc Line nnn: Invalid version number. In file FFF.arc on line nnn, ResCompiler found an
invalid version number. At the time of publication, the
only valid version number was 3.0.
File: FFF.arc Line nnn: Symbol ’SSS’ is a string. The symbol ‘SSS’ contains a string value. A number
should have been provided.
File: FFF.arc Line nnn: Divide by zero. A numeric expression contains a divide by zero error.
File: FFF.arc Line nnn: Warning. Unable to find The file contains an undefined symbol.
symbol ’SSS’.
File: FFF.arc Line nnn: Menu ID is too large. Menu IDs must be less than or equal to 32767.
File: FFF.arc Line nnn: Accelerator key value is too Accelerator key values must be less than or equal to
large. 32767.
221
File: FFF.arc Line nnn: Internal Error. Unknown This internal error is contained within the ResCompiler
lookup error. executable and should be reported directly to BASIS
Technical Support.
Internal Error. Unable to initialize resource file This internal error is contained within the ResCompiler
subsystem. Syntax checking only. executable and should be reported directly to BASIS
Technical Support.
222
RESOURCE PROPERTY INDEX
Always Place Window on Top
Description Always positions the window on top of other windows.
Applies To Window/Form
Property Type Flag $00020000$
ResCompiler Syntax alwaysontop
ResCompiler Default False
Set Background Color

Description Sets the background color.
Applies To Window/Form, Child Window, Status Bar; Button, Check Box, Custom Edit, Edit, Grid, Group
Box, INPUTE, INPUTN, List Box, List Button, List Edit, Radio Button, Scroll Bar, Static Text,
Tool Button
Property Type Color
ResCompiler Syntax backgroundcolor
ResCompiler Default System default
Sound Beep for Invalid Data Entry

Description Sounds a beep upon entry of invalid data.
Applies To INPUTN
Property Type INPUTN Input Rules Flag $80$
ResCompiler Syntax beep
Create Border Around Control

Description Draws a border around the control.
Applies To Custom Edit
ResCompiler Syntax border
Create Child Window Without Border

Description Creates a child window without a border.
Applies To Child Window
ResCompiler Syntax borderless
ResCompiler Default True
Display Tabs as Buttons

Description Causes the tabs to appear as buttons.
Applies To Tab
Property Type Tab Style Flag $01$
ResCompiler Syntax buttons
Checkable Menu Item

Description Sets the menu item to be checkable.
223
Applies To Menu Item
ResCompiler Syntax checkable
Set Control to be Initially Checked

Description Sets the menu item or control to be initially checked.
Applies To Menu Item; Check Box, Radio Button, and Tool Button
Property Type Flag
Value Menu Item: $00000008$ Check Box Radio Button, and Tool Button: $00000004$
ResCompiler Syntax checked
Draw Client Edge Around Control

Description Draws a recessed client edge around the child window or control.
Applies To Child Window, Button, Check Box, Custom Edit, Edit, Grid, Group Box, INPUTE, INPUTN, List
Box, List Button, List Edit, Radio Button, Scroll Bar, Static Text, Tab, Tool Button, Status Bar
Property Type Flag
Value Child Window: $01000000$ All controls: $00000800$
ResCompiler Syntax clientedge
Create Close Box

Description Creates a window close box.
ResCompiler Syntax closebox
Use a Managed Grid Control as Column Heading

Description Creates a managed grid control as a column heading.
Applies To Grid
ResCompiler Default N/A
Set Initial Number of Columns

Description Sets the initial number of grid columns.
Applies To Grid
Property Type Integer
ResCompiler Syntax columns
ResCompiler Default 1
Copy Commas in Input

Description Causes the control to copy commas.
Applies To INPUTN
ResCompiler Syntax copycommas
224
Set Current Units
Description Sets the current units of the window.
Applies To Window/Form and Child Window
ResCompiler Syntax currentunits
Allow Custom Color Palette

Description Allows a window to use a custom color palette.
ResCompiler Syntax customcolorpalette
Replace Decimal Characters

Description Causes the control to replace decimal characters.
Applies To INPUTN
ResCompiler Syntax decimalreplace
Set Default Font

Description Sets the default font.
Applies To Window/Form, and Child Window
Property Type Font
ResCompiler Syntax defaultfont
ResCompiler Default System font
Make Window Behave as Dialog

Description Sets the window to behave as a dialog.
ResCompiler Syntax dialogbehavior
Create Border around Dialog

Description Creates a border around the dialog
Applies To Window/Form Window
ResCompiler Syntax dialogborder
Set Control to be Initially Disabled

Description Sets the resource to be initially disabled.
Applies To Window/Form, Child Window, Status Bar, Button, Check Box, Custom Edit, Edit, Grid, Group
Box, INPUTE, INPUTN, List Box, List Button, List Edit, Radio Button, Scroll Bar, Static Text,
Tab, Tool Button
Property Type Flag
Value Window/Form and Child Window: $00000020$ All others: $00000001$
225
ResCompiler Syntax dialogborder
Dock to Parent Frame

Description Attaches the child window to one side of the parent frame, by default to the top frame.
ResCompiler Syntax docking
Set Child Window Docking Position

Description Sets the child window docking position.
ResCompiler Syntax dockingposition
Use <Enter> as <Tab>

Description Sets the <Enter> key to behave as a <Tab> key.
ResCompiler Syntax enterastab
Set Event Mask

Description Sets the window event mask.
ResCompiler Syntax eventmask
ResCompiler Default EM_ALL
Set Fixed Tab Widths

Description Sets fixed tab widths.
Applies To Tab
ResCompiler Syntax fixedwidth
Prevent Focus
Description Prevents the tab control from receiving focus when clicked.
Applies To Tab
ResCompiler Syntax focusnever
Receive Focus on Button Down

Description Causes the tab control to receive focus when clicked.
Applies To Tab
226
ResCompiler Syntax focusonbuttondown
Set Control Font

Description Sets the control font.
Applies To Button, Check Box, Custom Edit, Edit, Grid, Group Box, INPUTE, INPUTN, List Box, List
Button, List Edit, Radio Button, Static Text, Tab, Tool Button, Status Bar
Property Type Font
ResCompiler Syntax font
ResCompiler Default Windows default
Force Icons to Left Margin

Description Forces icons to the left margin of the tab control.
Applies To Tab
ResCompiler Syntax forceiconleft
Force Labels to Left Edge of Tabs

Description Forces labels to the left edges of fixed-width tabs.
Applies To Tab
ResCompiler Syntax forcelabelleft
Set Foreground Color

Description Sets the foreground color.
Applies To Window/Form, Child Window, and Status Bar; Check Box, Custom Edit, Edit, Grid, Group Box,
INPUTE, INPUTN, List Box, List Button, List Edit, Radio Button, Static Text, Tool Button
Property Type Color
ResCompiler Syntax foregroundcolor
ResCompiler Default System default
Set Child Window Gravity

Description Arranges the child window to fit within the parent window.
ResCompiler Syntax gravity
ResCompiler Default Form = False Child Win = True
Group Controls Together

Description Designates the control to be part of a group.
Applies To Status Bar, Button, Check Box, Custom Edit, Edit, Grid, Group Box, INPUTE, INPUTN, List
Box, List Button, List Edit, Radio Button, Scroll Bar, Static Text, Tab, Tool Button
ResCompiler Syntax group
Set Non-mouse Events to Highlight Text

Description Prompts non-mouse events on the control to highlight the control’s text.
227
Applies To INPUTE and INPUTN
ResCompiler Syntax highlight
Draw Horizontal Grid Lines

Description Draws horizontal lines between grid rows.
Applies To Grid
ResCompiler Syntax horizlines
Set Additional Horizontal Spacing Between Tabs

Description Sets the additional horizontal spacing between tabs.
Applies To Tab
ResCompiler Syntax horizontalpadding
Include Horizontal Scroll Bar

Description Includes a horizontal scroll bar with the window, child window, or control.
Applies To Window/Form, Child Window, Custom Edit, and Grid
Property Type Flag
Value Window/Form Child Window: $00000004$ Custom Edit and Grid: $00000080$
ResCompiler Syntax hscrollbar
Define Icon File

Description Defines the file that contains the window’s icon.
Property Type String, Number
ResCompiler Syntax icon
ResCompiler Default default VPRO/5 icon
Ignore Tabs in Text Input

Description Causes the control to ignore tabs in text input.
ResCompiler Syntax ignoretabs
Define Image List

Description Sets the tab control’s image list. Only up to 8-bit depth(256 color) graphics are supported.
Applies To Grid and Tab
Property Type String
ResCompiler Syntax imagelist
ResCompiler Default Null
228
Set INPUTN Input Mask
Description Sets the input mask.
Applies To INPUTN
ResCompiler Syntax imask
Set Initial Contents

Description Sets the control’s initial contents.
Button, List Edit, Radio Button, Static Text, and Tool Button
ResCompiler Syntax initialcontents
Set Initial Cursor Position

Description Sets the initial cursor position.
Applies To INPUTE, INPUTN, and Scroll Bar
ResCompiler Syntax initialposition
ResCompiler Default End of input string
Set Scroll Bar Proportion

Description Sets the scroll bar proportion.
Applies To Scroll Bar
ResCompiler Syntax initialproportion
Set Initial Thumb Size

Description Sets the initial thumb size.
ResCompiler Syntax initialsize
Set Initial Tab

Description Sets the tab that begins the display.
Applies To Tab
ResCompiler Syntax initialtab
Set Space Between Grid Rows

Description Sets the number of pixels between grid rows.
Applies To Grid
ResCompiler Syntax interspace
229
Set Control to be Initially Invisible
Description Sets the resource to be initially invisible.
Applies To Window/Form, Child Window, Status Bar, Button, Check Box, Edit (Windows NT 4.0 only),
Grid, Group Box, INPUTE, INPUTN, List Box, List Button, List Edit, Radio Button, Scroll Bar,
Static Text, Tab, Tool Button,
Property Type Flag
Value $00000010$
ResCompiler Syntax invisible
Set Text Justification

Description Sets the text justification.
Applies To Status Bar; Button, Check Box, Edit (Windows NT 4.0 only), Radio Button, Static Text, Tool
Button
ResCompiler Syntax justification
ResCompiler Default $00000000$ ($00002000$=Left; $00004000$=Center;$00008000$=Right)
Activate Keyboard Navigation

Description Activates keyboard navigation in the window.
ResCompiler Syntax keyboardnavigation
Maximum Number of Paragraphs

Description Sets the maximum number of paragraphs for the control.
ResCompiler Syntax limit
Set Status Bar (Longcue) Text

Description Sets the status bar text for the control.
Button, List Edit, Radio Button, Scroll Bar, Static Text, Tab, Tool Button, Status Bar
ResCompiler Syntax longcue
Automatically Manage SYSCOLOR Events

Description Sets the window to automatically manage SYSCOLOR events.
ResCompiler Syntax managesyscolor
Set Control Margin

Description Sets the control margin in current units.
230
ResCompiler Syntax margin
Set INPUTE Input Mask

Description Sets the input mask.
Applies To INPUTE
ResCompiler Syntax mask
Set Maximum Number of Columns

Description Sets the maximum number of grid columns.
Applies To Grid
ResCompiler Syntax maxcols
Allow Maximized Window

Description Allows the window to be maximized.
ResCompiler Syntax maximizable
Set Window to be Initially Maximized

Description Sets the window to be initially maximized.
ResCompiler Syntax maximized
Maximum Input String Length

Description Sets the maximum length of the input string.
Applies To INPUTE
ResCompiler Syntax maxlength
ResCompiler Default Undefined
Include Menu Bar

Description Creates a default menu bar with a window/form.
ResCompiler Syntax menubar
Allow Minimized Window

Description Allows the window to be minimized.
231
ResCompiler Syntax minimizable
Set Window to be Initially Minimized

Description Sets the window to be initially minimized.
ResCompiler Syntax minimized
Display all Tab Rows

Description Displays all rows of tabs.
Applies To Tab
ResCompiler Syntax multiline
Allow Multiple Selections

Description Permits the control to accept multiple selections.
Applies To List Box
ResCompiler Syntax multiselect
Set Window/Control Name

Description Sets the name of the window/form or control.
Applies To Window/Form, Child Window, Menu, Menu Item, Status Bar, Button, Check Box, Custom Edit,
Edit, Grid, Group Box, INPUTE, INPUTN, List Box, List Button, List Edit, Radio Button, Scroll
Bar, Static Text, Tab, Tool Button
ResCompiler Syntax name
Prevent Automatic Management of Tab Item Display and Sizing

Description Prevents a tab's associated control or child window from being automatically displayed when
the tab is selected. It also prevents a tab's managed controls or child windows from being
automatically resized when the tab is resized.
(By default, a tab will automatically display an associated control or child window when it is
selected, and will automatically resize its managed controls or child windows when it is
resized.)
Applies To Tab
ResCompiler Syntax noautomanagement
Do Not Include Title Bar

Description Creates the window without a title bar.
232
ResCompiler Syntax notitlebar
Prevent Text Wrapping

Description Prevents static text control text from wrapping.
Applies To Static Text
ResCompiler Syntax nowrap
Set INPUTN Output Mask

Description Sets the output mask.
Applies To INPUTN
ResCompiler Syntax omask
Allow Only One Paragraph

Description Limits the control text to one paragraph.
ResCompiler Syntax oneparagraph
Set Option String

Description Sets the option string.
ResCompiler Syntax optionstring
Set Scroll Bar Orientation

Description Sets the scroll bar orientation.
ResCompiler Syntax orientation
Initially in Overstrike Mode

Description Causes the control to be initially in overstrike mode.
ResCompiler Syntax overstrike
Set INPUTE Pad Character

Description Sets the pad character.
Applies To INPUTE
233
ResCompiler Syntax padcharacter
Pass <Enter> to Parent Window

Description Passes the <Enter> key to the parent window.
ResCompiler Syntax passenter
Pass <Home> and <Delete> as Keypress Notify Events

Description Passes the <Home> and <Delete> keys as Keypress Notify events.
Applies To Edit
ResCompiler Syntax passhomedel
Pass <Tab> to Parent Window

Description Passes the <Tab> key to the parent window.
ResCompiler Syntax passtab
Replace Input Text with Asterisks

Description Replaces input text with asterisks.
Applies To Edit
ResCompiler Syntax passwordentry
Prevent Full Tab Justification

Description Prevents tabs from filling the entire width of the tab control.
Applies To Tab
ResCompiler Syntax raggedright
Draw Raised Edge Around Control

Description Draws a raised edge around the child window or control.
Applies To Child Window, Button, Check Box, Custom Edit, Edit, Grid, Group Box, INPUTE, INPUTN, List
Box, List Button, List Edit, Radio Button, Scroll Bar, Static Text, Tab, Tool Button
Property Type Flag
Value Child Window: $02000000$ All others: $00001000$
ResCompiler Syntax raisedge
Set Text as Read-only

Description Defines the edit text as read-only.
234
ResCompiler Syntax readonly
Set Restore String

Description Sets the restore string value.
ResCompiler Syntax restorestring
Set INPUTN to Behave as INPUTE if First Character is Non-numeric

Description Causes the INPUTN control to behave as an INPUTE control if the first character entered is
non-numeric.
Applies To INPUTN
ResCompiler Syntax reverttoinpute
Set Full Tab Justification

Description Expands each tab, causing the row to fill the entire width of the tab control.
Applies To Tab
ResCompiler Syntax rightjustify
Enter Data from Right Side

Description Causes the data to be entered from the right side.
Applies To INPUTN
ResCompiler Syntax rightmostentry
Use a Managed Grid Control as Row Heading

Description Creates a managed grid control as a row heading.
Applies To Grid
ResCompiler Default N/A
Set Initial Number of Grid Rows

Description Sets the initial number of rows in the grid.
Applies To Grid
ResCompiler Syntax rows
Insert Separation Line After Menu Item

Description Inserts a line after a menu item.
235
Applies To Menu Item
ResCompiler Syntax separator
Share Image Lists with Other Tab Controls

Description Shares image lists with other tab controls.
Applies To Tab
ResCompiler Syntax shareimagelists
Set Tool Tip (Shortcue) Text

Description Sets the tool tip text.
Button, List Edit, Radio Button, Scroll Bar, Static Text, Tab, Tool Button, Status Bar
ResCompiler Syntax shortcue
Allow Window Resizing

Description Allows the window to be resized.
ResCompiler Syntax sizeable
Set Status Bar Definition

Description Sets the status bar definition.
Property Type Status bar
ResCompiler Syntax statusbar
Set Tab Height

Description Sets the tab height.
Applies To Tab
ResCompiler Syntax tabheight
Display Tabs as Tabs/Draw Border Around Display

Description Displays tabs as tabs and draws a border around the display area.
Applies To Tab
ResCompiler Syntax tabs
236
Set Tab Width
Description Sets the tab width.
Applies To Tab
ResCompiler Syntax tabwidth
Place Text to Left of Check Box or Radio Button

Description Places title text to the left of the Check Box or Radio Button.
Applies To Check Box and Radio Button
ResCompiler Syntax textleft
Set Title
Description Sets the Window/Form title or the initial contents for the control (for use with pre-existing
resource files only).
Applies To Window/Form, Status Bar, Button, Check Box, Custom Edit, Edit, Grid, Group Box, INPUTE,
INPUTN, List Box, List Button, List Edit, Radio Button, Static Text, Tool Button
ResCompiler Syntax title
Create Toggle On/Off Button

Description Creates a “click on, click off toggle button.
Applies To Grid
ResCompiler Syntax toggle
Create Window as Tool Window

Description Creates a top level window as a Windows-style tool window.
Applies To Tab Control
ResCompiler Syntax toolwindow
Allow Column Resizing

Description Allows users to resize grid columns.
Applies To Grid
ResCompiler Syntax usersize
Set Additional Vertical Tab Spacing

Description Sets the additional vertical spacing between tab rows.
Applies To Tab
237
ResCompiler Syntax verticalpadding
Draw Vertical Lines Between Columns

Description Draws vertical lines between grid columns.
Applies To Grid
ResCompiler Syntax vertlines
Include Vertical Scroll Bar

Description Includes a vertical scroll bar with the window, child window, or control.
Applies To Window/Form, Child Window, Custom Edit, and Grid
Property Type Flag
Value Window/Form, Child Window: $00000008$; Custom Edit and Grid: $00000100$
ResCompiler Syntax vscrollbar
Wrap Text to Next Line

Description Causes the control to wrap text to the next line.
ResCompiler Syntax wordwrap
238
SENDMSG() FUNCTIONS
Grid Control SENDMSG() Functions
The SENDMSG() function is used to query and manipulate grid controls. The following is the standard syntax for SENDMSG() as
used with the grid control:
Syntax
RESULT$=SENDMSG(sysgui,id,function,int,str$)
sysgui SYSGUI channel.
id
function An integer representing a specific function (described below).
int Integer argument. May be zero or some other value depending on the specific function.
str$ String argument. May be null or not depending on the specific function.
Many grid SENDMSG() functions return a one-character string to indicate the success or failure of the operation: $01$ indicates
success, $00$ indicates failure. Other functions return null strings or binary data.
GRID SENDMSG() Functions Listed by Functional Grouping

Functional Grouping Title Number
Cell Appearance Set Default Alignment 84
Set Default Background Color 55
Set Default Style 83
Set Default Text Color 56
Set Line Color 61
Cell Characteristics Draw Cell 54
Set Extended Text Options 27
Data Insertion Draw Cell 54
Set Edit Text 35
Set Multiple Cells 21
Set Multiple Rows 87
Set Single Cell 22
Data-Aware Grids Perform Data-Aware Function 81
Seek Last Record 85
Set Channel and Template 80
Set Continue Message 82
Set Last Record Dialog 86
Grid Dimensions Set Number of Columns 66
Set Number of Rows 67
Grid Display Goto Column 47
Goto Row 48
Redraw Grid 76
Redraw Row 50
Set Top Row 70
Grid Functionality Set Cursor 78
Set Drag Accept 33
Set Edit Mask 79
Set Horizontal Scroll Mode 59
Set Image List ID 75
Set Mouse Scrolling Mode 65
Set Thumb Update Mode 69
Set User Resize 74
Set Vertical Scroll Mode 71
Grid Operations Deselect All Cells 32
Drag Start 25
End Edit 26
Set Mouse Capture Mode 64
Start Edit 31
Heading Grids Set Current Heading Mode 77
Set Heading Dark Shadow Color 52
Set Heading Light Shadow Color 53
Set Heading Shadow Height 51
Set Heading Spacing 28
Set Heading Titles 23
Highlighting Set Cell/Row Highlight 49
Set Highlight Method 57
Margins Set Margin 62
Set Margin Mode 63
Multiple Grid Characteristics Set Up Grid 30
Queries Get Average Character Width 37
Get Column Width 38
Get Edit Text 34
Get Font 39
Get Grid Information Block Defaults 20
Get Number of Columns 40
Get Number of Rows 41
Get Number of Visible Rows 43
Get Row Height 42
Get Selected Column 44
Get Selected Row 45
Get String Width 73
Get Top Row 46
Row and Column Dimensions Fit Columns to Window 29
Set Best Fit 24
Set Column Width 36
Set Interspace 60
240
Set Row Height 68
Separation Lines Set Horizontal Lines 58
Set Vertical Lines 72
Get Grid Information Block - GRID SENDMSG() Function 20

Syntax
GRID_INFO$=SENDMSG(sysgui,id,20,0,$$)
Description
The grid information block is a templated string used by Draw Cell - Grid SENDMSG() Function 54 to set text, colors, alignment,
and style in a cell. This function returns the default values in this string. Using this function with SENDMSG() Function 54 is a
simple way to set default colors, style, and alignment in a main grid or a row or column heading grid. Default settings can be
modified with other SENDMSG() functions. Any change in default settings will be reflected in the string returned by this function.
id Grid control ID.
20 SENDMSG() function number.
0 Always zero.
$$ Always null.
Use the TMPL() function with an index of 1 to retrieve the template for the grid information block. For example:
dim grid_info$:TMPL(sysgui,ind=1)
The full template follows:
msg:u(4),wparm:u(4),lparm:i(4),col:u(4),row:u(4),textcolor:c(3),backcolor:c(3),
alignment:u(1),style:i(4),imgidx:i(4),x:i(2),y:i(2),
w:u(2),h:u(2),ptx:I(2),pty:i(2),buf:c(1*)
Many of the fields in this template relate to individual cells or do not have meaningful defaults. The fields in the grid information
block that are relevant to this function are described below:
Grid Information Block Field Description
TEXTCOLOR RGB color string for text.
BACKCOLOR RGB color string for background.. The default value is
ALIGNMENT Controls the alignment of text in the cell:
0 = Left alignment
1 = Right alignment
2 = Centered
STYLE Controls the appearance of the cell:.
0 = INPUTE control
1 = Raised button appearance created by shading two sides of the cell.
2 = Recessed button appearance created by shading two sides of the cell.
4 = Checked checkbox, with text, if any, displayed to the right of the checkbox.
8 = Unchecked check box, with text, if any, displayed to the right of the checkbox.
The following table identifies the default values returned for main and heading grid controls, assuming no defaults have been
changed:
Grid Information Block Field Main Grid Default Value Heading Grid Default Value
TEXTCOLOR $000000$ (Black) $000000$ (Black)
BACKCOLOR $FFFFFF$ (White) $C0C0C0$ (Gray)
241
ALIGNMENT 2 (Centered) 2 (Centered)
STYLE 0 (INPUTE control) 1 (Raised button)
The default text color can be changed with Set Default Text Color - Grid SENDMSG() Function 56. The default background color
can be changed with Set Default Background Color - Grid SENDMSG() Function 55. The default alignment can be changed with
Set Default Alignment - Grid SENDMSG() Function 84. The default style can be changed with Set Default Style - Grid
Note
In Visual PRO/5 Rev. 2.0x, this function returned a snapshot of the grid information block rather than default values. The values
returned in this snapshot were not reliable.
See also Draw Cell - Grid SENDMSG() Function 54.
Set Multiple Cells - GRID SENDMSG() Function 21

Syntax
TF$=SENDMSG(sysgui,id,21,number_of_cells,cell_contents$)
Description
This function sets the values in one or more contiguous cells with one command.
id Grid control ID.
number_of_cells Number of cells to fill in.
cell_contents$ Linefeed-terminated string with values to place in grid.
The number_of_cells parameter specifies how many cells are to be filled. The cell_contents$ parameter contains one or more
strings delimited by linefeeds ($0A$). When the function executes, the first value is placed in the first column of the current row.
Then the second value is placed in the next cell to the right. If number_of_cells is greater than the number of columns in the grid,
values will be set in the entire current row, then the next row or rows until all the cell entries are used. If all the cell entries are
used before the specified number of cells have been filled, the values from the beginning of the string are reused.
This function works on heading grids as well as main grids. The return value is a one-byte string that indicates the success or
failure of an operation; $01$ indicates success, $00$ indicates failure.
System default style, alignment, and colors are used. If any nondefault display attributes had been set in a cell with Draw Cell -
Grid SENDMSG() Function 54, those attributes are reset to defaults by this function.
Example
The following example creates a grid with three rows and three columns and fills in the first five cells:
sysgui=unt;open (sysgui)"X0"
print (sysgui)'window'(50,50,200,150,"Grid Program",$$,$$)
print (sysgui)'grid'(100,20,20,160,120,$9040$,3,3,3)
result$=sendmsg(sysgui,100,68,150/4,$$); rem row height
for col=0 to 2
result$=sendmsg(sysgui,100,36,col,chr(51)); rem column width
next col
result$=sendmsg(sysgui,100,21,5,"First"+$0A$+"Second"+$0A$+"Third"+$0A$)
escape
242
Set Single Cell - GRID SENDMSG() Function 22
Syntax
TF$=SENDMSG(sysgui,id,22,column_number,cell$)
Description
This function displays the value in cell$ in the specified column on the current row. The left cell in the row is numbered 0, the next
cell to the right is numbered 1, and so on.
id Grid control ID.
column_number Number of cell to fill in.
cell$ Value to place in grid.
This function works on heading grids as well as main grids. The return value is a one-byte string that indicates the success or
failure of the operation; $01$ indicates success, $00$ indicates failure. If column_number is higher than the highest column
number in the grid, the function generates an !ERROR=17.
System default style, alignment, and colors are used. If any nondefault display attributes had been set in a cell with Draw Cell -
Grid SENDMSG() Function 54, those attributes are reset to defaults by this function.
Example
The following example creates a grid and uses SENDMSG() Function 22 to display data in each column of each row:
let sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(50,50,200,150,"",$$,$$)
for col=0 to 2
next col
result$=sendmsg(sysgui,100,57,0,$$); rem turn off color change highlighting
for row=0 to 2
tf$=sendmsg(sysgui,100,48,row,$$)
for col=0 to 2
tf$=sendmsg(sysgui,100,22,col,str(col))
next col
next row
escape
Set Heading Titles - GRID SENDMSG() Function 23

Syntax
TF$=SENDMSG(sysgui,id,23,0,title$)
Description
Set Cells - Grid SENDMSG() Function 21, Set Cell - Grid SENDMSG() Function 22, or Draw Cell - Grid SENDMSG() Function 54
can be used to put data in heading grids and are recommended for displaying constant data in heading grids. The Set Heading
Titles function works only on heading grids and allows the programmer to display data from the main grid in the associated
heading grid. For example, a row header can be constructed from the main grid columns that display a customer's first and last
names.
243
id Grid control ID.
0 Always zero.
title$ Title string.
This function uses the title$ parameter to set the titles in the specified heading grid. The title$ string is parsed and values are
substituted based on the following formats:
title$ String Format Description
%column_number Substitutes the data in the specified column number specified. For example, if a title$
string specifies a row heading of "%c1 %c3", the data contained in columns 1 and 3
would be displayed in each row heading, with a space between the fields.
%row_number Substitutes the data in the specified row. This can be useful when the column heading is
to represent a record in a file that marks the start of a search.
%% Prints the percent symbol.
All other characters in the string are not substituted, but are placed directly into the title value.
Visual PRO/5 manages heading grids by caching the values for the columns and the currently displayed set of rows. For Visual
PRO/5 to obtain the initial data, the program must be able to return data for the column, row or specific cell when requested
through a Notify message. If the grid receives data from an input channel, some aspects of this feature may not be available
because Visual PRO/5 may not have seen the data at the time the grid needs to be displayed. When Set Cells - Grid SENDMSG()
Function 21, Set Cell - Grid SENDMSG() Function 22, or Draw Cell - Grid SENDMSG() Function 54, are executed for a given
column within the main grid, that cell is examined to determine if it is part of a formatted header used to update the information in
the cached header cells. The header format string manages the entire header. Until all cells required to produce the formatted
string are seen by one of the above SENDMSG() functions, the column or row header text will not be displayed.
When using Set Cells, Set Cell, or Draw Cell functions with a header grid, the format string managed by the header grid should be
cleared so the values can be displayed correctly. The format string is not required for a heading grid but is supplied as a
convenience. Although the column headings are always cached, row headings cannot be completely cached because the grid can
contain over 2 billion rows. The row cache size is based upon the number of displayed rows. Therefore, if an application sets the
column header cell values, Notify message requests for column heading cell information can be ignored (unless the cells are
actually being changed). Because the row header cache may or may not properly set the row cells, the application should be set
to always respond to Notify message requests for row heading cell information, unless a formatted string is used to manage the
row heading. The return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success,
$00$ indicates failure.
Set Best Fit - GRID SENDMSG() Function 24

Syntax
TF$=SENDMSG(sysgui,id,24,extra_pixels,string_list)
Description
This function adjusts the width of each column based on the parameters passed. string_list is a list of strings terminated with line
feeds ($0A$), and extra_pixels is the number of pixels to be added to the width of every column. The width of each column is set
by taking the width of the corresponding string in the list and adding the extra_pixels value.
Sysgui SYSGUI channel.
id Grid control ID.
extra_pixels Extra pixels to be added to the width of each column.
string_list List of strings terminated with line feeds ($0A$). There should be one string for each column.
The return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success, $00$ indicates
failure.
244
Example
The following shows the use of Grid SENDMSG() Function 24 to set variable column widths:
let sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(50,50,200,150,"",$$,$$)
for col=0 to 2
next col
for row=0 to 2
for col=0 to 2
tf$=sendmsg(sysgui,100,22,col,fill(col+1,"Y"))
next col
next row
tf$=sendmsg(sysgui,100,24,10,"XX"+$0a$+"XXX"+$0a$+"XXXX"+$0a$)
escape
See also Set Column Width - Grid SENDMSG() Function 36, Fit Columns to Window - Grid SENDMSG() Function 29.
Drag Start - GRID SENDMSG() Function 25

Syntax
TF$=SENDMSG(sysgui,id,25,cursor,string$)
Description
This function starts a drag-and-drop operation and specifies the data to be dropped. It does not return a value until the operation is
finished.
id Grid control ID.
cursor Cursor parameter, which can be one of the following:
-1 The cursor set with SENDMSG() Function 78
0 Arrow and small hourglass
1 Arrow
2 Crosshair
3 Text I-beam
4 Reserved for a future version
5 Slashed circle
6 Reserved for a future version
7 Four-pointed arrow
8 Double-pointed arrow pointing northeast and southwest
9 Double-pointed arrow pointing up and down
245
10 Double-pointed arrow pointing northwest and southeast
11 Double-pointed arrow pointing left and right
12 Arrow pointing up
13 Hourglass
string $ String to be used in the drag-and-drop operation.
If the cursor parameter is -1, the default cursor will be used for the drag-and-drop operation. Otherwise, an index to a cursor
resource may be entered.
Once the operation is completed a DRAGDROP Notify event (Notify code 4) is sent. This event reports the location where the
drop occurred. The return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success,
$00$ indicates failure.
See also Set Drag Accept - Grid SENDMSG() Function 33.
End Edit - GRID SENDMSG() Function 26

Syntax
TF$=SENDMSG(sysgui,id,26,0,$$)
Description
This function ends editing mode. Typically, this function is executed in response to an EDITKILL Notify event (notify code 7), which
is generated when a cell in edit mode loses focus.
id Grid control ID.
0 Always zero.
$$ Always null.
Application programs may also end editing mode in response to keystrokes such as arrow keys, the <Enter> key, the <Home>
key, etc. The return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success, $00$
indicates failure.
Set Extended Text Options - GRID SENDMSG() Function 27

This function does nothing in Visual PRO/5 Rev. 2.10 and above.
Set Heading Spacing - GRID SENDMSG() Function 28

Syntax
TF$=SENDMSG(chan,id,28,heading,chr(pixels))
Description
This function sets the spacing between a main grid and an associated column or row heading grid. The pixels parameter defines
the number of pixels between the grids. Use the CHR() function to pass the binary representation of this value. The heading
parameter controls which heading grid is referenced. To adjust the column heading, use a value of 0. To adjust the row heading,
use a value of 1. The id parameter should refer to the main grid, not a heading grid. The return value is a one-byte string that
indicates the success or failure of an operation; $01$ indicates success, $00$ indicates failure.
id Grid control ID.
heading 1 to set row heading spacing, 0 to set column heading spacing.
246
chr(pixels) Binary representation of the number of pixels between the grids.
Fit Columns to Window - GRID SENDMSG() Function 29

Syntax
TF$=SENDMSG(sysgui,id,29,cols,$$)
Description
This function adjusts the width of the columns specified to fill the entire body of the grid.
id Grid control ID.
cols Number of columns to fit into grid display.
$$ Always null.
The cols parameter specifies the number of columns to fit in the window. The columns are adjusted so that width proportions are
maintained. For example, if column 0 is three times as wide as column 1 before the function is called, column 0 will still be three
times as wide as column 1 after the function has been called. The return value is a one-byte string that indicates the success or
failure of an operation; $01$ indicates success, $00$ indicates failure.
See also Set Column Width - Grid SENDMSG() Function 36, Set Best Fit - Grid SENDMSG() Function 24.
Set Up Grid - GRID SENDMSG() Function 30

Syntax
TF$=SENDMSG(sysgui,id,30,0,grid_description$)
Description
This function combines the functionality of several other grid SENDMSG() functions to set several characteristics of a grid in one
command. The return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success, $00$
indicates failure.
id Grid control ID.
0 Always zero.
grid_descriptions$ String that contains the grid parameters.
“ROWS:U(4),COLS:U(1),COLWIDTHS[cols]:U(2),INTERSPACE[cols]:U(2),
USERSIZE:U(1),COLMASKS[cols]:C(mask_len)
Field Offset/Length Description

ROWS 1,4 Number of grid rows, ranging from 0 to 2,100,000,000. Unsigned
integer.
COLS 5,1 Number of columns in the grid, ranging from 0 to 255. Unsigned
Integer
COLWIDTHS (6,2)*COLS Array of column widths in current units. A value must be provided
for each column in the grid. Unsigned integer.
INTERSPACE (6,2)*COLS,2 Array of unsigned integers indicating the number of extra pixels
between rows. A value must be provided for each column in the
grid.
247
USERSIZE (6,2)*COLS+2,1 A flag that controls whether the user can change column widths. If
the value of this parameter is 1, column widths can be changed.
Unsigned integer.
COLMASKS$ (6,2)*COLS+3,m Optionally sets a mask for each column in the grid mask. If this
field is specified, a mask field must exist for each column in the
grid. The mask is created according to the rules for masking
INPUTE controls. Each mask field must be terminated with a null
($00$). If a column does not need a mask, enter an empty string
as the mask. Columns with no mask defined can contain up to
255 characters.
Example
The following example uses SENDMSG() Function 30 to set column width:
print (sysgui)'window'(50,50,200,150,"Grid Sample",$$,$$)
result$=sendmsg(sysgui,100,56,0,$000000$)
dim ts$:"rows:u(4),cols:u(1),colwidth[3]:u(2),interspace[3]:u(2),usersize[3]:u(2)"
ts.rows=8,ts.cols=3
for col=1 to 3
ts.colwidth[col]=51
next col
result$=sendmsg(sysgui,100,,30,0,ts$); rem ' initialize grid
escape
Start Edit - GRID SENDMSG() Function 31

Syntax
TF$=SENDMSG(sysgui,id,31,0,edit_params$)
Description
This function starts editing mode in the specified cell.
id Grid control ID.
0 Always zero.
edit_params$ Templated string with parameters that control how the function operates.
The edit_params$ parameter controls the operation of the function. The structure of edit_params$ is flexible.
Note that when a grid control is in edit cell mode, keystrokes such as arrow keys, function keys, and <Enter> are not processed by
the grid. If the application is to respond to these keys, they must be trapped. This is accomplished by checking for the EDITKEY
Notify event (Notify code 6).
The complete string may be defined with this template:
mask:c(1*=0),restore:c(1*=0),initstr:c(1*=0),key:u(2),col:u(2),row:u:(4)
Either of these two shorter templates may also be used:
initstr:c(1*=0),key:u(2),col:u(2),row:u(4)
mask:c(1*=0),restore:c(1*=0),key:u(2),col:u(2),row:u(4)
Each of the fields is described below:
248
Templated String Field Description
MASK Null-terminated mask string to use for editing. Valid mask characters are the same
as those used by the INPUTE control. This mask overrides any masks specified by
Set Edit Mask - Grid SENDMSG() Function 79 or Set Up Grid - ENDMSG() Function
30.
RESTORE$ Null-terminated restore string that can be used to restore the field during editing
when the user presses <Esc> or <Ctrl>+R. If no string is specified, the initial value in
the cell is the restore value.
INITSTR$ Null-terminated string with the initial value to be placed into the cell when entering
edit mode. If an initial string is specified for a cell in a data-aware grid, the initial
string specified in the function appears in the cell instead of the data in the record.
KEY Integer that specifies the key code. This parameter is useful if editing mode was
started in response to a KEYBOARD Notify event (Notify code 12). Entering the key
value sent in the KEYBOARD message will cause it to be added to the edit control.
To avoid sending a key value to the edit control, use 0 for this parameter.
COLUMN Number of column in which to begin editing. Note that column numbering is zero-
based.
ROW Number of row in which to begin editing. Note that row numbering is zero-based.
The return value is a one-byte string that indicates the success or failure of an
operation; $01$ indicates success; $00$ indicates failure.
Example
This example shows the use of SENDMSG() Function 31 in response to a mouse left button click (Notify event 14). When the
mouse click is detected, the program enters edit mode. When edit mode is ended by clicking on another cell, the edited data is
stored in an array.
dim event$:tmpl(sysgui); event=len(event$)
dim generic$:noticetpl(0,0)
dim edit_param$:"initstr:c(1*=0),key:u(2),col:u(2),row:u(4)"
dim grid_data$[2,2]
grid$=sendmsg(sysgui,100,20,0,$$)
grid.style=1
counter=0
for col=0 to 2
for row=0 to 2
grid.col=col,grid.row=row
grid.buf$=str(counter)
tf$=sendmsg(sysgui,100,54,0,grid$)
grid_data$[col,row]=str(counter)
counter=counter+1
next row
next col
249
eoj=0
repeat
read record(sysgui,len=event)event$
: notice$=generic$
rem Query the cell after exiting edit mode
if event.code$="N" and notice.code=7 then
: grid_data$[notice.col,notice.row]=sendmsg(sysgui,100,34,0,$$)
rem Enter edit mode after a click of the left mouse button
if event.code$="N" and notice.code=14 and notice.lparam=1 then
: edit_param.row=notice.row,edit_param.col=notice.col;
: tf$=sendmsg(sysgui,100,31,0,edit_param$)
rem Redraw a cell in response to Notify event 23
: grid.col=notice.col,grid.row=notice.row;
: grid.buf$=grid_data$[notice.col,notice.row];
: tf$=sendmsg(sysgui,100,54,0,grid$)
rem Redraw range of cells in response to Notify event 22
: for row=notice.toprow to notice.botrow;
: grid.row=row;
: for col=notice.leftcol to notice.rightcol;
: grid.col=col;
: grid.buf$=grid_data$[col,row];
: result$=sendmsg(sysgui,100,54,0,grid$);
: next col;
: next row
until eoj
Deselect All Cells - GRID SENDMSG() Function 32

Syntax
Description
This function deselects all grid cells and causes the grid to set the current row to -1. The return value is a one-byte string that
indicates the success or failure of an operation; $01$ indicates success, $00$ indicates failure.
id Grid control ID.
0 Always zero.
$$ Always null.
250
Set Drag Accept - GRID SENDMSG() Function 33
Syntax
TF$=SENDMSG(sysgui,id,33,accept_drag_flag,$$)
Description
This function controls whether the specified grid control will accept drag operations from other grid controls.
id Grid control ID.
accept_drag_flag Nonzero value indicates drag operations accepted; zero value indicates drag operations
rejected.
$$ Always null.
If the accept_drag_flag parameter is nonzero, the grid will accept drag operations, otherwise it will reject drag operations. The
return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success, $00$ indicates
failure.
Get Edit Text - GRID SENDMSG() Function 34

Syntax
TEXT$=SENDMSG(sysgui,id,34,0,$$)
Description
This function returns the edit text in a cell that is an INPUTE control (the default cell style). This text can be input into the grid with
a Set Edit Text - Grid SENDMSG() Function 35, or by the user editing text in a cell.
id Grid control ID.
0 Always zero.
$$ Always null.
Set Edit Text - GRID SENDMSG() Function 35

Syntax
Description
This function sets the title text for the user to edit in a cell. Note that this function does not cause the value to be displayed. The
text can be queried with Get Edit Text - SENDMSG() Function 34. The return value is a one-byte string that indicates the success
or failure of an operation; $01$ indicates success, $00$ indicates failure.
id Grid control ID.
0 Always zero.
title$ Title text.
251
Set Column Width - GRID SENDMSG() Function 36
Syntax
TF$=SENDMSG(sysgui,id,36,col,chr(colwidth))
Description
This function sets the width of the specified column in the grid.
id Grid control ID.
col Column number. The leftmost column is column 0.
chr(colwidth) Binary representation of the column width.
The colwidth parameter defines the width in pixels. Use the CHR() function to pass the binary representation of this value. The
width of a column can be changed at any time. Note that column numbering is zero-based. The return value is a one-byte string
that indicates the success or failure of an operation; $01$ indicates success, $00$ indicates failure.
See also Set Best Fit - Grid SENDMSG() Function 24 and Fit Columns to Window - Grid SENDMSG() Function 29.
Get Average Character Width - GRID SENDMSG() Function 37

Syntax
WIDTH$=SENDMSG(sysgui,id,37,0,$$)
Description
This function returns a binary representation of the average width of a character in pixels, based on the grid's current font. Use
DEC(width$) to get the numeric representation.
id Grid control ID.
0 Always zero.
$$ Always null.
Get Column Width - GRID SENDMSG() Function 38

Syntax
WIDTH$=SENDMSG(sysgui,id,38,column,$$)
Description
This function returns a binary representation of the width of the specified column, in pixels.
id Grid control ID.
column Column number (zero-based).
$$ Always null.
Note that column numbering is zero-based. Use DEC(WIDTH$) to get the numeric representation. The return value is a binary
representation of the width of the specified column, in pixels.
252
Get Font - GRID SENDMSG() Function 39
Syntax
FONT$=SENDMSG(sysgui,id,39,0,$$)
Description
This function returns information about the font used by the grid control.
id Grid control ID.
0 Always zero.
$$ Always null.
The following template can be used:
width:u(1),height:u(1),leading:u(1),ascent:u(1),descent:u(1),
size:u(2),style:u(2),charset:u(2),family:c(1*=)
Get Number of Columns - GRID SENDMSG() Function 40

Syntax
COLUMNS$=SENDMSG(sysgui,id,40,0,$$)
Description
This function returns a binary representation of the number of columns in the grid. Use DEC(COLUMNS$) to get the numeric
representation.
id Grid control ID.
0 Always zero.
$$ Always null.
Get Number of Rows - GRID SENDMSG() Function 41

Syntax
ROWS$=SENDMSG(sysgui,id,41,0,$$)
Description
This function returns a binary representation of the number of rows in the grid. Use DEC($00$+ROWS$) to get the numeric
representation.
id Grid control ID.
0 Always zero.
$$ Always null.
253
Get Row Height - GRID SENDMSG() Function 42
Syntax
HEIGHT$=SENDMSG(sysgui,id,42,row,$$)
Description
This function returns a binary representation of the height of the specified row, in pixels. Use DEC(HEIGHT$) to get the numeric
representation.
id Grid control ID.
row Row number (zero-based).
$$ Always null.
Note that row numbering is zero-based.
Get Number of Visible Rows - GRID SENDMSG() Function 43

Syntax
Description
This function returns a binary representation of the maximum number of rows that can be displayed in the main body of the grid,
based on the current row height. Use DEC(ROWS$) to get the numeric representation.
id Grid control ID.
0 Always zero.
$$ Always null.
Get Selected Column - GRID SENDMSG() Function 44

Syntax
COLUMN$=SENDMSG(sysgui,id,44,0,$$)
Description
This function returns the binary representation of the currently selected column. Use DEC(COLUMN$) to get the numeric
representation.
id Grid control ID.
0 Always zero.
$$ Always null.
If row highlighting is enabled instead of the default of cell highlighting, this function returns the number of the column shown at the
left side of the grid. Note that column numbering is zero-based.
See also Set Cell/Row Highlight - Grid SENDMSG() Function 49.
254
Get Selected Row - GRID SENDMSG() Function 45
Syntax
ROW$=SENDMSG(sysgui,id,45,0,$$)
Description
This function returns the binary representation of the currently selected row. Use DEC($00$+ROW$) to get the numeric
representation.
id Grid control ID.
0 Always zero.
$$ Always null.
Get Top Row - GRID SENDMSG() Function 46

Syntax
ROW$=SENDMSG(sysgui,id,46,0,$$)
Description
This function returns the number of the row that is currently at the top of the grid's window. Use DEC($00$+ROW$) to get the
numeric representation.
id Grid control ID.
0 Always zero.
$$ Always null.
Goto Column - GRID SENDMSG() Function 47

Syntax
COLUMN$=SENDMSG(sysgui,id,47,column,$$)
Description
This function sets the column specified as the current column. Normally this function should not be used if row highlighting is
enabled. If the column exists and is not currently visible, it is scrolled into view. Use DEC(COLUMN$) to retrieve the numeric
value.
id Grid control ID.
column New column number (zero-based).
$$ Always null.
Note that column numbering is zero-based. The returned value is determined by the following conditions:
255
• If the column does not exist, the binary representation of the current column is returned.
• If the column exists and cell highlighting is enabled (the default), the binary representation of the new current column is
returned.
• If the column exists and row highlighting is enabled, the binary representation of the leftmost visible column is returned.
See also Set Cell/Row Highlight - Grid SENDMSG() Function 49.
Goto Row - GRID SENDMSG() Function 48

Syntax
ROW$=SENDMSG(sysgui,id,48,row,$$)
Description
This function sets the row specified as the current row. Use DEC($00$+ROW$) to get the numeric representation.
id Grid control ID.
row New row number (zero-based).
$$ Always null.
Row numbering is zero-based. Note the following:
• If the row exists and is not currently visible, it will be scrolled into view.
• If the row exists, the binary representation of the new current row is returned.
• If the row parameter is greater than the current number of rows in the grid, the binary representation of the number of the last
row is returned.
Set Cell/Row Highlight - GRID SENDMSG() Function 49

Syntax
NULL$=SENDMSG(sysgui,id,49,highlight_mode,$$)
Description
This function sets the highlight mode for cells and rows.
id Grid control ID.
highlight_mode Zero value causes current cell to be highlighted. Nonzero value causes current row to be
highlighted.
$$ Always null.
There are two modes for grid highlighting. The default is to highlight the current cell. The other mode is to highlight the current row.
If highlight_mode is zero, the current cell is highlighted. If highlight_mode is nonzero, the current row is highlighted. The return
value is a null string.
Redraw Row - GRID SENDMSG() Function 50

Syntax
TF$=SENDMSG(chan,id,50,row,$$)
256
Description
This function instructs the grid control to redraw the specified row.
id Grid control ID.
row Row number (zero-based).
$$ Always null.
Note that row numbering is zero-based. If the row exists, $01$ is returned. If the row does not exist, $00$ is returned. The return
value is $01$ if row exists, or $00$ if row does not exist.
Note that when a standard grid is redrawn, it may need grid data from the application. The control requests data by sending a
Notify event 22 or 23 to the application. All programs that use a grid control must check for these events and respond to them, or
blank cells may appear in the grid.
Set Heading Shadow Height - GRID SENDMSG() Function 51

Syntax
HEIGHT$=SENDMSG(sysgui,id,51,height,$$)
Description
This function sets the height of the shadows that create a three-dimensional effect on heading grids. The default is 2 pixels. The
binary representation of the new shadow height is returned. Use DEC(HEIGHT$) to get the numeric representation.
id Grid control ID.
height Shadow height, in pixels.
$$ Always null.
Set Heading Dark Shadow Color - GRID SENDMSG() Function 52

Syntax
NULL$=SENDMSG(sysgui,id,52,rgb$,$$)
Description
This function sets the color of the dark shadows that create a three-dimensional effect on heading grids. The rgb$ parameter is a
$RRGGBB$ formatted string that defines the RGB value of the dark shadow color. The return value is a null string.
id Grid control ID.
rgb$ RGB value.
$$ Always null.
257
Set Heading Light Shadow Color - GRID SENDMSG() Function 53
Syntax
NULL$=SENDMSG(sysgui,id,53,rgb$,$$)
Description
This function sets the color of the light shadows that create a three-dimensional effect on heading grids. The rgb$ parameter is a
$RRGGBB$ formatted string that defines the RGB value of the light shadow color. The return value is a null string.
id Grid control ID.
rgb$ RGB value.
$$ Always null.
Draw Cell - GRID SENDMSG() Function 54

Syntax
TF$=SENDMSG(sysgui,id,54,0,grid_information_block$)
Description
This function is the most powerful function to set cell characteristics for one cell and display data in that cell. It works on heading
grids as well as main grids.
id Grid control ID.
0 Always zero.
grid_information_block$ String that contains the grid information block.
Depending on the fields set in the grid_information_block$ parameter, one invocation of the Draw Cell function can do any or all of
the following in a cell:
The power of the function comes from the grid information block, which is a templated string that controls the characteristics of the
target cell and the data to be displayed in it. The template for this string follows:
msg:u(4),wparm:u(4),lparm:i(4),col:u(4),row:u(4),textcolor:c(3),backcolor:c(3),
alignment:u(1),style:i(4),imgidx:i(4),x:i(2),y:i(2),
w:u(2),h:u(2),ptx:i(2),pty:i(2),buf:c(1*)
Use the TMPL() function with an index of 1 to retrieve this template. For example:
dim grid_info$:TMPL(sysgui,ind=1)
The relevant fields in the grid information block are described below:
Grid Information Block Field Description
COL Column that the target cell is in. Note that column numbering is zero-based.
ROW Row that the target cell is in. Note that row numbering is zero-based.
TEXTCOLOR RGB color string for text.
BACKCOLOR RGB color string for background.
ALIGNMENT Controls the alignment of text in the cell:
0 = Left alignment
258
1 = Right alignment
2 = Centered
STYLE Controls the appearance of the cell. If this function is used on a cell and style is not
set, the default appearance of heading and main grid cells is to look like raised
buttons. Main grid cells can have their style changed to any of the styles listed below.
Heading grid cells can only be changed to look like recessed buttons. Other style
settings for heading grids are ignored.
0 = INPUTE control.
1 = Raised button appearance created by shading two sides of the cell.
2 = Recessed button appearance created by shading two sides of the cell.
4 = Checked checkbox, with text, if any, displayed to the right of the checkbox.
8 = Unchecked check box, with text, if any, displayed to the right of the checkbox.
IMGIDX Index of an imagelist. The imagelist must already be defined, and the grid must have
been informed which imagelist to use with a SENDMSG() Function 75.
BUF$ Text to be displayed in cell.
failure. By adjusting the style, the grid control can be made to simulate embedded buttons and checkboxes. Clicking on these
simulated buttons and checkboxes does not generate any special event code. To simulate the operation of these controls, the
application must check for mouse clicks or double-clicks on the cells and react by redrawing them with a different style setting.
Examples
The following example shows Draw Cell - Grid SENDMSG() Function 54 used to change the background color, set checkbox
styles, and display text in two cells:
print (sysgui)'window'(0,20,550,100,"Grid Sample",$00000082$,$ff$)
dim grid$:tmpl(sysgui,ind=1); rem DIMension grid information block
grid$=sendmsg(sysgui,100,20,0,$$); rem initialize grid information block
grid.backcolor$=$ffccff$,grid.buf$="checkbox"
grid.style=4,grid.col=1,grid.row=1; rem create checked checkbox
grid.style=8,grid.col=2,grid.row=1; rem create checked checkbox
escape
The following example shows SENDMSG() Function 54 used to change default grid appearance and populate a grid with data:
grid.style=1; rem set cell style to raised button
counter=0
for col=0 to 2
259
for row=0 to 2
rem Instruct SENDMSG(54) which cell to manipulate
rem Set display buffer to loop counter.
grid.buf$=str(counter)
counter=counter+1
next row
next col
escape
The following example shows SENDMSG() Function 54 used to create a checkerboard pattern with varying background colors
and styles. Note that by setting values for grid.buf$, this code could also display data in the grid:
counter=0
for col=0 to 2
for row=0 to 2
rem Instruct SENDMSG(54) which cell to manipulate
rem Based on counter value, set style and background color
if mod(counter,2) then
: grid.style=2,grid.backcolor$=$ffcc00$
: else
: grid.style=0,grid.backcolor$=$ffffff$
counter=counter+1
next row
next col
escape
Set Default Background Color - GRID SENDMSG() Function 55

Syntax
NULL$=SENDMSG(sysgui,id,56,0,rgb$)
Description
This function sets the default background color for the grid.
260
id Grid control ID.
0 Always zero.
rgb$ RGB value.
The rgb$ parameter is a $RRGGBB$ formatted string that defines the RGB value of the background color. The default color can
be overridden in individual cells in a standard grid with Draw Cell - Grid SENDMSG() Function 54.
This function produces unpredictable behavior in a grid that has been made data-aware, so it should be used before binding the
grid to a data channel with Set Channel and Template - SENDMSG() Function 80..The background color for each column can be
changed by using the BCOLOR attribute with SENDMSG() Function 80.
The return value is a null string.
Set Default Text Color - GRID SENDMSG() Function 56

Syntax
NULL$=SENDMSG(sysgui,id,56,0,rgb$)
Description
This function sets the default text color for the grid.
id Grid control ID.
0 Always zero.
rgb$ RGB value.
The rgb$ parameter is a $RRGGBB$ formatted string that defines the RGB value of the text color. The default color can be
overridden in individual cells in a standard grid with Draw Cell - Grid SENDMSG() - Function 54.
This function produces unpredictable behavior in a grid that has been made data-aware and should be used before binding the
grid to a data channel with Set Channel and Template—SENDMSG() Function 80.The text color for each column can be changed
by using the TCOLOR attribute with SENDMSG() Function 80.
Example
The following example displays a grid with green text:
result$=sendmsg(sysgui,100,56,0,$00ff00$); rem set text to green
for col=0 to 2
next col
result$=sendmsg(sysgui,100,57,0,$$)
for row=0 to 2
for col=0 to 2
let tf$=sendmsg(sysgui,100,22,col,str(col))
next col
261
next row
escape
Set Highlight Method - GRID SENDMSG() Function 57

Syntax
NULL$=SENDMSG(sysgui,id,57,highlight_method,$$)
Description
This function sets the method in which cells are highlighted.
id Grid control ID.
highlight_method Zero value sets highlight method to rectangle. Nonzero value sets highlight method to color
change.
$$ Always null.
There are two ways a grid control can highlight the current cell or row. The default is to highlight the current cell or row with the
default highlight colors. The other highlight method is to draw a rectangle around the current cell or row without changing colors. If
highlight_method is zero, the rectangle highlight is used. highlight_method is nonzero, the color change highlight is used. The
return value is a null string.
Set Horizontal Lines - GRID SENDMSG() Function 58

Syntax
LINEMODE$=SENDMSG(sysgui,id,58,line_flag,$$)
Description
This function controls the display of horizontal lines between rows in the body of the grid.
id Grid control ID.
line_flag Nonzero value causes horizontal lines to be displayed. Zero value causes horizontal lines to be
suppressed.
$$ Always null.
If the line_flag parameter is nonzero, horizontal lines will be displayed. If the line_flag parameter is zero, horizontal lines will not be
displayed. The new setting is returned in binary format. This function has no effect on headings. The return value is $01$ if lines
displayed. $00$ if lines not displayed.
Set Horizontal Scroll Mode - GRID SENDMSG() Function 59

Syntax
NULL$=SENDMSG(sysgui,id,59,scroll_mode,$$)
Description
This function controls how the columns in the grid control will scroll. The return value is a null string.
id Grid control ID.
262
scroll_mode Scroll mode. If set to 0, , the user can scroll to the right until the rightmost column is the only column
visible, and is flush to the left side of the grid. If other than 0, scrolling stops when the rightmost
column is visible The right edge of this column will line up with the right edge of the grid's client area.
$$ Always null.
Set Interspace - GRID SENDMSG() Function 60

Syntax
INTERSPACE$=SENDMSG(sysgui,id,60,interspace,$$)
Description
This function sets the interspace, which along with the row height, makes up the total height of the cells in a grid.
id Grid control ID.
interspace Interspace, in pixels.
$$ Always null.
The default row height is based on the grid's font. The default interspace is zero. Use this function to make cells higher than the
default. This function has no effect on column headers. The return value is a binary representation of the new interspace. Use
DEC($00$+INTERSPACE$) to get the numeric representation.
Set Line Color - GRID SENDMSG() Function 61

Syntax
RGB$=SENDMSG(sysgui,id,61,line_type,rgb$)
Description
This function sets the color of the separation lines within the specified grid control.
id Grid control ID.
line_type Zero value changes vertical line color. Nonzero value changes horizontal line color.
rgb$ RGB value.
The function affects horizontal or vertical lines depending on the value of the line_type parameter. If line_type is 0, the vertical line
color is defined. If line_type is 1, the horizontal line color is defined. The rgb$ parameter is a $RRGGBB$ formatted string that
defines the RGB value of the line color. The return value is the default pen color. The return value is the RGB value of the default
pen color.
Set Margin - GRID SENDMSG() Function 62

Syntax
NEWMARGIN$=SENDMSG(sysgui,id,62,margin,$$)
Description
This function always sets the left margin for text display in the main grid, and may set the right margin (The default is to set just the
left margin--see Set Margin Mode - Grid SENDMSG() Function 63 ).
263
id Grid control ID.
margin Margin setting, in pixels.
$$ Always null.
The margin parameter sets the margin(s) in pixels. The new setting is returned in binary format if the operation is successful. Use
DEC(NEWMARGIN$) to get the numeric representation. This function does not apply to heading grids. The return value is a
binary representation of the new margin setting if the operation is successful. If the operation is not successful, $00$ is returned.
See also Set Margin Mode - Grid SENDMSG() Function 63.
Set Margin Mode - GRID SENDMSG() Function 63

Syntax
NULL$=SENDMSG(sysgui,id,63,margin_mode,$$)
Description
This function toggles the margin mode to apply the margin setting to both margins or just the left margin.
id Grid control ID.
margin_mode 1 applies margin setting to both margins. Zero applies margin setting to just the left margin.
$$ Always null.
By default, Set Margin SENDMSG() - Function 62 applies to just the left margin. The return value is a null string. Note that the
right margin cannot be different from the left margin, unless it is zero.
Set Mouse Capture Mode - GRID SENDMSG() Function 64

Syntax
NULL$=SENDMSG(sysgui,id,64,capture_mode,$$)
Description
This function sets the mouse capture mode for main grids.
id Grid control ID.
capture_mode Zero value turns on mouse capture mode. 1 turns off mouse capture mode.
$$ Always null.
Setting the capture_mode parameter to 1 causes the grid control to capture mouse movements and report the position of the
mouse 10 times per second with MOUSECAPTURE Notify events (Notify code 17). Setting the capture_mode parameter to 0
causes the grid control to stop generating MOUSECAPTURE events. Typically, the mouse capture mode is toggled in response to
an LCLICKED or RCLICKED Notify event (Notify codes 14 and 18). The return value is a null string.
See also Set Mouse Scrolling Mode - Grid SENDMSG() Function 65.
264
Set Mouse Scrolling Mode - GRID SENDMSG() Function 65
Syntax
NULL$=SENDMSG(sysgui,id,65,mouse_move_mode,$$)
Description
This function toggles the mouse scrolling behavior. The default behavior of a grid control when a user clicks on a cell and drags
the mouse off one edge of the grid window is for the grid to scroll in the direction of the mouse movement until the mouse is
released.
id Grid control ID.
mouse_move_mode 1 disables mouse scrolling. Zero enables mouse scrolling.
$$ Always null.
If mouse_move_mode is 1, mouse scrolling is disabled. If mouse_move_mode is zero, mouse scrolling is enabled. The return
value is a null string.
Set Number of Columns - GRID SENDMSG() Function 66

Syntax
COLS$=SENDMSG(sysgui,id,66,cols,$$)
Description
This function sets the number of columns in the specified grid control.
id Grid control ID.
cols Number of columns. Valid values are 0 to 255.
$$ Always null.
A grid may have 0 to 255 columns. The number of columns can be changed at any time but cannot exceed the maximum number
of columns specified when the grid was created. If the number of columns specified exceeds the maximum, only the maximum
number of columns will be set. This function is valid only for main grids, not heading grids. Heading grids are automatically
updated if they exist.
Note that this message does not change the size of the grid control, so reducing the number of columns may cause the right side
of the grid's space to go blank.
The return value is a binary representation of the number of columns actually set by this message. Use DEC(COLS$) to get the
numeric representation.
Example
The following example creates a grid with three columns and reduces the number of columns to two:
print (sysgui)'window'(0,20,650,120,"Grid Sample",$00000082$,$FF$)
print (sysgui)'grid'(100,20,20,580,74,$0866$,3,3,5,18,101,30,102)
cols$=sendmsg(sysgui,100,66,2,$$)
print dec(cols$)
escape
265
Set Number of Rows - GRID SENDMSG() Function 67
Syntax
ROWS$=SENDMSG(sysgui,id,67,rows,$$)
Description
This function sets the number of rows in the specified grid control.
id Grid control ID.
rows Number of rows. Valid values are 0 to 2,100,000,000.
$$ Always null.
A grid may have 0 to 2.1 billion rows. This function is valid only for main grids, not heading grids. Heading grids are automatically
updated if they exist. Note that this function does not change the size of the grid control, so reducing the number of rows may
cause the bottom part of the grid's space to go blank. The return value is a binary representation of the number of rows set by this
message. Use DEC($00$+ROWS$) to get the numeric representation.
Example
The following example creates a grid with three rows and reduces the number of rows to two:
print (sysgui)'window'(0,20,650,120,"Grid Sample",$00000082$,$FF$)
print (sysgui)'grid'(100,20,20,580,74,$0866$,3,3,5,18,101,30,102)
rows$=sendmsg(sysgui,100,67,2,$$)
print dec($00$+rows$)
escape
Set Row Height - GRID SENDMSG() Function 68

Syntax
ROWHEIGHT$=SENDMSG(sysgui,id,68,rowheight,$$)
Description
This function adjusts the height of main (not heading) grid rows.
id Grid control ID.
rowheight Row height, in pixels.
$$ Always null.
The height is set in pixels. The default row height is based on the grid font, so normally there is no reason to adjust this setting
unless you want to reduce the white space around text in cells or enlarge cells so the grid body will fill the area defined for it.
Another way to make cells higher than the default is to adjust the interspace setting with SENDMSG() Function 60.
Note that the grid control will not display a truncated row, so using this function may reduce or enlarge the space occupied by the
grid. The return value is a binary representation of the new row height. Use DEC(ROWHEIGHT$) to get the numeric
representation.
266
Example
The following example creates a grid 120 pixels high with three rows and expands the rows to 50 pixels high. Because three rows
will not fit in the available space, two rows are displayed and the grid uses less than the full 120 pixels.
sysgui=unt;open (sysgui)"X0"
result$=sendmsg(sysgui,100,68,50,$$); rem row height
for col=0 to 2
next col
escape
See also Set Interspace – SENDMSG() Function 60.
Set Thumb Update Mode - GRID SENDMSG() Function 69

Syntax
UPDATE_MODE$=SENDMSG(sysgui,id,69,update_mode,$$)
Description
This function sets the vertical scroll bar thumb update mode.
id Grid control ID.
update_mode Nonzero value causes the grid control to update rows continuously as the user drags the vertical
scroll bar thumb. Zero value causes the grid to wait until after the thumb stops moving to update.
$$ Always null.
If the update_mode parameter is 1, the main grid (not the row heading grid) will be continuously updated as the user drags the
vertical scroll bar thumb. If the update_mode parameter is zero, the grid will not be updated until the user has finished dragging
the thumb. The new update mode is returned as a binary string. The return value is a binary representation of the update mode.
Use DEC(UPDATE_MODE$) to get the numeric representation.
Set Top Row - GRID SENDMSG() Function 70

Syntax
TOP_ROW$=SENDMSG(sysgui,id,70,row,$$)
Description
This function displays the specified row at the top of the grid window. Note that row numbering is zero-based. The binary
representation of the new top row is returned if the operation is successful. If the operation fails, $00$ is returned. Use
DEC($00$+TOP_ROW$) to get the numeric representation.
id Grid control ID.
row Number of new top row (zero-based).
$$ Always null.
267
Set Vertical Scroll Mode - GRID SENDMSG() Function 71
Syntax
NULL$=SENDMSG(sysgui,id,71,scroll_mode,$$)
Description
This function sets the vertical scroll mode for the grid control.
id Grid control ID.
scroll_mode Sets the vertical scroll mode.
• Entering a zero value causes the grid control to display all the appropriate records after each
movement of the vertical scroll bar thumb. This is the default mode.
• Setting a nonzero value restricts the thumb to three positions and causes the grid to scroll one row
after each click on a scroll bar arrow. This mode is recommended for grids with large amounts of
data.
$$ Always null.
Set Vertical Lines - GRID SENDMSG() Function 72

Syntax
LINEMODE$=SENDMSG(sysgui,id,72,line_flag,$$)
Description
This function controls the display of vertical lines between columns in the body of the grid.
id Grid control ID.
line_flag Nonzero value causes vertical lines to be displayed. Zero value causes vertical lines to be
suppressed.
$$ Always null.
If the line_flag parameter is nonzero, vertical lines will be displayed. If the line_flag parameter is zero, vertical lines will not be
displayed. The new setting is returned in binary format. This function has no effect on headings. The return value is $01$ if lines
are displayed, or $00$ if lines are not displayed.
Get String Width - GRID SENDMSG() Function 73

Syntax
WIDTH$=SENDMSG(chan,id,73,0,string$)
Description
This function uses the grid's current font to calculate the width of the specified string and returns it in binary format.
id Grid control ID.
0 Always zero.
268
string$ String to be analyzed.
Use DEC($00$+WIDTH$) to get the numeric representation. The return value is a binary representation of the width of the passed
string, in pixels.
Set User Resize - GRID SENDMSG() Function 74

Syntax
NULL$=SENDMSG(sysgui,id,74,user_resize_flag,$$)
Description
This function controls whether the user will be able to resize the width of columns in the grid with a mouse.
id Grid control ID.
user_resize_flag Zero value turns off user resize capability. Nonzero value turns on user resize capability.
$$ Always null.
If the user_resize_flag parameter is nonzero, users will be able to resize columns. If the parameter is zero, users will not be able
to adjust the widths of columns. The return value is a null string.
Set Image List ID - GRID SENDMSG() Function 75

Syntax
TF$=SENDMSG(sysgui,id,75,image_list_id,$$)
Description
Use this function in conjunction with Draw Cell - SENDMSG() Function 54 to display an image in a cell. This function sets the ID of
an image list recognized by the SYSGUI device. Set the IMGIDX parameter in the grid information block to specify which image in
the list should be displayed.
id Grid control ID.
image_list_id Control ID of image list.
$$ Always null.
The image list may have been defined by the ‘IMAGELIST' mnemonic or by loading a resource that has an image list defined . The
image_list_id parameter identifies the control ID of the image list to use on the SYSGUI channel. The image depth may not
exceed 8 bits (256 colors). The returned value indicates the success or failure of the operation; $01$ indicates success, $00$
indicates failure.
See also Draw Cell - Grid SENDMSG() Function 54 , ‘IMAGELIST’ mnemonic, ResBuilder Image list.
Redraw Grid - GRID SENDMSG() Function 76

Syntax
NULL$=SENDMSG(chan,id,76,0,$$)
Description
This function instructs the grid control to redraw itself and causes the grid to request data by sending a Notify event 22 to the
application. All programs that use a standard grid control must check for this event and respond to it, or blank cells may appear in
the grid.
269
id Grid control ID.
0 Always zero.
$$ Always null.
Set Current Heading Mode - GRID SENDMSG() Function 77

Syntax
MODE$=SENDMSG(sysgui,id,77,mode,$$)
Description
Optionally, a grid control's row and column headings for the current cell can appear as depressed buttons. This function controls
whether this mode is enabled. Set the mode parameter to 1 to display row and column headings as depressed buttons. Set the
mode parameter to 0 to disables this behavior. The binary representation of the current mode setting is returned. Use
DEC(MODE$) to get the numeric representation. The return value is a binary representation of the current mode.
id Grid control ID.
mode 1 to display selected row and column headings as depressed buttons. Zero to not change display of
selected row and column headings.
$$ Always null.
Set Cursor - GRID SENDMSG() Function 78

Syntax
TF$=SENDMSG(sysgui,id,78,0,cursorfile$)
Description
This function sets the cursor used for grid drag-and-drop operations.
id Grid control ID.
0 Always zero.
cursorfile$ Path and file name of a Windows .cur or .ani cursor file. Using an empty string resets the cursor to
the default.
The cursorfile$ parameter specifies the path of a Windows .cur or .ani cursor file. Data server paths are not supported. The
returned value indicates the success or failure of the operation; $01$ indicates success, $00$ indicates failure. The only known
reasons for a failure would be an invalid or missing cursor file or an out of memory condition. The return value is a one-byte string
that indicates the success or failure of an operation; $01$ indicates success; $00$ indicates failure.
Set Edit Mask - GRID SENDMSG() Function 79

Syntax
TF$=SENDMSG(sysgui,id,79,column,mask$)
270
Description
This function sets the edit mask defined in the mask$ parameter for the specified column. The edit mask follows the conventions
for INPUTE control masks.
id Grid control ID.
column Column number (zero-based).
mask$ Edit mask.
Note that column numbering is zero-based. The return value is a one-byte string that indicates the success or failure of an
operation; $01$ indicates success; $00$ indicates failure.
Set Channel and Template - GRID SENDMSG() Function 80

Syntax
TF$=SENDMSG(sysgui,id,80,channel,template$)
Description
This function binds the grid to a Visual PRO/5 SELECT, SQL SELECT, or an MKEYED file channel that has already been opened
on the specified channel.
id Grid control ID.
channel Visual PRO/5 SELECT, SQL SELECT, or MKEYED file channel. Use the negative value of SQL
SELECT channels.
template$ Template describing the records read on the channel. Each template field can contain any number of
user-defined attributes, as described in the table below. Note that these attributes are case-sensitive
and must be entered in upper case. Because spaces are delimiters for user-defined attributes,
underscores must be substituted for spaces when they are needed in labels and masks.
Once the channel is passed to the grid via this function, the program should not manipulate it. Do not read from the channel, write
to it, or change the record pointer.
Attribute Description Example
SHOW Directs the grid to display or hide the identified grid This template creates two columns in the grid control:
column. If the attribute is unspecified, or the attribute is
set to 1, the field is displayed. If the attribute is set to "cust_number:c(1*):SHOW=0:,
zero the field is not displayed. first_name:c(1*):SHOW=1:,
last_name:c(1*):SHOW=1:"
MASK Specifies the field's edit mask, which follows the The following specifies an edit mask for a North
INPUTE control's masking conventions. (Cannot be American-style telephone number:
used in conjunction with the length attribute.) Use the
underscore character ('_') to indicate spaces in the "phone:c(10):MASK=(000)000-0000:"
mask.
OMASK Optional output mask to apply to fields when they are "amount:n(4):OMASK=$##,##0.00"
displayed in the grid but not being edited. If the mask is
used to force spaces in the display, use the underscore
character ('_') in the mask to indicate each space.
LABEL Sets the field's column heading grid label. If this "first:c(1*):LABEL=first_name:"
attribute is omitted, the field name is used by default,
unless the column heading is explicitly set by the
program. If spaces are required, use the underscore
character ('_') in the label text. Underscores will be
removed when the column heading displays.
271
LENGTH Limits the field length. (Cannot be used in conjunction "first:c(1*):LENGTH=15:"
with the mask attribute.)
ALIGN Sets the column alignment. If the attribute is set to 0, The following centers the "first" field:
the data will be left-justified. If the attribute is set to 1,
the data will be right-justified. If the attribute is set to 2, "first:c(1*):ALIGN=2:"
the data will be centered.
STYLE Sets the column style. The style parameter values are The following sets the raised button style for the "first"
identical to the values used in the style field of the grid field:
information block. See Set Default Style, SENDMSG()
Function 83 for details. "first:c(1*):STYLE=1:"
TCOLOR Sets the column text color, using a hex representation The following sets the text color of the "first" field to
of the RGB() color. black:
"first:c(1*):TCOLOR=$000000$:"
BCOLOR Sets the column background color, using a hex The following sets the background color of the "first"
representation of the RGB() color. field to white:
"first:c(1*):BCOLOR=$ffffff$:"
CVSIN Sets the value of the CVS() function described on page The following strips white space before the "first" field
48 of the Commands Manual) to apply to a field before can be edited:
it is edited.
"first:c(1*):CVSIN=3:"
CVSOUT Sets the value of the CVS() function to apply to the The following strips white space before the first" field is
field before displaying it. displayed:
"first:c(1*):CVSOUT=3:"
If the channel is set to zero, the grid resets and is no longer data-aware. The application is responsible for closing the channel
passed to the grid. To specify an SQL SELECT file channel, specify the negated value of the open channel. This convention
allows the grid control to distinguish an SQL channel (opened with the SQLOPEN verb) from a channel opened with an OPEN
verb. For example, if sqlchan is a value used with an SQLOPEN() verb, the following syntax might be used:
TF$=SENDMSG(sysgui,id,80,-sqlchan,template$)
If the channel is an SQL SELECT channel, the program must have already performed the SQLPREP() and SQLEXEC() verbs.
The grid control will manage the SQLFETCH() calls.
The data-aware grid works with at least two channels: the input channel passed by Set Channel and Template, SENDMSG()
Function 80, and the channel for the temporary file created to manage the displayed grid. If the grid is expected to handle a very
large number of records, ensure that the TMP, TEMP, or TMPDIR environment variables are set to a location that can handle the
temporary file, which is removed when the grid is destroyed or another call is issued to the grid to set a new channel. The
temporary file channel references a single-keyed MKEYED file that contains the query result for Visual PRO/5 SELECTs or SQL
SELECTs, or it references a single-keyed MKEYED file that is an index file for an editable multi-keyed file. If the grid allows
editing, two more channels may be used to update and validate records. The application should be designed to support the
considerable resources needed to operate a data aware grid control.
For SQL SELECT and Visual PRO/5 SELECT channels performing SELECT operations on read-only files, or for MKEYED file
channels that lack write permissions, the grid is set to read-only mode. A grid can also be set to read-only by sending the $01$
value to the grid with Perform Data-Aware Function - Grid SENDMSG() Function 81.
For a writeable MKEYED file or SELECT channel that refers to a writeable MKEYED file, the grid can be edited unless it has
explicitly been set to read-only. The update operation is governed by the rules described below and is performed on the file being
used by the SELECT channel. This is done by opening the file internally. This internal channel is closed automatically when the
grid is destroyed or a new channel is set using this message.
Data is read from the channel according to the initial channel setup. Therefore, for a SELECT or SQL SELECT channel, the order
is determined up by the sort clause that is part of the operation itself. If the channel is a multi-keyed MKEYED file, the user
program sets the key chain and the data is read in that order. Usually, only read records are issued on the input channel.
Channel Insert/Delete/Update Rules

The following describes the rules for writeable MKEYED files or SELECT channels that refer to writeable MKEYED files. For all
the operations described below, an EXTRACT RECORD is performed before the operation takes place.
If a locked record is encountered during any of the initial EXTRACTs, the operation is canceled and an ERROR Notify event
message is sent to the application. Duplicate or Missing errors suspend the operation. Deleting a row deletes the corresponding
record in the file and sends a ROWDELETE Notify event (Notify code 25) to inform the program of the deletion.
272
Records to be removed are first extracted on the update channel, then removed. A tag in the header of the affected row displays a
tag, indicating that the row has been removed. No further editing is allowed on the row. If the extract fails because of a duplicate or
missing record, the record is simply marked as "removed" and an error message is sent to the application.
Inserting a row inserts a record in the corresponding file and puts the inserted row into edit mode on the first column. The record is
automatically updated when the user moves focus from the inserted row. If the record is successfully written to the file, a
ROWINSERT Notify event message is sent to inform the program of the record insert. If the record cannot be written a message
box prompts the user to abort the insert operation and delete the new row or continue entering information into the row. The
default text is "Record Incomplete! Continue editing?". This text can be changed with Set Continue Message - Grid SENDMSG()
Function 82. If the user aborts the insert, the grid sends a ROWCANCEL Notify event to inform the program of the insert
cancellation.
Records can only be inserted at the end of the grid. Therefore, if an insert operation is initiated, the grid moves to the end of the
data that has already been read and displays a new empty row which is tagged "new" in the row header. The grid then goes into
an update state without an existing record.
When the application determines the user wants to edit a row/record, it should send a message to the cell(s) via Start Edit - Grid
SENDMSG() Function 31 to enter edit mode. During editing, the grid locks the record on a verify channel, and it is released when
the editing is completed via a cancel command from the application or the user, or when the user changes focus to a different row.
If the update is not canceled, the new record is extracted to ensure that it does not already exist. If the record exists, the current
row is forced back to the user row and an ERROR notify message is sent to the application for handling. If the new record does
not already exist, the old record is removed on the verify channel and the new record is written. The grid sends a ROWUPDATE
Notify event to inform the program of the update. The return value is a one-byte string that indicates the success or failure of an
operation; $01$ indicates success, $00$ indicates failure.
Visual Clues During Grid Operations

The grid will give two types of visual clues to the user indicating the status of records: record status icons in the left column or row
header, and asterisks in all fields of unavailable records. Records that are locked on another channel display all fields as asterisks,
and a locked icon displays in the row header, if there are row headers, or the left column if there are no row headers. When a new
record is added, an add icon displays in the left column if there are no row headers. This icon persists after the record is added. If
there are row headers, no icon displays. When a record is edited, an update icon displays in the left column if there are no row
headers. This icon persists after the editing is completed. If there are row headers, no icon displays.
After a record has been deleted, all fields display as asterisks, and a delete icon displays in the row header, if there are row
headers, or the left column if there are no row headers. The only way to remove a deleted record's row from the grid display is to
disconnect the grid from the data channel by sending a SENDMSG() Function 80 with a channel number of zero, then reattach the
grid with another SENDMSG() Function 80 (see the Data-Aware Grid Tutorial for a example of this). The icons displayed after a
record is added or edited can be removed with the same process.
Errors
!ERROR=1 is returned if the minimum required record size for the specified template is larger than the file’s record size.
!ERROR=14 is returned if the channel number specified is not open.
!ERROR=26 is returned if the template includes any incorrect template definition syntax.
Example
The following code sample creates a window and grid, sets up a template called DATAREC_DESC$, opens a PRO/5 select
channel, then binds the channel to the grid. The data file, datagrid.dat, is distributed with GUIBuilder and is available on the
BASIS Web site. The template definition sets column headings for the displayed fields, and an input field length of 50 is specified
for the TITLE field:
dim event$:tmpl(sysgui)
event=len(event$)
print (sysgui)'window'(0,20,390,120,"",$00000082$,$ff$)
print (sysgui)'grid'(100,20,20,360,84,$8842$,3,3,5,15,101)
datarec_desc$="cdnumber:c(6*=10):SHOW=1 LABEL=Number:,"+
: "title:c(50*=10):SHOW=1 LENGTH=50 LABEL=Title:"
sel_chan=unt; select (sel_chan)datarec$ from "datagrid.dat"
tf$=sendmsg(sysgui,100,80,sel_chan,datarec_desc$)
273
escape
Perform Data-Aware Function - GRID SENDMSG() Function 81

Syntax
RESULT$=SENDMSG(sysgui,id,81,row,function$)
Description
This function performs five different operations on a data-aware grid, depending on the value of function$. The returned value is
the specified record if the function$ parameter is $04$. Otherwise, the return value is a one-byte string that indicates the success
or failure of an operation; $01$ indicates success, $00$ indicates failure.
id Grid control ID.
row Row number (zero-based) or ignored.
function$ Specific function.
The following identifies the possible values for the function$ string:
function$ Value Description
$01$ Sets the grid to read-only mode. The row parameter is ignored.
$02$ Flags the specified row as deleted and removes the corresponding record in the MKEYED
file. Note that row numbering is zero-based.
$03$ Adds a row to the grid and enters edit mode, allowing the user to enter a new record. When
focus is moved from the edited row, the grid control attempts to write the new record. If the
entire primary key is not available, a "Continue/Abort" message box is displayed. The row
parameter is ignored.
$04$ Returns the record contained in the specified row. Note that row numbering is zero-based.
$05$ Cancels a record update command. This can also be performed by End Edit - Grid
Set Continue Message - GRID SENDMSG() Function 82

Syntax
NULL$=SENDMSG(sysgui,id,82,0,msg$)
Description
This function sets the "Continue/Abort" message to be displayed when the grid control does not have a primary key and cannot
write a new record. The msg$ parameter specifies two substrings, each terminated with a linefeed ($0A$). The first substring
specifies the title of the message box. The second substring specifies the message itself. The return value is a null string.
id Grid control ID.
0 Always zero.
msg$ Message box title and message, each terminated with a linefeed ($0A$) character.
274
Set Default Style - GRID SENDMSG() Function 83
Syntax
NULL$=SENDMSG(sysgui,id,83,style,$$)
Description
This function sets the default cell style for a grid. The system default is INPUTE style.
id Grid control ID.
style Default cell style.
$$ Always null.
grid to a data channel with Set Channel and Template - SENDMSG() Function 80.The style for each column can be changed by
using the STYLE attribute with SENDMSG() Function 80.
The style parameter values are identical to the values used in the style field of the grid information block:
style Value Description

0 INPUTE control
1 Raised button
2 Recessed button
4 Checked checkbox
8 Unchecked check box
Example
The following example shows how to use SENDMSG() Function 83 to set a default cell style of 2 (recessed button). This style is
overridden on the TITLE field by setting the STYLE user attribute to 0 in the grid template DATAREC_DESC$:
print (sysgui)'window'(0,20,390,120,"",$00000082$,$ff$)
datarec_desc$="cdnumber:c(6*=10):SHOW=1 LABEL=Number:,"+
: "title:c(50*=10):SHOW=1 LENGTH=50 LABEL=Title STYLE=0:"
sel_chan=unt; select (sel_chan)datarec$ from "datagrid.dat"
tf$=sendmsg(sysgui,100,83,2,$$)
tf$=sendmsg(sysgui,100,80,sel_chan,datarec_desc$)
escape
275
Set Default Alignment - GRID SENDMSG() Function 84
Syntax
NULL$=SENDMSG(sysgui,id,84,alignment,$$)
Description
This function sets the default text alignment for cells in a grid. The system default is to center text in cells.
id Grid control ID.
alignment Default text alignment.
$$ Always null.
grid to a data channel with Set Channel and Template - Grid SENDMSG() Function 80.Set Channel and Template - SENDMSG()
Function 80.The alignment for each column can be changed by using the ALIGN attribute with SENDMSG() Function 80.
The alignment parameter values are identical to the values used in the alignment field of the grid information block:
alignment Value Description

0 Left
1 Right
2 Center
Seek Last Record - GRID SENDMSG() Function 85

Syntax
Description
This function instructs a data-aware grid control to get the last record in the data channel and display it. While the last record is
being sought, a dialog allows the user to cancel the operation. There are three possible return values: $01$ indicates success;
$FF$ indicates the user canceled the operation; $01$ indicates the function encountered an error. An !ERROR 17 is generated if
this function is attempted on a heading grid.
id Grid control ID.
0 Always 0.
$$ Always null.
See also Set Last Record Dialog - Grid SENDMSG() Function 86.
276
Set Last Record Dialog - GRID SENDMSG() Function 86
Syntax
TF$=SENDMSG(sysgui,id,86,0,string)
Description
This function instructs a data-aware grid control to seek to the last record in the data channel and display it. During this operation,
a dialog box allows the user to cancel. Use SENDMSG() Function 86 to change the text that displays in this dialog. The passed
string is made up of the window title, the message, and the text on the cancel button concatenated into one string and terminated
with nulls ($00$). The default message is "Seeking last record. Please wait.". The default button text is "Cancel", and the dialog
title is blank by default.
failure.
id Grid control ID.
0 Always 0.
string Concatenated string that contains the text for the caption, dialog message, and Cancel button
according to the following:
caption$+$00$+message$+$00$+cancel$+$00$
Set Multiple Rows - GRID SENDMSG() Function 87

Syntax
TF$=SENDMSG(sysgui,id,87,starting_row,cell_contents$)
Description
This function sets the values in one or more contiguous cells with one command.
id Grid control ID.
starting_row Starting row number (or column number if working with a column header).
cell_contents$ Linefeed-separated strings with values to place in grid.
This function is supported only in VPro5 Rev 2.11 or later. Attempting to send this message to a grid control in an earlier version of
VPro5 will generate an !ERROR=17 tcb(10)=3. This function is similar to Function 21 (Set Multiple Cells) but does not require that
the cell pointer be moved to the starting cell. The starting_row parameter specifies the starting row number (zero based) or column
number if sending to a column header grid. With the exception of column header grids, the starting column is always zero. The
cell_contents$ parameter contains one or more strings delimited by linefeeds ($0A$). When the function executes, the first value
is placed in the first column of the starting row. Then the second value is placed in the next cell to the right. If the number of strings
in cell_contents$ is greater than the number of columns in the grid, values will be set in the entire current row, then the next row or
rows until last row is filled or all strings are used. Extra strings are ignored. If starting_row specifies a row or column that does not
exist, VPro5 generates an !ERROR=17 tcb(10)=4.
The return value is a four-byte string that indicates the number of cells changed. The default style, alignment, and colors which
can be changed with functions 55, 56, 83, and 84 are used. If any nondefault display attributes had been set in a cell with Draw
Cell - SENDMSG() Function 54, those attributes are reset to the defaults by this function.
Example
The following example creates a grid with a column header, three rows, and two columns and fills in the column header grid:
print (sysgui)'window'(10,50,380,90,"Grid Example",$$)
277
result$=sendmsg(sysgui,101,87,0,"First"+$0A$+"Second")
escape
Status Bar SENDMSG() Functions
Set Text - Status Bar SENDMSG() Function 20

Syntax
TF$=SENDMSG(sysgui,id,20,int,string$)
Description
This function sets the status bar text. The returned string indicates the success or failure of the operation: $01$ indicates success,
while $00$ indicates failure.
sysgui Valid SYSGUI channel.
id Object ID.
int Segment ID plus the attributes for the text display of the segment. The low order byte of int is the
index of the segment the text is being set for.
string$ Text string to be displayed in the segment.
Example
The following sets the second displayed segment with a pop out border in centered text:
TF$=SENDMSG(sysgui,id,20,dec($0201$),$09$+"Second Segment")
Get Text - Status Bar SENDMSG() Function 21

Syntax
SBTEXT$=SENDMSG(sysgui,id,21,segment_index,$$)
Description
This function returns the text of a specified status bar segment.
id Object ID.
segment_index Index of segment to retrieve the text from. If this value is greater than the number of segments, an
invalid parameter error will be generated.
$$ Always null.
Returned String Template

dispattr:U(2),text:C(1*)
Field Description
dispattr Text style
text Actual text to be displayed.
See the descriptions above for "No Border", "Pop Out", and "Right to Left" for the specific values possible in this field.
278
Get Text Length - Status Bar SENDMSG() Function 22
Syntax
SBTEXT$=SENDMSG(sysgui,id,22,segment_index,$$)
Description
This function returns a templated string that contains a specified status bar segment's text style and length.
id Object ID.
segment_index Index of segment to retrieve the text from. If this value is greater than the number of segments, an
$$ Always null.
Returned String Template

dispattr:U(2),len:U(2)
Field Description
dispattr Text style
len Text length
See the descriptions above for "No Border", "Pop Out", and "Right to Left" for the specific values possible in this field.
Get Rectangle - Status Bar SENDMSG() Function 23

Syntax
RECT$=SENDMSG(sysgui,id,23,segment_index,$$)
Description
This function returns a templated string that contains the bounding rectangle within client coordinates of the status bar.
id Object ID.
segment_index Index of segment to retrieve the length from. If this value is greater than the number of segments, an
$$ Always null.
The following describes the format of the RECT$ string:
left:u(2), top:u(2), width:u(2), height:u(2)
The string returns the bounding rectangle within client coordinates of the status bar, not its parent window.
Get Borders - Status Bar SENDMSG() Function 24

Syntax
BORDERS$=SENDMSG(sysgui,id,24,int,$$)
Description
This function returns a three-byte formatted string that contains the borders of the segments within the status bar.
279
id Object ID.
int Always zero.
$$ Always null.
Returned String Format

Byte Description
1 Width of the vertical border.
2 Width of the horizontal border.
3 Width of the inter-segment border.
Set Minimum Height - Status Bar SENDMSG() Function 25

Syntax
NULL$=SENDMSG(sysgui,id,25,int,$$)
Description
This function sets the minimum height of the status bar and returns a null string.
id Object ID.
int Minimum status bar height, in pixels.
$$ Always null.
Normally, the status bar height is determined by the font selected into the control. However, specifying a minimum height can
achieve a better appearance when the font size is small.
Get Parts - Status Bar SENDMSG() Function 26

Syntax
PARTS$=SENDMSG(sysgui,id,26,int,string$)
Description
This function has a dual purpose.
• If string$ is null, the int value is ignored and the returned string parts$ is a single byte indicating the number of segments within
the status bar control.
• If the string$ is not null, the int value must specify the number of segments for the right edge location. If int is greater than the
number of segments in the status bar, only the right edge location for the number of segments is returned.
id Object ID.
int Number of segments for which to set the right edge location. If int is greater than the number of
segments in the status bar, only the right edge location for the number of segments is returned.
string$ • If null, the int value is ignored and the returned string is a single byte indicating the number of
segments within the status bar control.
280
• If not null, the int value is used to indicate the right edge of the segments. The returned string is a
formatted string consisting of a series of two byte values specifying the right edge location of each
segment. A segment which extends to the end of the status bar control will return a $FFFF$ for
the right edge.
Example
For a status bar with two segments, the following will return a four-byte string:
parts$=SENDMSG(sysgui,id,26,255,$00$)
The dec(parts$(1,2)) is the right edge of the first segment, and dec(parts$(3,2)) is the right edge of the second segment.
Set Parts - Status Bar SENDMSG() Function 27

Syntax
TF$=SENDMSG(sysgui,id,27,int,string$)
Description
This function sets the right edge of the segments specified in the string$ string. Use this function to set the number of segments in
the status bar.
id Object ID.
int Always 0
string$ Formatted string, as returned from Get Parts - Status Bar SENDMSG() Function 26. Each pair of
bytes represents the location of the right edge of the corresponding segment within the status bar
control. A segment with a right edge value of $FFFF$ will set the right edge to edge of the status
window.
The returned string indicates the success or failure of the operation: $01$ indicates success, while $00$ indicates failure.
INPUTE SENDMSG() Functions
Get Title - INPUTE SENDMSG() Function 20

Syntax
TITLE$=SENDMSG(sysgui,id,20,0,$$)
Description
This function returns the INPUTE control title text, minus the mask characters.
id Object ID.
0 Always zero.
string$ Always null.
Set Title - INPUTE SENDMSG() Function 21

Syntax
281
Description
This function sets the INPUTE control title text.
id Object ID.
0 Always zero.
title$ INPUTE control title text.
Get Mask - INPUTE SENDMSG() Function 22

Syntax
MASK$=SENDMSG(sysgui,id,22,0,$$)
Description
This function returns the INPUTE control's mask. If the control was created with a length specified instead of a mask, the return
value will be a string of 256 “X characters.
id Object ID.
0 Always zero.
$$ Always null.
Set Mask - INPUTE SENDMSG() Function 23

Syntax
TF$=SENDMSG(sysgui,id,23,0,mask$)
Description
This function sets the INPUTE control's mask.
id Object ID.
0 Always zero.
mask$ INPUTE control mask.
Get Position - INPUTE SENDMSG() Function 24

Syntax
POSITION$=SENDMSG(sysgui,id,24,0,$$)
Description
This function returns the INPUTE control's caret position.
282
id Object ID.
0 Always zero.
$$ Always null.
The caret position is relative to the returned title string and does not include mask character positions. The first and last positions
are to the left of the first character and right of the last character that Get Title - INPUTE SENDMSG() Function 20 returns,
respectively. Use the returned string with the DEC() function to obtain the caret position in decimal format.
Set Position - INPUTE SENDMSG() Function 25

Syntax
TF$=SENDMSG(sysgui,id,25,position,$$)
Description
This function sets the INPUTE control's caret position.
id Object ID.
position Caret position value. The caret position is relative to the returned title string and does not include
mask character positions. The first and last positions are to the left of the first character and right of
the last character that Get Title - INPUTE SENDMSG() Function 20 returns, respectively.
$$ Always null.
Get Pad Character - INPUTE SENDMSG() Function 26

Syntax
CHARACTER$=SENDMSG(sysgui,id,26,0,$$)
Description
This function returns a one-byte string that contains the INPUTE control's pad character.
id Object ID.
0 Always zero.
$$ Always null.
Set Pad Character - INPUTE SENDMSG() Function 27

Syntax
TF$=SENDMSG(sysgui,id,27,character,$$)
Description
This function sets the INPUTE control's pad character.
id Object ID.
283
character INPUTE control pad character.
$$ Always null.
Get Restore String - INPUTE SENDMSG() Function 28

Syntax
RESTORE$=SENDMSG(sysgui,id,28,0,$$)
Description
This function returns the INPUTE control's restore string. The returned string contains the mask.
id Object ID.
0 Always zero.
$$ Always null.
Set Restore String - INPUTE SENDMSG() Function 29

Syntax
TF$=SENDMSG(sysgui,id,29,0,restore$)
Description
This function sets the INPUTE control's restore string.
id Object ID.
0 Always zero.
restore$ Restore string.
Set Left Margin - INPUTE SENDMSG() Function 30

Syntax
TF$=SENDMSG(sysgui,id,30,margin,$$)
Description
This function sets the left margin of the INPUTE control's first character.
id Object ID.
margin Number of pixels in the margin. The default left margin is one pixel. The margin value can be used
to move the entire text, including the mask characters, to the left or right within the control.
$$ Always null.
284
Set Text Color - INPUTE SENDMSG() Function 31
Syntax
TF$=SENDMSG(sysgui,id,31,color,$$)
Description
This function sets the INPUTE control's text color.
id Object ID.
color Text color specified as DEC($00$+$RRGGBB$), where $RRGGBB$ defines the RGB value.
$$ Always null.
Set Background Color - INPUTE SENDMSG() Function 32

Syntax
Description
This function sets the INPUTE control's background color.
id Object ID.
color Background color specified as DEC($00$+$RRGGBB$), where $RRGGBB$ defines the RGB value.
$$ Always null.
Set !EDIT Value - INPUTE SENDMSG() Function 33

Syntax
TF$=SENDMSG(sysgui,id,33,0,value$)
Description
This function sets the INPUTE control's !EDIT string and may be necessary if a control exists. The !EDIT string can be changed
within the Visual PRO/5 program.
id Object ID.
0 Always zero.
value$ Edit string, having a maximum of 256 characters.
The !EDIT string is set at initialization but does not reflect changes that occur during the control's lifetime. The control is not
subject to the file system's device I/O and, therefore, does not recognize function key programming, although Keypress Notify
events inform the application when special keys are pressed.
The control does not recognize !EDIT string edit commands that are programmed into function keys for the SYSWINDOW device.
285
Set Length - INPUTE SENDMSG() Function 34
Syntax
TF$=SENDMSG(sysgui,id,34,length,$$)
Description
This function sets the length of the INPUTE string.
id Object ID.
length Length of the INPUTE string.
$$ Always null.
Get Error - INPUTE SENDMSG() Function 35

Syntax
ERR$=SENDMSG(sysgui,id,35,0,$$)
Description
This function returns the INPUTE control's last error.
id Object ID.
0 Always zero.
$$ Always null.
The returned string can be used with the DEC() function to determine the error.
Set Insert Mode - INPUTE SENDMSG() Function 36

Syntax
TEXT$=SENDMSG(sysgui,id,36,mode,$$)
Description
This function sets the INPUTE control's character entry mode. When the control is created, the insert mode is set by SETOPTS
byte 1, bit $20$.
id Object ID.
mode Character entry mode. A value of 1 places the control into insert mode, while a value of 0 places the
control into overtype mode.
$$ Always null.
286
Set !CTYPE Value - INPUTE SENDMSG() Function 37
Syntax
TF$=SENDMSG(sysgui,id,37,0,ctype$)
Description
This function sets the INPUTE control's !CTYPE string and may be necessary if a control exists. The !CTYPE string can be
changed within the Visual PRO/5 program.
id Object ID.
0 Always zero.
ctype$ Edit string, which must be exactly 768 bytes long.
The !CTYPE string is set at initialization but does not reflect changes that occur during the control's lifetime. The returned value
indicates the success or failure of the operation: $01$ indicates success, while $00$ indicates failure. The error can be requested
or returned with the Notify event.
INPUTN SENDMSG() Functions
Get Title - INPUTN SENDMSG() Function 20

Syntax
TITLE$=SENDMSG(sysgui,id,20,0,$$)
Description
This function returns the title text of the INPUTN control, minus the mask characters.
id Object ID.
0 Always zero.
$$ Always null.
Set Title - INPUTN SENDMSG() Function 21

Syntax
Description
This function sets the title text of the INPUTN control.
id Object ID.
0 Always zero.
title$ INPUTN control title text.
287
Get OMask - INPUTN SENDMSG() Function 22
Syntax
OMASK$=SENDMSG(sysgui,id,22,0,$$)
Description
This function returns the output mask of the INPUTN control.
id Object ID.
0 Always zero.
$$ Always null.
Set Output Mask - INPUTN SENDMSG() Function 23

Syntax
TF$=SENDMSG(sysgui,id,23,0,omask$)
Description
This function sets the output mask of the INPUTN control.
id Object ID.
0 Always zero.
omask$ INTPUTN control output mask.
Get Position - INPUTN SENDMSG() Function 24

Syntax
POSITION$=SENDMSG(sysgui,id,24,0,$$)
Description
This function sets the INPUTN control's caret position. The position parameter defines the value. The caret position is relative to
the returned title string and does not include mask character positions. The first and last positions are to the left of the first
character and right of the last character that Get Title - INPUTN SENDMSG() Function 20 returns, respectively. The returned
string can be used with the DEC() function to convert the caret's position to decimal format.
id Object ID.
0 Always zero.
$$ Always null.
288
Get Error - INPUTN SENDMSG() Function 25
Syntax
ERR$=SENDMSG(sysgui,id,25,0,$$)
Description
This function returns the last error generated by the INPUTN control. The returned string can be used with the DEC() function to
determine the error.
id Object ID.
0 Always zero.
$$ Always null.
Get Restore String - INPUTN SENDMSG() Function 26

Syntax
RESTORE$=SENDMSG(sysgui,id,26,0,$$)
Description
This function returns the output mask, which is the restore string of the INPUTN control.
id Object ID.
0 Always zero.
$$ Always null.
Set Left Margin - INPUTN SENDMSG() Function 27

Syntax
TF$=SENDMSG(sysgui,id,27,margin,$$)
Description
This function sets the left margin of the INPUTN control's first character.
id Object ID.
margin Number of pixels in the left margin, the default is one pixel. This value can be used to move the
entire text, including the mask characters, to the left or right within the control.
$$ Always null.
Set Text Color - INPUTN SENDMSG() Function 28

Syntax
289
Description
This function sets the text color of the INPUTN control.
id Object ID.
color Text color, specified as DEC($00$+$RRGGBB$), where $RRGGBB$ defines the RGB value.
$$ Always null.
Set Background Color - INPUTN SENDMSG() Function 29

Syntax
Description
This function sets the background color of the INPUTN control.
id Object ID.
color Background color, specified as DEC($00$+$RRGGBB$), where $RRGGBB$ defines the RGB
value.
$$ Always null.
Set Position - INPUTN SENDMSG() Function 30

Syntax
TF$=SENDMSG(sysgui,id,30,position,$$)
Description
This function gets the INPUTN control's caret position, which is relative to the returned title string and does not include mask
character positions.
id Object ID.
position Caret position. The first and last positions are to the left of the first character and right of the last
character that Get Title - INPUTN SENDMSG() Function 20 returns, respectively.
$$ Always null.
Set Restore String - INPUTN SENDMSG() Function 31

Syntax
TF$=SENDMSG(sysgui,id,31,0,restore$)
Description
This function sets the restore string of the INPUTN control.
290
id Object ID.
0 Always zero.
restore$ Restore string.
Set !EDIT Value - INPUTN SENDMSG() Function 32

Syntax
TF$=SENDMSG(sysgui,id,32,0,value$)
Description
This function sets the !EDIT string of the INPUTN control, which may be necessary if a control exists and users can change the
!EDIT string within Visual PRO/5.
id Object ID.
0 Always zero.
value$ Edit string, having a maximum of 256 characters.
Although the !EDIT string is set when the control is created, it does not reflect changes that occur during the control's lifetime. The
control is not subject to the file system's device I/O and does not recognize function key programming, although Keypress Notify
events inform the application when special keys are pressed. The control does not recognize !EDIT string edit commands that are
programmed into function keys for the SYSWINDOW device.
Set Insert Mode - INPUTN SENDMSG() Function 33

Syntax
TF$=SENDMSG(sysgui,id,33,mode,$$)
Description
This function sets the character entry mode of the INPUTN control.
id Object ID.
mode Character entry mode. A value of 1 places the control into insert mode, while a value of 0 places the
control into overtype mode.
$$ Always null.
When the control is created, the insert mode is set by SETOPTS byte 1, bit $20$.
TABCTRL SENDMSG() Functions
SENDMSG() Syntax Legend

The following describes the SENDMSG() syntax items that are unique to the tab control:
Item Description
color$ A three-byte binary string specifying a color, in $RRGGBB$ format, with the bytes providing, in order, the red, green,
and blue values.
291
count$ A two-byte binary string containing the number of tabs in a tab control. Print DEC($00$+COUNT$) to obtain the
value in decimal format.
ht$ A one-byte hit test return value. If the value is $00$, the position is not over a tab. If the value is $01$, the position is
over a tab, but not over its icon or text. If the value is $02$, the position is over a tab's icon. If the value is $03$, the
position is over a tab's text.
id$ A one-byte binary string containing the ID of a control or image list. Print ASC(ID$) to obtain the ID value.
idx$ A one-byte binary string returning an index value. Print ASC(IDX$) to obtain the index value.
null$ A null string.
pt$ A four-byte string representing a point in the control's coordinates. It is described using the following template:
x:i(2),y:i(2)
rect$ An eight-byte string describing a rectangle. It is described using the following template:
x:i(2),y:i(2),w:u(2),h:u(2)
rows$ A one-byte string returning the number of rows in a tab control. Print ASC(ROWS$) to obtain the actual value.
tabdes$ A string containing a description of a tab and uses the following template:
imageidx:i(2),id:i(2),text:c(1*=0)
The imageidx field contains the index of the displayed image list tab image (-1 indicates no image). The id field
contains the ID of a control or child window to be displayed when the tab is selected by the user (-1 indicates that no
control or child window should be displayed automatically). The text field contains the text displayed on the tab.
tabidx% An integer value used to identify a particular tab or tab location within the tab control.
tf$ A one-byte string value containing $01$ if the operation succeeded, or $00$ if the operation failed.
xy$ A four-byte string containing a position. It is described using the following template:
x:i(2),y:i(2)
wh$ Four-byte string describing the width and height of the tab. It is described using the following template:
w:i(2),h:i(2)
Get/Set Display Rectangle - TABCTRL SENDMSG() Function 20

Depending on the syntax used, this function returns or sets the display rectangle of the tab control
Get Display Rectangle Syntax

RECT$=SENDMSG(sysgui,id,20,0,$$)
id Object ID.
0 Always zero.
$$ Always null.
The returned eight-byte string describes the display rectangle according to the following template:
x:i(2),y:i(2),w:u(2),h:u(2)
Set Display Rectangle Syntax

NULL$=SENDMSG(sysgui,id,20,1,rect$)
id Object ID.
292
1 Nonzero.
rect$ Eight-byte string that describes the display rectangle according to the following template:
x:i(2),y:i(2),w:u(2),h:u(2)
Get Bounding Rectangle - TABCTRL SENDMSG() Function 21

Syntax
RECT$=SENDMSG(sysgui,id,21,tabidx%,$$)
Description
This function returns the bounding rectangle of a tab on the control. A null string is returned if the function fails.
sysgui A valid SYSGUI channel.
id Object ID.
tabidx% An integer value used to identify a particular tab or tab location within the tab control.
$$ Always null.
Get Number of Tab Rows - TABCTRL SENDMSG() Function 22

Syntax
Description
This function returns the number of tab rows in the control.
id Object ID.
0 Always zero.
$$ Always null.
Set Tab Width and Height - TABCTRL SENDMSG() Function 23

Syntax
WH$=SENDMSG(sysgui,id,23,0,wh$)
Description
This function sets the width and height of each tab on a fixed-width tab control.
id Object ID.
0 Always zero.
wh$ Four-byte string describing the new width and height of the tab according to the following
template:
293
w:i(2),h:i(2)
The first time this function is used, the return value is not meaningful. Subsequent uses return the old width and height of the tabs
in a four-byte string, which may be described with the following template:
w:i(2),h:i(2)
Set Tab Icon/Label Padding - TABCTRL SENDMSG() Function 24

Syntax
NULL$=SENDMSG(sysgui,id,24,0,xy$)
Description
This function sets the amount of padding space around the icon and label of each tab.
id Object ID.
0 Always zero.
xy$ Pad spacing as described using the following template:
x:i(2),y:i(2)
The x field contains the horizontal spacing and the y field contains the vertical spacing.
Remove All Tabs - TABCTRL SENDMSG() Function 25

Syntax
Description
This function removes all tabs from the control.
id Object ID.
0 Always zero.
$$ Always null.
Remove a Tab - TABCTRL SENDMSG() Function 26

Syntax
TF$=SENDMSG(sysgui,id,26,tabidx%,$$)
Description
This function removes a tab from the control. The programmer is responsible for removing controls associated with tabs.
id Object ID.
tabidx% Tab to be removed.
294
$$ Always null.
Get Tab Information - TABCTRL SENDMSG() Function 27

Syntax
TABDES$=SENDMSG(sysgui,id,27,tabidx%,$$)
Description
This function returns tab information.
id Object ID.
tabidx% Zero-based tab index.
$$ Always null.
If the operation fails, a null string is returned.
Get Tab Index - TABCTRL SENDMSG() Function 29

Syntax
IDX$=SENDMSG(sysgui,id,29,0,$$)
Description
This function returns the index of the tab that currently has focus.
id Object ID.
0 Always zero.
$$ Always null.
Get Tab Image List ID - TABCTRL SENDMSG() Function 30

Syntax
ID$=SENDMSG(sysgui,id,30,0,$$)
Description
This function returns the ID of the image list used by the control.
id Object ID.
0 Always zero.
$$ Always null.
295
Get Tab Count - TABCTRL SENDMSG() Function 31
Syntax
COUNT$=SENDMSG(sysgui,id,31,0,$$)
Description
This function returns the number of tabs in the control.
id Object ID.
0 Always zero.
$$ Always null.
Perform Point Hit Test - TABCTRL SENDMSG() Function 32

Syntax
HT$=SENDMSG(sysgui,id,32,0,pt$)
Description
This function performs a hit test of a given point. The point value is specified in pixels.
id Object ID.
0 Always zero.
pt$ Four-byte string representing the hit point, as described using the following template:
x:i(2),y:i(2)
Insert Tab - TABCTRL SENDMSG() Function 33

Syntax
IDX$=SENDMSG(sysgui,id,33,tabidx%,tabdes$)
Description
This function inserts a tab into the control. The return value contains the null string if the operation fails. If the operation succeeds,
the return value will be the value passed in tabidx%.
id Object ID.
tabidx% Location in which to insert the tab.
tabdes$ String containing a description of a tab and uses the following template:
The imageidx field contains the index of the displayed image list tab image (-1 indicates no
image). The id field contains the ID of a control or child window to be displayed when the tab is
selected by the user (-1 indicates that no control or child window should be displayed
automatically). The text field contains the text displayed on the tab.
296
Select Tab - TABCTRL SENDMSG() Function 34
Syntax
IDX$=SENDMSG(sysgui,id,34,tabidx%,$$)
Description
This function selects a tab in the control. If the operation succeeds, it returns the zero-based tab index. Otherwise, it returns a null
string.
id Object ID.
0 Identifies the tab to be selected.
$$ Always null.
Set Tab Image List ID - TABCTRL SENDMSG() Function 35

Syntax
ID$=SENDMSG(sysgui,id,35,imagelist_id,$$)
Description
This function assigns an image list to a control. The return value contains the ID of the image list previously placed in the control
or the null value if no image list was previously selected.
id Object ID.
imagelist_id Image list ID.
$$ Always null.
Set Tab Attributes - TABCTRL SENDMSG() Function 36

Syntax
TF$=SENDMSG(sysgui,id,36,tabidx%,tabdes$)
Description
This function sets tab attributes.
id Object ID.
tabidx% Identifies the tab for which to set attributes.
tabdes$ String containing a description of a tab and uses the following template:
The imageidx field contains the index of the displayed image list tab image (-1 indicates no
image). The id field contains the ID of a control or child window to be displayed when the tab is
selected by the user (-1 indicates that no control or child window should be displayed
automatically). The text field contains the text displayed on the tab.
297
Ignore/Process Selection Change Notice - TABCTRL SENDMSG() Function 37
Depending on the syntax used, this function causes a selection change notice (which indicates that a tab item is about to be
deselected) to be ignored or processed. By default, selection change notices are processed.
Ignore Selection Change Notice Syntax

TF$=SENDMSG(sysgui,id,37,tabidx%,$00$)
Description
This function causes a selection change notice received by a selected tab item (identified by tabidx%) to be ignored.
id Object ID.
tabidx% Tab item for which to ignore the selection change notice.
$00$ Always $00$
Process Selection Change Notice Syntax

TF$=SENDMSG(sysgui,id,37,tabidx%,$01$)
Description
This function causes a selection change notice received by a selected tab item (identified by tabidx%) to be processed.
id Object ID.
tabidx% Tab item for which to process the selection change notice.
$01$ Always $01$
Get Current Tab - TABCTRL SENDMSG() Function 38

Syntax
ID$=SENDMSG(sysgui,id,38,0,$$)
Description
This function retrieves a two-byte hexadecimal representation of the index of the currently selected tab item. Note that tab item
numbering is zero-based.
id Object ID.
0 Always 0.
$$ Always null.
Set Tab Index Focus - TABCTRL SENDMSG() 39

Syntax
NULL$=SENDMSG(sysgui,id,39,tabidx%,$$)
298
Description
This function sets the tab focus to the zero-based tab index. If the tab has CTRLTAB_FLAG_BUTTONS set and does not have
CTRLTAB_FLAG_TABS set, the currently selected tab can be different than the tab with the focus. Otherwise, setting focus to a
tab will select that tab.
id Object ID.
tabidx% Tab index.
$$ Always null.
Index
.
.gbf File [Program] Section .......................................................................................................... 106

_
_label Utility - Convert Line Numbers to Line Labels................................................................... 108

A
Accelerator and Combination Key Values ................................................................................... 128

Aligning Child Windows in ResBuilder ......................................................................................... 177
ASCII Resource File Compiling with ResCompiler ...................................................................... 190
ASCII Resource Files Created In ResCompiler........................................................................... 190
Asterisk Input Mask Property Setting........................................................................................... 234
Automanagement of Tabs, Preventing Property Setting ............................................................. 232
B
Background Color Property Setting ............................................................................................. 223

Beep for Invalid Data Entry Property Setting ............................................................................... 223
Border Around Dialog Property Setting ....................................................................................... 225
Border for Custom Edit Control Property Setting......................................................................... 223
Borderless Child Window Property Setting.................................................................................. 223
Building BBX Programs with GUIBuilder ....................................................................................... 83
Button Controls ............................................................................................................................ 130
Button Controls Defined in ResCompiler ..................................................................................... 202
C
Check Box Controls ..................................................................................................................... 130
Check Box Controls Defined in ResCompiler .............................................................................. 203
299
Check/Uncheck Event.................................................................................................................. 144
Child Window Properties - Setting Defaults in ResBuilder .......................................................... 179
Child Windows ............................................................................................................................. 131
Child Windows Defined in ResCompiler ...................................................................................... 200
Clear Event Queue Buffer - FLUSH Mnemonic ........................................................................... 143
Client Edge Property Setting........................................................................................................ 224
Close Box Event........................................................................................................................... 144
Close Box, Included with Window Property Setting..................................................................... 224
Code Blocks
Checking for Errors in GUIBuilder ........................................................................................... 81
COLCHANGE Grid Notify Event .................................................................................................. 155
COLUMNSIZED Grid Notify Event............................................................................................... 154
Commas, Borderless Child Window Property Setting ................................................................. 224
CONFIG.TPM File in DDBuilder .................................................................................................... 17
Configuration File
Creating in Configurator ............................................................................................................ 1
Opening Existing in Configurator............................................................................................... 1
Printing in Configurator.............................................................................................................. 2
Control Coordinates ..................................................................................................................... 127
Control Focus Gained/Lost Event ................................................................................................ 145
Control Font Property Setting ...................................................................................................... 227
Control Properties - Setting Defaults in ResBuilder..................................................................... 184
Convert Line Numbers to Line Labels - _label Utility................................................................... 108
Creating New Resource Files in ResBuilder................................................................................ 174
CTRL() Function - Get GUI Control Data
Use with Button Controls ....................................................................................................... 130
Use with Check Box Controls ................................................................................................ 130
Use with Child Windows ........................................................................................................ 131
Use with Custom Edit Controls.............................................................................................. 131
Use with Edit Controls ........................................................................................................... 132
Use with Group Box Controls ................................................................................................ 133
Use with Horizontal Scroll Bar Controls ................................................................................ 133
Use with INPUTE Controls .................................................................................................... 134
Use with INPUTN Controls .................................................................................................... 134
Use with List Box Controls .................................................................................................... 135
Use with List Button Controls ................................................................................................ 136
Use with List Edit Controls .................................................................................................... 136
Use with Radio Button Controls ............................................................................................ 140
Use with Status Bar Controls ................................................................................................ 140
Use with Tab Controls ........................................................................................................... 141
Use with Tool Button Controls............................................................................................... 141
Current Units Property Setting ..................................................................................................... 225
Cursor Position, Initial Property Setting ....................................................................................... 229
Custom Color Palette Property Setting........................................................................................ 225
300
Custom Edit Controls ................................................................................................................... 131
Custom Edit Controls Defined in ResCompiler............................................................................ 204
D
Data Dictionary
Adding Elements ..................................................................................................................... 22
Copying Elements ................................................................................................................... 22
Creating New........................................................................................................................... 18
Deleting Elements ................................................................................................................... 23
Inserting Columns.................................................................................................................... 22
Making Data Files.................................................................................................................... 18
Opening Existing ..................................................................................................................... 19
Pasting Elements..................................................................................................................... 22
Renaming Elements ................................................................................................................ 23
Saving...................................................................................................................................... 20
Data Dictionary (simple)
Column Attributes .................................................................................................................... 25
Indices ..................................................................................................................................... 26
Table Attributes ....................................................................................................................... 24
Data Source
Closing..................................................................................................................................... 21
Creating ................................................................................................................................... 18
Opening ............................................................................................................................. 18, 19
DCLICKED Grid Notify Event....................................................................................................... 155
DDBuilder
Moving to from GUIBuilder ...................................................................................................... 86
Defining Control Properties in ResBuilder ................................................................................... 183
Defining Default Values For Forms and Child Windows in ResBuilder ....................................... 179
Defining Form and Child Window Properties in ResBuilder ........................................................ 177
Deleting Controls in ResBuilder ................................................................................................... 186
Deselect All Cells - GRID SENDMSG() Function 32 ................................................................... 250
Dialog Box
Capabilities vs. Window......................................................................................................... 126
Dialog Window Property Setting .................................................................................................. 225
Distributing Controls in ResBuilder .............................................................................................. 182
Docking Position of Child Windows Property Setting .................................................................. 226
Drag Start - GRID SENDMSG() Function 25............................................................................... 245
DRAGDROP Grid Notify Event .................................................................................................... 156
Draw Cell - GRID SENDMSG() Function 54................................................................................ 259
Drawing Coordinates ................................................................................................................... 127
DSKSYN Settings in Configurator.................................................................................................... 2
E
Edit Control Modify Event ............................................................................................................ 145
301
Edit Controls................................................................................................................................. 132
Notify Events ......................................................................................................................... 149
Edit Controls Defined in ResCompiler ......................................................................................... 204
EDITCHANGE Grid Notify Event ................................................................................................. 156
EDITKEY Grid Notify Event ......................................................................................................... 157
EDITKILL Grid Notify Event ......................................................................................................... 157
EDITSET Grid Notify Event.......................................................................................................... 158
EDITSTART Grid Notify Event..................................................................................................... 166
End Edit - GRID SENDMSG() Function 26.................................................................................. 246
End of Job Code
Defining in GUIBuilder ............................................................................................................. 80
End Users
Preparing GUIBuilder Programs for ........................................................................................ 85
ENTER Grid Notify Event............................................................................................................. 158
ERROR Grid Notify Event............................................................................................................ 167
Error Messages in ResCompiler .................................................................................................. 221
Errors
Checking GUIBuilder Code Blocks For ................................................................................... 81
Event Handler Code Blocks
Event Mask Property Setting ....................................................................................................... 226
Events
SYSGUI ................................................................................................................................. 143
Exiting ResBuilder........................................................................................................................ 176
External Code
Importing into GUIBuilder ........................................................................................................ 81
External Editor
Using in GUIBuilder ................................................................................................................. 82
F
File Format GUIBuilder - .gbf ....................................................................................................... 106

Files
Opening Existing GUIBuilder................................................................................................... 78
Printing GUIBuilder.................................................................................................................. 78
Saving GUIBuilder ................................................................................................................... 78
Fit Columns to Window - GRID SENDMSG() Function 29 .......................................................... 247
Fixed Tab Width Property Setting ................................................................................................ 226
Font, Default Window Property Setting........................................................................................ 225
Force Icons to Left Margin Property Setting ................................................................................ 227
Foreground Color Property Setting .............................................................................................. 227
Forms and Child Windows-Creating in ResBuilder...................................................................... 176
302
G
gb.ini File...................................................................................................................................... 104

Get Average Character Width - GRID SENDMSG() Function 37................................................ 252
Get Borders - Status Bar SENDMSG() Function 24 .................................................................... 279
Get Bounding Rectangle - TABCTRL SENDMSG() Function 21 ................................................ 293
Get Column Width - GRID SENDMSG() Function 38.................................................................. 252
Get Current Tab - TABCTRL SENDMSG() Function 38.............................................................. 298
Get Display Rectangle - TABCTRL SENDMSG() Function 20.................................................... 292
Get Edit Text - GRID SENDMSG() Function 34 .......................................................................... 251
Get Error - INPUTE SENDMSG() Function 35 ............................................................................ 286
Get Error - INPUTN SENDMSG() Function 25 ............................................................................ 289
Get Font - GRID SENDMSG() Function 39 ................................................................................. 253
Get Grid Information Block - GRID SENDMSG() Function 20..................................................... 241
Get Last Record - GRID SENDMSG() Function 85 ..................................................................... 276
Get Mask - INPUTE SENDMSG() Function 22............................................................................ 282
Get Number of Columns - GRID SENDMSG() Function 40 ........................................................ 253
Get Number of Rows - GRID SENDMSG() Function 41.............................................................. 253
Get Number of Tab Rows - TABCTRL SENDMSG() Function 22............................................... 293
Get Number of Visible Rows - GRID SENDMSG() Function 43.................................................. 254
Get OMask - INPUTN SENDMSG() Function 22......................................................................... 288
Get Pad Character - INPUTE SENDMSG() Function 26 ............................................................. 283
Get Parts - Status Bar SENDMSG() Function 26 ........................................................................ 280
Get Position - INPUTE SENDMSG() Function 24 ....................................................................... 282
Get Position - INPUTN SENDMSG() Function 24 ....................................................................... 288
Get Rectangle - Status Bar SENDMSG() Function 23 ................................................................ 279
Get Restore String - INPUTE SENDMSG() Function 28 ............................................................. 284
Get Restore String - INPUTN SENDMSG() Function 26 ............................................................. 289
Get Row Height - GRID SENDMSG() Function 42...................................................................... 254
Get Selected Column - GRID SENDMSG() Function 44 ............................................................. 254
Get Selected Row - GRID SENDMSG() Function 45 .................................................................. 255
Get String Width - GRID SENDMSG() Function 73..................................................................... 268
Get Tab Count - TABCTRL SENDMSG() Function 31 ................................................................ 296
Get Tab Image List ID - TABCTRL SENDMSG() Function 30 .................................................... 295
Get Tab Index - TABCTRL SENDMSG() Function 29 ................................................................. 295
Get Tab Information - TABCTRL SENDMSG() Function 27........................................................ 295
Get Text - Status Bar SENDMSG() Function 21.......................................................................... 278
303
Get Text Length - Status Bar SENDMSG() Function 22.............................................................. 279
Get Title - INPUTE SENDMSG() Function 20 ............................................................................. 281
Get Title - INPUTN SENDMSG() Function 20 ............................................................................. 287
Get Top Row - GRID SENDMSG() Function 46 .......................................................................... 255
Getting Started in GUIBuilder (Mini-Tutorial) ............................................................................... 108
GLOBAL Settings in Configurator .................................................................................................... 3
Goto Column - GRID SENDMSG() Function 47 .......................................................................... 255
Goto Row - GRID SENDMSG() Function 48 ............................................................................... 256
Gravity Property Setting............................................................................................................... 227
Grid Column Lines, Vertical Property Setting .............................................................................. 238
Grid Column Resizing Property Setting ....................................................................................... 237
Grid Columns, Initial Number Property Setting............................................................................ 224
Grid Columns, Set Maximum Property Setting ............................................................................ 231
Grid Control
Data-Aware Grid Tutorial......................................................................................................... 63
Standard And Data-Aware Grids............................................................................................. 49
Standard Grid Tutorial 2
User-Modifiable Grid............................................................................................................... 60
Grid Controls
Notify Events ......................................................................................................................... 154
Grid Controls Defined in ResCompiler......................................................................................... 205
Grid Horizontal Lines Property Setting ........................................................................................ 228
Grid Row Spacing Property Setting ............................................................................................. 229
Grid Rows Property Setting ......................................................................................................... 235
Grid Toggle Button Property Setting ............................................................................................ 237
Group Box Controls ..................................................................................................................... 133
Group Box Controls Defined in ResCompiler .............................................................................. 206
Group Controls Property Setting.................................................................................................. 227
Grouping and Ungrouping Controls in ResBuilder....................................................................... 183
GUIBuilder Functions
Build and Tokenize Program using .gbf Data.......................................................................... 94
Copy Control Value from Screen to Template Record............................................................ 88
Delete .gbf String Data or Chunk of Code............................................................................... 92
Determine Event Visibility........................................................................................................ 99
Generate Framework .gbf String ............................................................................................. 99
Get All Child Windows for a Given Context........................................................................... 101
Get All Child Windows for a Given Top Level Window ......................................................... 102
Get All Controls for a Given Context ..................................................................................... 101
Get All Controls for a Given Form ......................................................................................... 103
Get All Forms for a Given Resource ..................................................................................... 102
Get All Forms for a Given SYSGUI Channel......................................................................... 100
Get Control Description for a Given Control Type................................................................... 99
Get Event Codes for a Given Control Type............................................................................. 99
304
Get Event Description for a Given Event Code....................................................................... 98
Get Event Label for a Given Event Code ................................................................................ 99
Get String Template Given Window ID ................................................................................... 88
Get Text File into a .gbf String................................................................................................. 93
Reading and Updating the Screen .......................................................................................... 86
Retrieve .gbf String Data or Chunks of Code.......................................................................... 90
Retrieving Window Information ............................................................................................... 89
Setting Screen Focus .............................................................................................................. 89
Update Screen Control Values from Template Record........................................................... 89
Validate a .gbf String ............................................................................................................... 93
GUIBuilder GB.INI.File................................................................................................................. 104
GUIBuilder Interface ...................................................................................................................... 76
H
Highlight Text Property Setting .................................................................................................... 227

HITBOTTOM Grid Notify Event.................................................................................................... 159
HITTOP Grid Notify Event............................................................................................................ 159
Horizontal Scroll Bar Controls...................................................................................................... 133
Horizontal Tab Padding Property Setting .................................................................................... 228
Hot Keys....................................................................................................................................... 128
I
Icon File Property Setting............................................................................................................. 228

Ignore/Process Selection Change Notice - TABCTRL SENDMSG() Function 37....................... 298
Image Elements Defined in ResCompiler.................................................................................... 207
Image List, Definition Property Setting ........................................................................................ 228
Image Lists
Creating In ResBuilder .......................................................................................................... 188
Imagelist Sharing Property Setting .............................................................................................. 236
Images ......................................................................................................................................... 134
Initial Contents Property Setting .................................................................................................. 229
Initialization Code
Initialization File
GUIBuilder ............................................................................................................. 104, 105, 106
Initially Checked Property Setting ................................................................................................ 224
Initially Disabled Property Setting ................................................................................................ 225
Initially Invisible Property Setting ................................................................................................. 230
Initially Minimize Window Property Setting .................................................................................. 231
Initially Minimize Windows Property Setting ................................................................................ 232
Input Mask for INPUTE Property Setting ..................................................................................... 231
Input Mask for INPUTN Property Setting..................................................................................... 229
305
INPUTE Controls.......................................................................................................................... 134
Notify Events ......................................................................................................................... 150
INPUTE Controls Defined in ResCompiler .................................................................................. 207
INPUTN Controls ......................................................................................................................... 134
Notify Events ......................................................................................................................... 150
INPUTN Controls Defined in ResCompiler .................................................................................. 208
Insert Tab - TABCTRL SENDMSG() Function 33........................................................................ 296
Interface
GUIBuilder ............................................................................................................................... 76
Interface Description ...................................................................................................................... 18
J
Justification of Text Property Setting ........................................................................................... 230

K
Keyboard Focus, Keyboard Navigation, and The Default Button ................................................ 127
KEYBOARD Grid Notify Event..................................................................................................... 160
Keyboard Navigation Property Setting......................................................................................... 230
Keypress Event ............................................................................................................................ 145
KILLFOCUS Grid Notify Event..................................................................................................... 160
L
Labels to Left Edge of Tabs Property Setting .............................................................................. 227

LCLICKED Grid Notify Event ....................................................................................................... 160
LCLICKED2 Grid Notify Event ..................................................................................................... 161
LEFTCOLCHANGE Grid Notify Event ......................................................................................... 162
Line Element ................................................................................................................................ 209
List Box Controls .................................................................................................................. 135, 209
List Boxes
Description of........................................................................................................................... 76
List Button Controls.............................................................................................................. 136, 210
Notify Events ......................................................................................................................... 151
List Edit Controls .......................................................................................................................... 136
Notify Events ......................................................................................................................... 151
List Edit Controls Defined in ResCompiler................................................................................... 211
List Item Click Event .................................................................................................................... 146
Longcue Text Property Setting .................................................................................................... 230
M
Making Data Files .......................................................................................................................... 19
Managed Grid Control as Column Heading Property Setting...................................................... 224
306
Managed Grid Control as Row Heading Property Setting ........................................................... 235
Maximum Length of Input String Property Setting ....................................................................... 231
Menu Bar-Creating in ResBuilder ................................................................................................ 186
Menu Item, Checkable Property Setting ...................................................................................... 223
Menu Selection Event .................................................................................................................. 147
Menu Separation Lines Property Setting ..................................................................................... 235
Menus .......................................................................................................................................... 137
Menus-Adding Menu Items in ResBuilder ................................................................................... 187
Menus-Adding to the Menu Bar in ResBuilder............................................................................. 187
Menus-Attaching to Forms in ResBuilder .................................................................................... 187
Mini-Tutorial - GUIBuilder ............................................................................................................ 108
Modifying Tab Order of Controls in ResBuilder ........................................................................... 185
Mouse Button Down Event .......................................................................................................... 147
Mouse Button Up Event ............................................................................................................... 148
Mouse Double-Click Event........................................................................................................... 148
Mouse Move Event ...................................................................................................................... 149
MOUSECAPTURE Grid Notify Event .......................................................................................... 162
Moving Controls in ResBuilder..................................................................................................... 182
Multiple List Box Selections Property Setting .............................................................................. 232
N
Name of Windows/Controls Property Setting .............................................................................. 232
Notify Events ................................................................................................................................ 149
Notify Events for the Grid Control ........................................................................................ 154, 155
Novell-Specific Settings in Configurator ........................................................................................ 11
O
Opening Existing Files in GUIBuilder............................................................................................. 78

Opening Existing Resource Files in ResBuilder .......................................................................... 174
Option String Property Setting ..................................................................................................... 233
Output Mask for INPUTN Property Setting .................................................................................. 233
Overstrike Mode Property Setting................................................................................................ 233
P
Pad Character for INPUTE Property Setting ............................................................................... 233

Perform Data-Aware Function - GRID SENDMSG() Function 81 ............................................... 274
Perform Point Hit Test - TABCTRL SENDMSG() Function 32 .................................................... 296
Plotter Device Settings in Configurator ............................................................................................ 8
307
Predefined Constants in ResCompiler......................................................................................... 217
PREFIX Settings in Configurator ..................................................................................................... 3
Prepared Resources .................................................................................................................... 127
Preparing GUIBuilder Programs for End Users ............................................................................. 85
Preprocessor Commands in ResCompiler .................................................................................. 216
Previewing Resource Files in ResBuilder.................................................................................... 188
Printer Property Settings in Configurator ......................................................................................... 5
Printing GUIBuilder Files................................................................................................................ 78
Printing Resource Files in ResBuilder ......................................................................................... 188
Program Options
Setting...................................................................................................................................... 83
Programs
Building.................................................................................................................................... 83
Preparing for End Users .......................................................................................................... 85
Run Generated Program ....................................................................................................... 100
Running GUIBuilder................................................................................................................. 84
Viewing .................................................................................................................................... 84
Property Types in ResCompiler ASCII Resource Files ............................................................... 192
Push Button Event ....................................................................................................................... 144
R
Radio Button Controls.................................................................................................................. 140
Radio Button Controls Defined in ResCompiler........................................................................... 211
Raised Edge Property Setting...................................................................................................... 234
RCLICKED Grid Notify Event....................................................................................................... 163
Read-only Text Property Setting.................................................................................................. 234
Redraw Grid - GRID SENDMSG() Function 76 ........................................................................... 269
Redraw Row - GRID SENDMSG() Function 50........................................................................... 256
Remove a Tab - TABCTRL SENDMSG() Function 26 ................................................................ 294
Remove All Tabs - TABCTRL SENDMSG() Function 25 ............................................................ 294
ResBuilder
Moving to from GUIBuilder ...................................................................................................... 85
ResBuilder Interface Description ................................................................................................. 173
Resource File Contents and Structure in ResCompiler ............................................................... 190
Resource Files
Checking vs. .gaf Files ............................................................................................................ 82
Creating New in ResBuilder .................................................................................................. 174
Opening Existing in ResBuilder............................................................................................. 174
Saving in ResBuilder ............................................................................................................. 175
Restore String Property Setting ................................................................................................... 235
Right-Side Data Entry Property Setting ....................................................................................... 235
308
ROWCANCEL Grid Notify Event ................................................................................................. 166
ROWCHANGE Grid Notify Event................................................................................................. 163
ROWDELETE Grid Notify Event .................................................................................................. 165
ROWINSERT Grid Notify Event................................................................................................... 165
ROWUPDATE Grid Notify Event ................................................................................................. 166
Running GUIBuilder Programs ...................................................................................................... 84
Running Programs ......................................................................................................................... 84
Running ResCompiler .................................................................................................................. 220
S
Saving Resource Files in ResBuilder .......................................................................................... 175
Scroll Bar Orientation Property Setting........................................................................................ 233
Scroll Bar Proportion Property Setting......................................................................................... 229
Scroll Bar Thumb Size Property Setting ...................................................................................... 229
Scroll Bar, Horizontal Property Setting ........................................................................................ 228
Scroll Bar, Vertical Property Setting............................................................................................. 238
Scrollbar Move Event................................................................................................................... 151
Select Tab - TABCTRL SENDMSG() Function 34....................................................................... 297
SENDMSG() Functions - Send Message to Windows and Controls
Tab Control............................................................................................................................ 292
Set !CTYPE Value - INPUTE SENDMSG() Function 37 ............................................................. 287
Set !EDIT Value - INPUTE SENDMSG() Function 33 ................................................................. 285
Set !EDIT Value - INPUTN SENDMSG() Function 32 ................................................................. 291
Set Background Color - INPUTE SENDMSG() Function 32........................................................ 285
Set Background Color - INPUTN SENDMSG() Function 29 ....................................................... 290
Set Best Fit - GRID SENDMSG() Function 24............................................................................. 244
Set Cell/Row Highlight - GRID SENDMSG() Function 49 ........................................................... 256
Set Channel and Template - GRID SENDMSG() Function 80 .................................................... 271
Set Column Width - GRID SENDMSG() Function 36 .................................................................. 252
Set Continue Message - GRID SENDMSG() Function 82........................................................... 274
Set Current Heading Mode - GRID SENDMSG() Function 77 .................................................... 270
Set Cursor - GRID SENDMSG() Function 78 .............................................................................. 270
Set Default Alignment - GRID SENDMSG() Function 84 ............................................................ 276
Set Default Background Color - GRID SENDMSG() Function 55 ............................................... 260
Set Default Style - GRID SENDMSG() Function 83 .................................................................... 275
Set Default Text Color - GRID SENDMSG() Function 56............................................................ 261
Set Drag Accept - GRID SENDMSG() Function 33 ..................................................................... 251
Set Edit Mask - GRID SENDMSG() Function 79 ......................................................................... 270
309
Set Edit Text - GRID SENDMSG() Function 35........................................................................... 251
Set Extended Text Options - GRID SENDMSG() Function 27 .................................................... 246
Set Heading Dark Shadow Color - GRID SENDMSG() Function 52 ........................................... 257
Set Heading Light Shadow Color - GRID SENDMSG() Function 53........................................... 258
Set Heading Shadow Height - GRID SENDMSG() Function 51.................................................. 257
Set Heading Spacing - GRID SENDMSG() Function 28 ............................................................. 246
Set Heading Titles - GRID SENDMSG() Function 23.................................................................. 243
Set Highlight Method - GRID SENDMSG() Function 57.............................................................. 262
Set Horizontal Lines - GRID SENDMSG() Function 58 ............................................................... 262
Set Horizontal Scroll Mode - GRID SENDMSG() Function 59 .................................................... 262
Set Image List ID - GRID SENDMSG() Function 75.................................................................... 269
Set Insert Mode - INPUTE SENDMSG() Function 36.................................................................. 286
Set Insert Mode - INPUTN SENDMSG() Function 33 ................................................................. 291
Set Interspace - GRID SENDMSG() Function 60 ........................................................................ 263
Set Last Record Dialog - GRID SENDMSG() Function 86 .......................................................... 277
Set Left Margin - INPUTE SENDMSG() Function 30................................................................... 284
Set Left Margin - INPUTN SENDMSG() Function 27 .................................................................. 289
Set Length - INPUTE SENDMSG() Function 34.......................................................................... 286
Set Line Color - GRID SENDMSG() Function 61 ........................................................................ 263
Set Margin - GRID SENDMSG() Function 62.............................................................................. 263
Set Margin Mode - GRID SENDMSG() Function 63.................................................................... 264
Set Mask - INPUTE SENDMSG() Function 23 ............................................................................ 282
Set Minimum Height - Status Bar SENDMSG() Function 25....................................................... 280
Set Mouse Capture Mode - GRID SENDMSG() Function 64 ...................................................... 264
Set Mouse Scrolling Mode - GRID SENDMSG() Function 65 ..................................................... 265
Set Multiple Cells - GRID SENDMSG() Function 21 ................................................................... 242
Set Multiple Rows - GRID SENDMSG() Function 87 .................................................................. 277
Set Number of Columns - GRID SENDMSG() Function 66......................................................... 265
Set Number of Rows - GRID SENDMSG() Function 67 .............................................................. 266
Set OMask - INPUTN SENDMSG() Function 23 ......................................................................... 288
Set Pad Character - INPUTE SENDMSG() Function 27 ............................................................. 283
Set Parts - Status Bar SENDMSG() Function 27......................................................................... 281
Set Position - INPUTE SENDMSG() Function 25........................................................................ 283
Set Position - INPUTN SENDMSG() Function 30........................................................................ 290
Set Restore String - INPUTE SENDMSG() Function 29.............................................................. 284
Set Restore String - INPUTN SENDMSG() Function 31 ............................................................. 290
Set Row Height - GRID SENDMSG() Function 68 ...................................................................... 266
310
Set Single Cell - GRID SENDMSG() Function 22........................................................................ 243
Set Tab Attributes - TABCTRL SENDMSG() Function 36 ........................................................... 297
Set Tab Icon/Label Padding - TABCTRL SENDMSG() Function 24 ........................................... 294
Set Tab Image List ID - TABCTRL SENDMSG() Function 35..................................................... 297
Set Tab Index Focus - TABCTRL SENDMSG() Function 39 ...................................................... 298
Set Tab Width and Height - TABCTRL SENDMSG() Function 23 .............................................. 293
Set Text - Status Bar SENDMSG() Function 20 .......................................................................... 278
Set Text Color - INPUTE SENDMSG() Function 31 .................................................................... 285
Set Text Color - INPUTN SENDMSG() Function 28.................................................................... 289
Set Thumb Update Mode - GRID SENDMSG() Function 69....................................................... 267
Set Title - INPUTE SENDMSG() Function 21.............................................................................. 281
Set Title - INPUTN SENDMSG() Function 21.............................................................................. 287
Set Top Row - GRID SENDMSG() Function 70 .......................................................................... 267
Set Up Grid - GRID SENDMSG() Function 30 ............................................................................ 247
Set User Resize - GRID SENDMSG() Function 74 ..................................................................... 269
Set Vertical Lines - GRID SENDMSG() Function 72 ................................................................... 268
Set Vertical Scroll Mode - GRID SENDMSG() Function 71......................................................... 268
SETFOCUS Notify Event ............................................................................................................. 164
SETOPTS Options in Configurator .................................................................................................. 9
Shortcue Text Property Setting.................................................................................................... 236
Single Custom Edit Paragraph Property Setting.......................................................................... 233
SQL Settings in Configurator ......................................................................................................... 10
SQL.INI File in DDBuilder .............................................................................................................. 17
Standard Button IDs..................................................................................................................... 128
Start Edit - GRID SENDMSG() Function 31 ................................................................................ 248
Static Text Controls Defined in ResCompiler .............................................................................. 213
Status Bar
Defining in ResBuilder ........................................................................................................... 179
Status Bar Controls ...................................................................................................................... 140
Status Bar Definition Property Setting ......................................................................................... 236
Status Bar Text Property Setting ................................................................................................. 230
Subroutines and Functions
SYSCOLOR Event Automanagement Property Setting .............................................................. 230
SYSGUI Device
Coordinate Systems .............................................................................................................. 127
Event Masks .......................................................................................................................... 143
Event Queue And Events ...................................................................................................... 143
SYSGUI Device Settings in Configurator......................................................................................... 2
311
SYSPRINTER Settings in Configurator ........................................................................................... 4
System Color Change Event........................................................................................................ 151
SYSWINDOW Settings in Configurator ........................................................................................... 3
T
Tab Character, Ignored in Text Input Property Setting ................................................................ 228

Tab Controls................................................................................................................................. 141
Tab Controls Defined in ResCompiler ......................................................................................... 214
Tab Full Justification Property Setting ......................................................................................... 235
Tab Height Property Setting......................................................................................................... 236
Tab No Justification Property Setting .......................................................................................... 234
Tab Order Of Controls
Modifying in ResBuilder......................................................................................................... 185
Tab Rows, Display All Property Setting ....................................................................................... 232
Tab Width Property Setting.......................................................................................................... 237
Tab, Initial Property Setting.......................................................................................................... 229
TABLEUPDATE Grid Notify Event............................................................................................... 165
Tabs Displayed as Buttons Property Setting ............................................................................... 223
TAOS Data Dictionaries
Application-Specific Column Attributes ................................................................................... 36
Application-Specific Table Attributes....................................................................................... 32
Application-Specific Typedef Attributes................................................................................... 29
Column Input Attributes ........................................................................................................... 35
Column Output Attributes ........................................................................................................ 36
Column Rules .......................................................................................................................... 38
Form and Process Attributes ................................................................................................... 32
General Rules.......................................................................................................................... 26
General Typedef Attributes ..................................................................................................... 27
Table Rules ............................................................................................................................. 34
Typedef Input Attributes .......................................................................................................... 28
Typedef Output Attributes ....................................................................................................... 29
Typedef Rules ......................................................................................................................... 31
Typedefs.................................................................................................................................. 27
TAOS Rules
Column Rules .......................................................................................................................... 37
General Rules.......................................................................................................................... 26
Table Rules ............................................................................................................................. 33
Typedef Rules ......................................................................................................................... 30
TCP Socket Settings in Configurator ............................................................................................... 9
Text Justification Property Setting ............................................................................................... 230
The GUIBuilder Interface ............................................................................................................... 76
Title Bar, None Property Setting .................................................................................................. 232
Title of Windows Property Setting................................................................................................ 237
Tool Button Controls .................................................................................................................... 141
312
Tool Button Controls Defined in ResCompiler ............................................................................. 216
Tool Button Push Event ............................................................................................................... 152
Tool tip Text Property Setting ...................................................................................................... 236
Tools Used with GUIBuilder
DDBuilder ................................................................................................................................ 86
ResBuilder ......................................................................................................................... 85, 86
Visual PRO/5 Console............................................................................................................. 86
TOPROWCHANGE Grid Notify Event ......................................................................................... 164
Tutorial
Data-Aware Grid Control ......................................................................................................... 63
Standard Grid Control - User-Modifiable ................................................................................. 60
U
UDP Socket Settings in Configurator............................................................................................... 9

Ungrouping And Grouping Controls in ResBuilder ...................................................................... 183
Using
ResBuilder ............................................................................................................................. 173
Using ResCompiler ...................................................................................................................... 190
V
Variables
Generated Program................................................................................................................. 84
Vertical Scroll Bar Controls .......................................................................................................... 142
Vertical Tab Spacing Property Setting......................................................................................... 237
Viewing GUIBuilder Programs ....................................................................................................... 84
Views Created In DDBuilder
General Instructions For Creating And Defining ............................................................... 39, 44
Views For Use With Non-Normalized Data ............................................................................. 44
Views For Use With Normalized Data ..................................................................................... 39
Visual PRO/5 Console
Moving to ................................................................................................................................. 86
W
What is a Data Dictionary? ............................................................................................................ 15

WHERE Clause
Used With DDBuilder-Created Views...................................................................................... 44
Window Focus Gained/Lost Event............................................................................................... 152
Window Properties - Setting Defaults in ResBuilder.................................................................... 179
Window Resize Event .................................................................................................................. 153
Window Resizing Property Setting............................................................................................... 236
Windows
SYSGUI
Definition ............................................................................................................................... 126
313
Windows and Dialogs Defined in ResCompiler ........................................................................... 194
Word Wrap, Preventing Property Setting..................................................................................... 233
Word Wrap, Setting Property Setting........................................................................................... 238
314

Visual 1

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Visual 1

Diunggah oleh

Hak Cipta:

Format Tersedia

Visual PRO/5®

USING THE GRID CONTROL IN VISUAL PRO/5

GUI CONTROLS AND EVENTS

RESOURCE PROPERTY INDEX

BASIS International Ltd.

The Configurator Interface

Creating New Configuration Files

Opening Existing Configuration Files

Saving Configuration Files

Printing Configuration Files

Setting Configuration File Options

Setting DSKSYN, SYSGUI, and Limits Configuration Options

Setting PREFIX and Global String Options

Setting SYSWINDOW Options

Setting SYSPRINTER Options

Setting Printer Options

Setting Plotter Properties

Setting TCP Socket Options

Setting UDP Socket Options

Setting SETOPTS Options

Setting SQL Options

Defining the SQL.INI file path

Defining the Data Source Name and Configuration File

Setting Novell-Specific Options

Enabling Transaction Tracking

Creating NSPOOL Devices

What is a Data Dictionary?

Modifying PRO/5, ODBC Driver, and BBX PROGRESSION/4 Data Dictionaries

Creating Data Dictionaries for Use with TAOS

Modifying Data Dictionaries for Use with TAOS

The DDBuilder Interface

Creating a New Data Dictionary

Creating a Data Source

Making Data Files

To make data files, do the following:

1 In the tree view, click on the icon of a table to select it.

Opening an Existing Data Dictionary

Opening a Configuration File

Saving a Data Dictionary

Printing the DDBuilder Tree View

Print Prints the current document.

Next Page Displays the next page of the structure.

Prev Page Displays the previous page of the structure.

One Page Displays one page on the screen.

Two Page Displays two pages on the screen.

Closing a Data Source

Adding Elements to a Data Dictionary

Inserting Columns into a Data Dictionary

Copying Data Dictionary Elements to the Clipboard

Pasting Data Dictionary Elements from the Clipboard

Deleting Elements from a Data Dictionary

Reversing/Reinstating the Last Modification

Renaming Data Dictionary Elements

DDBuilder Naming Conventions and Reserved Words

ABORT ACCUMULATE ACROSS ADD ALL

Defining General Data Dictionaries

Defining General Data Sources

Defining General Table Attributes

Defining Data Dictionaries for Use with TAOS

Defining General Rules

Defining General Typedef Attributes

Defining Application-Specific Typedef Attributes

Vertical Scrollbar N(4*=0) scrollbar position dec(ctrl(gbsysgui, ‘SCROLLPOS’(gbctl_

fngbtemplate$(gbwin_id$) - Get String Template Given Window ID