Professional Documents
Culture Documents
Visual 1
Visual 1
Visual 1
CONFIGURATOR
DDBUILDER®
GUIBUILDER™
RESBUILDER™
RESCOMPILER
SENDMSG() FUNCTIONS
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.
Getting Started
1
• Press <Ctrl>+ O.
2 Move to the directory that contains the file, select it, and click Open.
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.
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.
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.
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.
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.
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
only by Visual PRO/5 processes with a FID(0)=T?.
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
desired characters. You can either select the desired characters by clicking them in the grid, or
by entering them into the CR= box.
When you have finished selecting all desired characters, click OK.
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.
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.
When you have finished selecting all desired characters, click OK.
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.
When you have finished selecting all desired characters, click OK.
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.
When you have finished selecting all desired characters, click OK.
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
desired characters. You can either select the desired characters by clicking them in the grid, or
by entering them into the LF= box.
When you have finished selecting all desired characters, click OK.
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.
When you have finished selecting all desired characters, click OK.
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
When you have finished selecting all desired characters, click OK.
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
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.
When you have finished selecting all desired characters, click OK.
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.
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.
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.)
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$
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.
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.
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.
• When you have finished selecting all desired characters, click OK.
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
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 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
desired characters. You can either select the desired characters by clicking them in the grid, or
by entering them into the CR= box.
When you have finished selecting all desired characters, click OK.
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.
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
When you have finished selecting all desired characters, click OK.
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.
• When you have finished selecting all desired characters, click OK.
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.
When you have finished selecting all desired characters, click OK.
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
desired characters. You can either select the desired characters by clicking them in the grid, or
by entering them into the LF= box.
When you have finished selecting all desired characters, click OK.
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
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.
When you have finished selecting all desired characters, click OK.
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.
When you have finished selecting all desired characters, click OK.
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.
When you have finished selecting all desired characters, click OK.
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.
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.
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.
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).
3 Save the data dictionary (see Saving a Data Dictionary).
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
Getting Started
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.
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.
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.
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
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.
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
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.
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
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.
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.)
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.
3 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.)
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.
27
Defining Typedef Input Attributes
To define typedef input attributes, do the following:
1 In the tree view, select the desired typedef to display the General Typedef properties page.
2 Click the Input tab to display the Input properties page.
3 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.)
28
Defining Typedef Output Attributes
To define typedef output attributes (i.e., report title, output mask, and the default column value), do the following:
1 In the tree view, select the desired typedef to display the General Typedef properties page.
2 Click the Format tab to display the Format properties page.
3 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.)
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:
1 In the tree view, select the desired typedef to display the General Typedef properties page.
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:
1 In the tree view, select the desired typedef to display the General Typedef properties page.
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:
1 In the tree view, select the desired table to display the General Table properties page.
2 Click the Options tab to display the Options properties page.
3 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.)
32
Selecting Tables Rules
Once data dictionary general rules have been defined, they can be selected for individual tables, as follows:
1 In the tree view, select the desired table to display the General Table properties page.
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.
5 To remove a rule from the Current rules field, either double-click the rule, or select it and then click the Remove
button.
33
Editing Table Rules
Once table rules have been selected, they can be customized without affecting the general rules definitions, as follows:
1 In the tree view, select the desired table to display the General Table properties page.
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.
5 Edit the values in the Error message, Error procedure, and Success procedure fields, to customize the rules for
the selected typedef:
34
Defining Column Input Attributes
To define the TAOS form input attributes for a selected column, do the following:
1 In the tree view, select the desired column to display the General Column properties page.
2 Click the Input tab to display the Input properties page.
3 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.)
35
Defining Column Output Attributes
To define output attributes (i.e., report title, output mask, and the default column value), do the following:
1 In the tree view, select the desired column to display the General Column properties page.
2 Click the Format tab to display the Format properties page.
3 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.)
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:
1 In the tree view, select the desired column to display the General Column properties page.
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.
5 To remove a rule from the Current rules field, either double-click the rule, or select it and then click the Remove
button.
37
Editing Column Rules
Once column rules have been selected, they can be customized without affecting the general rules definitions, as
follows:
1 In the tree view, select the desired column to display the General Column properties page.
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 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.
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.
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.
41
0003 John Lim
0004 Laura Montini
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.)
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.
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:
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 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.
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:
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
5 On the Program menu, select Run Program.
6 In the Save Program dialog, click the Save button. The program will present the grid as it did before.
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.
1 On the Object drop-down list, select Form 101 frmDataAwareGrid.
2 On the Control drop-down list, select Push Button 104 btnDelete.
3 On the Event drop-down list, select Button Pushed.
4 In the GUIBuilder edit area, add code that will be executed any time the user clicks the Delete button:
gosub delete current row
5 On the Object drop-down list, select New Subroutine/Function.
6 In the Name Subroutine/Function dialog, type the following:
Delete Current Row
7 Click OK.
8 Beneath the header remarks in the GUIBuilder edit area, enter the following code:
delete_current_row:
rem get the current row
grid_id=num(fattr(datagrid_temp$,"grdTestGrid","ID"))
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.
1 On the Program menu, select Run Program.
2 In the Save Program dialog, click the Save button. The program will present the grid as it did before.
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.
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.
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
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
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.
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.
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
1 Do one of the following:
• 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 Subroutines/Functions
To edit code in subroutines, functions, or non-executing statements like TABLE, IOLIST, and DATA, do the following:
1 Do one of 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
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.
Checking Resources
To check a GUIBuilder (.gbf) file against the corresponding resource file, do the following:
1 Do one of 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.
83
Viewing GUIBuilder Programs
To view the program, do the following:
1 Do one of 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.
The following variables are available only within the event loop:
84
Variable Description
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__.
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.
Helper Functions
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)
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.
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.
88
>print Hello.Message$
Hello from GUIBuilder!
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)
: +ctrl(gb__sysgui,0,2,gb__context)
: +ctrl(gb__sysgui,0,0,gb__context)
: +ctrl(gb__sysgui,0,1,gb__context)
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$
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
n = fngb__put_code("",
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
n = fngb__put_code("",
[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
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.
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__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 Copyright (C) 1998 BASIS International Ltd. All Rights Reserved.
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 Copyright (C) 1998 BASIS International Ltd. All Rights Reserved.
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.
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.
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.
Description
This function returns a control description for a given control type. If the control type is invalid or unknown, “ is returned.
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.
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.
Description
This routine runs the generated program.
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.
Description
This routine returns a list of all child windows on the specified context.
Parameter Description
gb__sysgui The channel that the SYSGUI device is opened on.
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.
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.
Description
This routine returns a list of all controls on the specified context.
Parameter Description
gb__sysgui The channel that the SYSGUI device is opened on.
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.
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.
Description
This routine returns a list of all forms on a resource.
Parameter Description
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$.
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.
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.
Description
This routine returns a list of all child windows on a top-level window in a resource.
Parameter Description
102
reshandle The handle that the target resource is opened on.
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.
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.
This routine does not check to see if there is enough memory to get the window information (RESINFO). An error 31
may result in cases where the window being evaluated is very complex and contains many controls.
Description
This routine returns a list of all controls on the specified form in a resource.
Parameter Description
reshandle The handle that the target resource is opened on.
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.
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.
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.
103
Conversions and File Formats
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.
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.
107
Called Programs
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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).
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).
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$
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
Mnemonic Description
'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.
Creating
Mnemonic Description
'CHECKBOX' Create a Check Box Control.
Manipulating
Mnemonic Description
130
'CHECK' Check Object (By default, check boxes are initially unchecked.)
'UNCHECK' Uncheck Object.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the control title.
2 Returns the checked/unchecked status of the check box.
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.
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
Mnemonic Description
'CHILD' Create Child Window.
Manipulating
Mnemonic Description
'CONTEXT' Set Device Context.
'DOCK' Change Child Window Docking Position.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the control title.
4 Returns the class and type of the control.
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.
131
Creating
Mnemonic Description
'TXEDIT' Create A Custom Edit Control.
Modifying
Mnemonic Description
'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
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
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.
4 Returns the control class and type.
5 Returns the text of a specified paragraph.
7 Returns the text of all paragraphs.
8 Returns the visible/invisible and enabled/disabled status of the control.
12 Returns the current text selection.
15 Returns the background color of the control.
16 Returns the foreground color of the control.
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
Mnemonic Description
'EDIT' Create an Edit Control.
Manipulating
Mnemonic Description
'SELECT' Select Text (Used to position the caret or select text.)
'TITLE' Set Control Title.
Querying
CTRL() Function Description
132
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the text of the edit control
4 Returns the control class and type.
8 Returns the visible/invisible and enabled/disabled status of the control.
12 Returns the current text selection.
15 Returns the background color of the control.
16 Returns the foreground color of the control.
Creating
Mnemonic Description
'GROUPBOX' Create a Group Box Control.
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.
Creating
Mnemonic Description
'HSCROLL' Create a Horizontal Scroll Bar Control.
Manipulating
Mnemonic Description
'SCROLLPOS' Set Scroll Bar Position.
'SCROLLPROP' Set Scroll Bar Proportion.
'SCROLLRANGE' Set Scroll Bar Range.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
2 Returns a 2-byte integer containing the location and value of the thumb position.
4 Returns the control class and type.
8 Returns the visible/invisible and enabled/disabled status of the control.
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
Mnemonic Description
'IMAGE' Draw Bitmapped Image.
Manipulating
Mnemonic Description
'TRACK' Toggle Tracking On/Off (Setting this to 0 prevents the image from being resized when the
window is resized.
Creating
Mnemonic Description
'INPUTE' Create a Graphical Edit (INPUTE) Control.
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.
Creating
Mnemonic Description
134
'INPUTN' Create a Numeric Edit (INPUTN) Control.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the control title.
2 Returns an 8-byte string representing a business math value using:
DIM B$:"BUS:B"B.BUS$=CTRL(sysgui,controlid,2)
Creating
Mnemonic Description
'LISTBOX' Create a List Box Control.
Manipulating
Mnemonic Description
'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
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
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.
4 Returns the control class and type.
7 Returns the text of all items with ($0A$) after each paragraph, including the last item.
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.
Creating
Mnemonic Description
'LISTBUTTON' Create a List Button Control.
Manipulating
Mnemonic Description
'LISTADD' Add List Item.
'LISTCLR' Clear List.
'LISTDEL' Delete List Item.
'LISTRESUME' Resume List Updates.
'LISTSEL' Select List Item.
'LISTSUSPEND' Suspend List Updates.
'LISTUNSEL' Deselect List Item.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the text of selected items, delimited by $0A$ (but no final $0A$).
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.
4 Returns the control class and type.
7 Returns the text of all items with ($0A$) after each paragraph, including the last item.
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.
136
Creating
Mnemonic Description
'LISTBUTTON' Create a List Button Control.
Manipulating
Mnemonic Description
'LISTADD' Add List Item.
'LISTCLR' Clear List.
'LISTDEL' Delete List Item.
'LISTRESUME' Resume List Updates.
'LISTSEL' Select List Item.
'LISTSUSPEND' Suspend List Updates.
'LISTUNSEL' Deselect List Item.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
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.
3 Returns the number of selected items followed by the total number of items in the list.
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.
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}
Parameter Description
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
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$
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$
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.
Creating
Mnemonic Description
'RADIOBUTTON' Create a Radio Button Control.
Manipulating
Mnemonic Description
'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
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the control title.
2 Returns the checked/unchecked status of the radio button.
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.
Creating
Mnemonic Description
'STATBAR' Create a Status Bar Control
140
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the status bar text.
4 Returns the control class and type.
7 Returns the status bar text. Results are identical to those of function 1.
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.
Tab Controls
Tab controls provide the capability to multiple logical pages or sections of information within the same window.
Creating
Mnemonic Description
'TABCTRL' Create a Tab Control.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the index of the currently-selected tab.
4 Returns the control class and type.
7 Returns the status bar text. Results are identical to those of function 1.
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.
141
• Does not include a “focus rectangle” when it has focus.
Typically, tool buttons are grouped together in a tool bar.
Creating
Mnemonic Description
'TBUTTON' Create a Tool Button Control
Manipulating
Mnemonic Description
'TITLE' Set Control Title (Sets the tool button text).
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
1 Returns the tool button title or bitmap image filename.
2 Returns the up/down status of the tool button.
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.
Creating
Mnemonic Description
'VSCROLL' Create a Vertical Scroll Bar Control.
Manipulating
Mnemonic Description
'SCROLLPOS' Set Scroll Bar Position.
'SCROLLPROP' Set Scroll Bar Proportion.
'SCROLLRANGE' Set Scroll Bar Range.
Querying
CTRL() Function Description
0 Returns the outer rectangle of the control in current scaled units.
2 Returns a 2-byte integer containing the location and value of the thumb position.
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.
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.
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
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
Mandatory/Optional: Optional
Event Mask bit: $02000000$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
Field Description
context Window that was closed.
code X
id 0
flags 0
x 0
y 0
144
Control Focus Gained/Lost Event
Mandatory/Optional: Optional
Event Mask bit: $00800000$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
Mandatory/Optional: Optional
Event Mask bit: $00000400$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
Mandatory/Optional: Optional
Event Mask bit: $01000000$.
146
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
Mandatory/Optional: Optional
Event Mask bit: $00000040$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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.
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
Field Description
context Current window.
code u
id Mouse button:
$00$ = Left
$01$ = Right
$02$ = Middle
flags Key pressed:
$01$ = Shift
$02$ = Ctrl
x Horizontal pixel location of the mouse click.
y Vertical pixel location of the mouse click.
Mandatory/Optional: Optional
The mouse was double clicked.
Event mask bit: $00000200$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
Field Description
context Current window.
code 2
id Mouse button:
$00$ = Left
$01$ = Right
$02$ = Middle
flags $01$ = Shift key pressed.
$02$ = Ctrl key pressed.
x Horizontal pixel location of the mouse click.
y Vertical pixel location of the mouse click.
148
Mouse Move Event
Mandatory/Optional: Optional
Event Mask bit: $00000100$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
Field Description
context Current window.
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$
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").
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.
Mandatory/Optional: Optional
Event Mask bit: $00100000$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
Field Description
context Window containing the scrollbar that was moved.
code p
id 0
flags 0
x New scrollbar location.
y 0
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
Field Description
151
context Current window.
code s
id 0
flags $01$ = system colors changed.
x 0
y 0
Mandatory/Optional: Mandatory
Event Mask bit: None. Event is always visible.
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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
Mandatory/Optional: Optional
Event Mask bit: $00000004$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
Field Description
context Window that gained or lost focus.
code F
id 0
flags 0
x 0
y 0
152
Window Resize Event
Mandatory/Optional: Optional
Event Mask bit: $00000008$
Event Template
context:u(2),code:c(1),id:u(2),flags:u(1),x:u(2),y:u(2)
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.
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
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
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 in which the event occurred.
code 2.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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).
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 in which the event occurred.
code 3.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
wparam Extended key status flag, which identifies the status of the <Shift>
and <Ctrl> keys:
• Bit $01$ set = <Ctrl> pressed.
155
• Bit $02$ set = <Shift> pressed.
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.
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 in which the event occurred.
code 4.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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.
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 in which the event occurred.
code 5.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
156
EDITKEY Grid Notify Event
Description
A special key was pressed while the grid was in edit mode.
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 in which the event occurred.
code 6.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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.
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),
157
ptx:i(2),pty:i(2),buf:c(1*)
Significant Field Description
context Context in which the event occurred.
code 7.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
col Number of the column being edited.
row Number of the row being edited.
buf Edit control text.
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 in which the event occurred.
code 8.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
col Number of the current column.
row Number of the current row.
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 9.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
wparam Extended key status flag, which identifies the status of the <Shift>
and <Ctrl> keys:
158
• Bit $01$ set = <Ctrl> pressed.
• Bit $02$ set = <Shift> pressed.
col Number of the current column.
row Number of the current row.
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 10.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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.
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 in which the event occurred.
code 11.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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
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 in which the event occurred.
code 12.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
wparam Value of the key pressed. Returns the same information as a key
press event for the SYSGUI channel.
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 13.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
col Number of the current column.
row Number of the current row.
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*)
160
Significant Field Description
context Context in which the event occurred.
code 14.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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.
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.
ptx,pty Point within the cell that was clicked.
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 in which the event occurred.
code 15.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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 containing the clicked cell.
row Number of the row containing the clicked cell.
x, y,w,h Rectangle containing the clicked cell.
ptx,pty Point within the cell that was clicked.
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
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 in which the event occurred.
code 16.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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 new left column (zero-based).
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 in which the event occurred.
code 17.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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.
lparam Mouse button position:
• 0 Button pressed.
• 1 Button released.
col Number of the column containing the clicked cell.
row Number of the row containing the clicked cell.
162
x, y,w,h Rectangle containing the clicked cell.
ptx,pty Point within the cell that was clicked.
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.
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 in which the event occurred.
code 18.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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.
lparam Mouse button position:
• 0 Button pressed.
• 1 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.
ptx,pty Point within the cell that was clicked.
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 in which the event occurred.
code 19.
163
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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.
row Number of the row that was just selected (zero-based).
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 in which the event occurred.
code 20.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
col Number of the current column.
row Number of the current row.
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 in which the event occurred.
code 21.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
wparam Extended key status flag, which identifies the status of the <Shift>
and <Ctrl> keys:
• Bit $01$ set = <Ctrl> pressed.
164
• Bit $02$ set = <Shift> pressed.
row Number of the row that was just selected (zero-based).
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)
Significant Field Description
context Context in which the event occurred.
code 22
id ID of the resource that caused the event.
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
Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),row:i(4),rcd:c(1*=)
Significant Field Description
context Context in which the event occurred.
code 24
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
row Number of the inserted row.
rcd Record inserted, deleted or updated. (This field is empty if a
record/row insert cancellation is identified.)
165
Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),row:i(4),rcd:c(1*=)
Significant Field Description
context Context in which the event occurred.
code 25
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
row Number of the deleted row.
rcd Record inserted, deleted or updated. (This field is empty if a
record/row insert cancellation is identified.)
Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),row:i(4),rcd:c(1*=)
Significant Field Description
context Context in which the event occurred.
code 26
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
row Number of the row whose insertion was canceled.
rcd Record inserted, deleted or updated. (This field is empty if a
record/row insert cancellation is identified.)
Event Template
context:u(2),code:i(1),id:u(2),objtype:i(2),row:i(4),rcd:c(1*=)
Significant Field Description
context Context in which the event occurred.
code 27
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
row Number of the updated row.
rcd Record inserted, deleted or updated. (This field is empty if a
record/row insert cancellation is identified.)
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*)
Significant Field Description
context Context in which the event occurred.
code 28.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
msg Event code number.
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*)
Significant Field Description
context Context in which the event occurred.
code 29.
id ID of the resource that caused the event.
objtype Type of resource that caused the event.
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.
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
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:
if event.code$="N" then
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.")
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:
if event.code$="N" then
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
gosub display_tab2_values
else
gosub display_tab3_values
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
context Context the event occurred in.
code Always 3.
id Tab control's ID.
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
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.
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:
• On the File menu, select Save.
• 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
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.
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.
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.
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:
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.
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.
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.
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.
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.
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>.
• Right-click to display the context-sensitive menu, then click 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>.
• Right-click to display the context-sensitive menu, then click Delete.
Menus
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.
187
Image Lists
Printing
ResBuilder allows you to preview an image of the contents of forms and child windows, set up the printer , and print the image.
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:
• On the File menu, select Print.
• 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 files create and define resources for use in Visual PRO/5 applications, and contain the following:
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
Second edit control 50
y Window 0 Defines the vertical position of the upper-left
corner of the resource in current units.
First edit control 10
Second edit control 10
width Window 200 Defines the width of the resource in current units.
First edit control 50
Second edit control 50
height Window 100 Defines the height of the resource in current units.
First edit control 25
Second edit control 25
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
Initialcontents "Figures" //Default Contents
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"
Window 1 "Status" 0 0 200 100
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"
Font "Arial" 12, Bold, CS_DEFAULT
192
Justification $2000$
Foregroundcolor Rgb(128,255,128)
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.
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
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
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.
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
menu-item 1011 "&Open"
menu-item 1012 "&Save"
separator
menu-item 1013 "E&xit"
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
menu-item 1011 "&Open"
begin
menu-item 1012 "&Save"
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
menu-item 1113 "E&xit"
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:
Property Description
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.
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
The following describes the child window properties:
Property Description
child-window Defines the resource as a child window.
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
The following describes the child window properties:
Property Description
child-window Defines the resource as a child window.
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
Checkbox 2 "Done" 10 10 50 25
End
End
Window 2000 "Second Window" 0 0 400 200
Begin
Button 1 "OK" 10 10 50 25
Checkbox 2 "Done" 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
Checkbox 2 "Done" 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.
Button Controls
The following lists the mandatory properties for button controls:
Button control-id "title" x y width height
Property Description
button Specifies the control as a button control.
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.
"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.
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"
Font "Arial" 12, Bold, CS_DEFAULT
Backgroundcolor $debabe$
Foregroundcolor $ccffcc$
Clientedge Raisededge
Justification JUSTIFICATION_LEFT
End
End
Example
The following example contains a window with two check box 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
Begin
Checkbox 1 "OK" 10 10 50 25
Checkbox 2 "Done" 50 10 50 25 Begin
Checked Group Clientedge Raisededge
Justification $2000$
Font "Arial" 12, Bold, CS_DEFAULT
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
End
End
203
Custom Edit Controls
The following lists the mandatory properties for custom edit controls:
Customedit control-id "title" x y width height
Property Description
customedit Specifies the control as a custom edit control.
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.
"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.
The Resource Properties Index identifies and describes the optional properties for this control.
Example
The following example contains a window with two custom edit 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
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
Font "Arial" 12, Bold, CS_DEFAULT
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
End
End
Edit Controls
The following lists the mandatory properties for edit controls:
Edit control-id "title" x y width height
Property Description
edit Specifies the control as an edit control.
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.
"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.
204
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.
The Resource Properties Index identifies and describes the optional properties for this control.
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"
Window 1 "Control Window" 0 0 200 100
Begin
Edit 1 "OK" 10 10 50 25
Edit 2 "Done" 50 10 50 25 Begin
Initialcontents "Editbox 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
Grid Controls
The following lists the mandatory properties for grid controls:
Grid control-id "title" x y width height
Property Description
grid Specifies the control as a grid control.
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.
"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.
The Resource Properties Index identifies and describes the optional properties for this 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"
Window 1 "Control Window" 0 0 200 100
Begin
Grid 1 "OK" 10 10 50 25
Grid 2 "Done" 50 10 50 25 Begin
Backgroundcolor Rgb(128,255,128)
205
Foregroundcolor Rgb(64,128,64)
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
Example
The following example contains a window with two group box 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
Begin
Groupbox 1 "Group One" 10 10 50 25
Groupbox 2 "Group Two" 50 10 50 25 Begin
Invisible Disabled Clientedge Raisededge
Font "Arial" 12, Bold, CS_DEFAULT
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
206
End
End
Image Elements
The following lists the mandatory properties for image elements:
Image control-id x y width height
Property Description
image Specifies the control as an image element.
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.
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.
The Resource Properties Index identifies and describes the optional properties for this control.
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"
Window 1 "Control Window" 0 0 200 100
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
Property Description
inpute Specifies the control as an INPUTE control.
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.
"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.
207
The Resource Properties Index identifies and describes the optional properties for this control.
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"
Window 1 "Control Window" 0 0 200 100
Begin
Inpute 1 "Hello" 10 10 50 25
Inpute 2 "Goodbye" 50 10 50 25 Begin
Font "Arial" 12, Bold, CS_DEFAULT
Initialcontents "(000) 555 1212"
Initialposition 15
Mask "(###) ### ####"
Padcharacter '\n'
Restorestring "(000) 555 1212"
Disabled Invisible Passtab Passenter Highlight
Clientedge Raisededge
End
Inpute 3 "" 50 10 50 25 Begin
Font "Arial" 12, Bold, CS_DEFAULT
Maxlength 15
Padcharacter '\n'
Disabled Invisible Passtab Passenter Highlight
Clientedge Raisededge
End
End
INPUTN Controls
The following lists the mandatory properties for INPUTN controls:
Inputn control-id "title" x y width height
Property Description
inputn Specifies the control as an INPUTN control.
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.
"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.
The Resource Properties Index identifies and describes the optional properties for this control.
Example
The following example contains a window with two INPUTN controls; the first contains only the mandatory definitions, and the
second contains optional settings.
208
Version "3.0"
Window 1 "Control Window" 0 0 200 100
Begin
Inputn 1 "Hello" 10 10 50 25
Inputn 2 "Goodbye" 50 10 50 25 Begin
Font "Arial" 12, Bold, CS_DEFAULT
Initialcontents "(000) 555 1212"
Initialposition 15
Imask "(###) ### ####"
Omask "(###) ### ####"
Rightmostentry Copycommas Decimalreplace Beep
Disabled Invisible Passtab Passenter Highlight
Clientedge Raisededge
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
The Resource Properties Index identifies and describes the optional properties for this control.
Example
The following example contains a window with two line elements; the first contains only the mandatory definitions, while the
second contains optional settings.
Version "3.0"
Window 1 "Control Window" 0 0 200 100
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
209
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.
The Resource Properties Index identifies and describes the optional properties for this control.
Example
The following example contains a window with two list box 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
Begin
Listbox 1 "OK" 10 10 50 25
Listbox 2 "Done" 50 10 50 25 Begin
Font "Arial" 12, Bold, CS_DEFAULT
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
Initialcontents "Item1\nitem2\nitem3\nitem4\n"
Multiselect Clientedge Raisededge Disabled
Invisible
Readonly
End
End
Example
The following example contains a window with two list 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
Begin
Listbutton 1 "OK" 10 10 50 25
210
Listbutton 2 "Done" 50 10 50 25 Begin
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
Font "Arial" 12, Bold, CS_DEFAULT
Initialcontents "Item1\nitem2\nitem3\nitem4\n"
Clientedge Raisededge
End
End
Example
The following example contains a window with two list edit 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
Begin
Listedit 1 "OK" 10 10 50 25
Listedit 2 "Done" 50 10 50 25 Begin
Font "Arial" 12, Bold, CS_DEFAULT
Initialcontents "Item1\nitem2\nitem3\nitem4\n"
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
Clientedge Raisededge
End
End
211
unique within a given top-level window.
"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.
The Resource Properties Index identifies and describes the optional properties for this control.
Example
The following example contains a window with two radio 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
Begin
Radiogroup 1, 2
Radiobutton 1 "OK" 10 10 50 25
Radiobutton 2 "Done" 50 10 50 25 Begin
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
Font "Arial" 12, Bold, CS_DEFAULT
Group Checked Clientedge Raisededge
Justification JUSTIFICATION_LEFT
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...
212
End
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"
Window 1 "Control Window" 0 0 200 100
Begin
Scrollbar 1 10 10 50 25
Scrollbar 2 50 10 50 25 Begin
Backgroundcolor Rgb(128,128,128)
Foregroundcolor $ccffcc$
Initialposition 0
Initialproportion 10
Initialsize 100
Orientation Vertical
Disabled Invisible Clientedge Raisededge
End
Scrollbar 2 50 10 50 25 Begin
Backgroundcolor Rgb(128,128,128)
Foregroundcolor $ccffcc$
Initialposition 0
Initialproportion 10
Initialsize 100
Orientation Horizontal
Disabled Invisible Clientedge Raisededge
End
End
213
Property Description
statictext Specifies the control as a static text control.
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.
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.
The Resource Properties Index identifies and describes the optional properties for this control.
Example
The following example contains a window with two static text 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
Begin
Statictext 1 "OK" 10 10 50 25
Statictext 2 "Done" 50 10 50 25 Begin
Font "Arial" 12, Bold, CS_DEFAULT
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
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
Property Description
tabcontrol Specifies the control as a tab control.
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.
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.
The Resource Properties Index identifies and describes the optional properties for this 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:
Property Description
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"
Window 1 "Control Window" 0 0 400 300
Begin
Tabcontrol 1 "Tab Control 1" 10 225 100 50
Tabcontrol 2 "Tab Control 2" 50 10 300 200
Begin
Backgroundcolor Rgb(128,128,128)
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
Child-window 2000 100 100
Begin
Button 1 "Yes" 10 10 50 25
End
Child-window 3000 100 100
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
Property Description
toolbutton Specifies the control as a tool button control.
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.
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.
The Resource Properties Index identifies and describes the optional properties for this control.
Example
The following example contains a window with two tool 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
Begin
Toolbutton 1 "OK" 10 10 50 25
Toolbutton 2 "Done" 50 10 50 25 Begin
Backgroundcolor Rgb(128,255,128)
Foregroundcolor Rgb(64,128,64)
Clientedge Raisededge
Justification JUSTIFICATION_LEFT
End
End
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
217
<Keypad 9> KEY_KEYPAD_9 $0147$
<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.
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)
219
Vertical VERTICAL 0
Horizontal HORIZONTAL 1
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
Parameter Description
command_line_options Command line options, contained in the table below.
input_files ASCII resource files to be compiled.
• 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.
• 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.
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
223
Applies To Menu Item
Property Type Flag $00000001$
ResCompiler Syntax checkable
ResCompiler Default False
224
Set Current Units
Description Sets the current units of the window.
Applies To Window/Form and Child Window
Property Type Integer
ResCompiler Syntax currentunits
ResCompiler Default 2
225
ResCompiler Syntax dialogborder
ResCompiler Default False
Prevent Focus
Description Prevents the tab control from receiving focus when clicked.
Applies To Tab
Property Type Tab Style Flag $04$
ResCompiler Syntax focusnever
ResCompiler Default False
226
ResCompiler Syntax focusonbuttondown
ResCompiler Default False
227
Applies To INPUTE and INPUTN
Property Type Flag $00000008$
ResCompiler Syntax highlight
ResCompiler Default False
228
Set INPUTN Input Mask
Description Sets the input mask.
Applies To INPUTN
Property Type String
ResCompiler Syntax imask
ResCompiler Default Null
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
ResCompiler Default False
230
Property Type Integer
ResCompiler Syntax margin
ResCompiler Default 0
231
Property Type Flag $00000080$
ResCompiler Syntax minimizable
ResCompiler Default True
232
ResCompiler Syntax notitlebar
ResCompiler Default False
233
ResCompiler Syntax padcharacter
ResCompiler Default 0
234
Applies To Custom Edit
Property Type Flag $00000001$
ResCompiler Syntax readonly
ResCompiler Default False
235
Applies To Menu Item
Property Type Flag $00000002$
ResCompiler Syntax separator
ResCompiler Default False
236
Set Tab Width
Description Sets the tab width.
Applies To Tab
Property Type Integer
ResCompiler Syntax tabwidth
ResCompiler Default 0
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
Property Type String
ResCompiler Syntax title
ResCompiler Default Null
237
ResCompiler Syntax verticalpadding
ResCompiler Default 0
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$)
Parameter Description
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.
240
Set Row Height 68
Separation Lines Set Horizontal Lines 58
Set Vertical Lines 72
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.
Parameter Description
sysgui SYSGUI channel.
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
SENDMSG() Function 83.
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.
Description
This function sets the values in one or more contiguous cells with one command.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
21 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
22 SENDMSG() function number.
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,"",$$,$$)
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,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
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
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
23 SENDMSG() function number.
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.
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.
Parameter Description
Sysgui SYSGUI channel.
id Grid control ID.
24 SENDMSG() function number.
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,"",$$,$$)
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(1)); rem column width
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,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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
25 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
26 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
28 SENDMSG() function number.
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.
Description
This function adjusts the width of the columns specified to fill the entire body of the grid.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
29 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
30 SENDMSG() function number.
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)
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:
sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(50,50,200,150,"Grid Sample",$$,$$)
print (sysgui)'grid'(100,20,20,160,120,$9040$,8,3,3)
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
Description
This function starts editing mode in the specified cell.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
31 SENDMSG() function number.
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.
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$:tmpl(sysgui,ind=1)
dim grid_data$[2,2]
print (sysgui)'window'(50,50,200,150,"Grid Sample",$$,$$)
print (sysgui)'grid'(100,20,20,160,120,$9040$,8,3,3)
result$=sendmsg(sysgui,100,68,150/4,$$); rem row height
result$=sendmsg(sysgui,100,57,0,$$); rem turn off color change highlighting
dim grid$:tmpl(sysgui,ind=1)
grid$=sendmsg(sysgui,100,20,0,$$)
grid.style=1
counter=0
for col=0 to 2
result$=sendmsg(sysgui,100,36,col,chr(51)); rem column width
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$
if event.code$="N" then
: generic$=notice(sysgui,event.x);
: dim notice$:noticetpl(generic.objtype,event.flags);
: 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
if event.code$="N" and notice.code=23 then
: 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
if event.code$="N" and notice.code=22 then
: 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
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
32 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
33 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
34 SENDMSG() function number.
0 Always zero.
$$ Always null.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
35 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
36 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
37 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function returns a binary representation of the width of the specified column, in pixels.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
38 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
39 SENDMSG() function number.
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*=)
Description
This function returns a binary representation of the number of columns in the grid. Use DEC(COLUMNS$) to get the numeric
representation.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
40 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function returns a binary representation of the number of rows in the grid. Use DEC($00$+ROWS$) to get the numeric
representation.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
41 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
42 SENDMSG() function number.
row Row number (zero-based).
$$ Always null.
Note that row numbering is zero-based.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
43 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function returns the binary representation of the currently selected column. Use DEC(COLUMN$) to get the numeric
representation.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
44 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
45 SENDMSG() function number.
0 Always zero.
$$ Always null.
Note that row numbering is zero-based.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
46 SENDMSG() function number.
0 Always zero.
$$ Always null.
Note that row numbering is zero-based.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
47 SENDMSG() function number.
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.
Description
This function sets the row specified as the current row. Use DEC($00$+ROW$) to get the numeric representation.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
48 SENDMSG() function number.
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.
Description
This function sets the highlight mode for cells and rows.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
49 SENDMSG() function number.
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.
256
Description
This function instructs the grid control to redraw the specified row.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
50 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
51 SENDMSG() function number.
height Shadow height, in pixels.
$$ Always null.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
52 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
53 SENDMSG() function number.
rgb$ RGB value.
$$ Always null.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
54 SENDMSG() function number.
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.
The return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success, $00$ indicates
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:
sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(0,20,550,100,"Grid Sample",$00000082$,$ff$)
print (sysgui)'grid'(100,20,20,500,54,$9040$,3,3,5)
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
tf$=sendmsg(sysgui,100,54,0,grid$)
grid.style=8,grid.col=2,grid.row=1; rem create checked checkbox
tf$=sendmsg(sysgui,100,54,0,grid$)
escape
The following example shows SENDMSG() Function 54 used to change default grid appearance and populate a grid with data:
sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(50,50,200,150,"Grid Sample",$$,$$)
print (sysgui)'grid'(100,20,20,160,120,$9040$,8,3,3)
result$=sendmsg(sysgui,100,68,150/4,$$); rem row height
result$=sendmsg(sysgui,100,57,0,$$); rem turn off color change highlighting
dim grid$:tmpl(sysgui,ind=1); rem DIMension grid information block
grid$=sendmsg(sysgui,100,20,0,$$); rem initialize grid information block
grid.style=1; rem set cell style to raised button
counter=0
for col=0 to 2
result$=sendmsg(sysgui,100,36,col,chr(51)); rem column width
259
for row=0 to 2
rem Instruct SENDMSG(54) which cell to manipulate
grid.col=col,grid.row=row
rem Set display buffer to loop counter.
grid.buf$=str(counter)
tf$=sendmsg(sysgui,100,54,0,grid$)
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:
sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(50,50,200,150,"Grid Sample",$$,$$)
print (sysgui)'grid'(100,20,20,160,120,$9040$,8,3,3)
result$=sendmsg(sysgui,100,68,150/4,$$); rem row height
result$=sendmsg(sysgui,100,57,0,$$); rem turn off color change highlighting
dim grid$:tmpl(sysgui,ind=1); rem DIMension grid information block
grid$=sendmsg(sysgui,100,20,0,$$); rem initialize grid information block
counter=0
for col=0 to 2
result$=sendmsg(sysgui,100,36,col,chr(51)); rem column width
for row=0 to 2
rem Instruct SENDMSG(54) which cell to manipulate
grid.col=col,grid.row=row
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$
tf$=sendmsg(sysgui,100,54,0,grid$)
counter=counter+1
next row
next col
escape
Description
This function sets the default background color for the grid.
Parameter Description
sysgui SYSGUI channel.
260
id Grid control ID.
55 SENDMSG() function number.
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.
Description
This function sets the default text color for the grid.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
56 SENDMSG() function number.
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.
The return value is a null string.
Example
The following example displays a grid with green text:
sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(50,50,200,150,"Grid Sample",$$,$$)
print (sysgui)'grid'(100,20,20,160,120,$9040$,3,3,3)
result$=sendmsg(sysgui,100,56,0,$00ff00$); rem set text to green
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,57,0,$$)
for row=0 to 2
tf$=sendmsg(sysgui,100,48,row,$$)
for col=0 to 2
let tf$=sendmsg(sysgui,100,22,col,str(col))
next col
261
next row
escape
Description
This function sets the method in which cells are highlighted.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
57 SENDMSG() function number.
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.
Description
This function controls the display of horizontal lines between rows in the body of the grid.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
58 SENDMSG() function number.
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.
Description
This function controls how the columns in the grid control will scroll. The return value is a null string.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
262
59 SENDMSG() function number.
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.
Description
This function sets the interspace, which along with the row height, makes up the total height of the cells in a grid.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
60 SENDMSG() function number.
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.
Description
This function sets the color of the separation lines within the specified grid control.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
61 SENDMSG() function number.
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.
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 ).
Parameter Description
263
sysgui SYSGUI channel.
id Grid control ID.
62 SENDMSG() function number.
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.
Description
This function toggles the margin mode to apply the margin setting to both margins or just the left margin.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
63 SENDMSG() function number.
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.
Description
This function sets the mouse capture mode for main grids.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
64 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
65 SENDMSG() function number.
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.
Description
This function sets the number of columns in the specified grid control.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
66 SENDMSG() function number.
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:
sysgui=unt; open (sysgui)"X0"
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
67 SENDMSG() function number.
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:
sysgui=unt; open (sysgui)"X0"
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
Description
This function adjusts the height of main (not heading) grid rows.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
68 SENDMSG() function number.
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"
print (sysgui)'window'(50,50,200,150,"Grid Sample",$$,$$)
print (sysgui)'grid'(100,20,20,160,120,$9040$,3,3,3)
result$=sendmsg(sysgui,100,68,50,$$); rem row height
for col=0 to 2
result$=sendmsg(sysgui,100,36,col,chr(51)); rem column width
next col
escape
See also Set Interspace – SENDMSG() Function 60.
Description
This function sets the vertical scroll bar thumb update mode.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
69 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
70 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
71 SENDMSG() function number.
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.
Description
This function controls the display of vertical lines between columns in the body of the grid.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
72 SENDMSG() function number.
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.
Description
This function uses the grid's current font to calculate the width of the specified string and returns it in binary format.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
73 SENDMSG() function number.
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.
Description
This function controls whether the user will be able to resize the width of columns in the grid with a mouse.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
74 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
75 SENDMSG() function number.
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.
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
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
76 SENDMSG() function number.
0 Always zero.
$$ Always null.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
77 SENDMSG() function number.
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.
Description
This function sets the cursor used for grid drag-and-drop operations.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
78 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
79 SENDMSG() function number.
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.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
80 SENDMSG() function number.
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.
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.
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:
sysgui=unt; open (sysgui)"X0"
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)
result$=sendmsg(sysgui,100,68,12,$$)
datarec_desc$="cdnumber:c(6*=10):SHOW=1 LABEL=Number:,"+
: "title:c(50*=10):SHOW=1 LENGTH=50 LABEL=Title:"
dim datarec$:datarec_desc$
sel_chan=unt; select (sel_chan)datarec$ from "datagrid.dat"
tf$=sendmsg(sysgui,100,80,sel_chan,datarec_desc$)
273
escape
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
81 SENDMSG() function number.
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
SENDMSG() Function 26.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
82 SENDMSG() function number.
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
83 SENDMSG() function number.
style Default cell style.
$$ Always null.
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 style for each column can be changed by
using the STYLE attribute with SENDMSG() Function 80.
The return value is a null string.
The style parameter values are identical to the values used in the style field of the grid information block:
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$:
sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(0,20,390,120,"",$00000082$,$ff$)
print (sysgui)'grid'(100,20,20,360,84,$8842$,3,3,5,15,101)
result$=sendmsg(sysgui,100,68,12,$$)
datarec_desc$="cdnumber:c(6*=10):SHOW=1 LABEL=Number:,"+
: "title:c(50*=10):SHOW=1 LENGTH=50 LABEL=Title STYLE=0:"
dim datarec$:datarec_desc$
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
84 SENDMSG() function number.
alignment Default text alignment.
$$ Always null.
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 - 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 return value is a null string.
The alignment parameter values are identical to the values used in the alignment field of the grid information block:
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.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
85 SENDMSG() function number.
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.
The return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success, $00$ indicates
failure.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
86 SENDMSG() function number.
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$
Description
This function sets the values in one or more contiguous cells with one command.
Parameter Description
sysgui SYSGUI channel.
id Grid control ID.
87 SENDMSG() function number.
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:
sysgui=unt; open (sysgui)"X0"
print (sysgui)'window'(10,50,380,90,"Grid Example",$$)
277
print (sysgui)'grid'(100,10,10,360,75,$8042$,3,2,2,20,101)
result$=sendmsg(sysgui,101,87,0,"First"+$0A$+"Second")
escape
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
20 SENDMSG() function number.
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")
Description
This function returns the text of a specified status bar segment.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
21 SENDMSG() function number.
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.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
22 SENDMSG() function number.
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.
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.
Description
This function returns a templated string that contains the bounding rectangle within client coordinates of the status bar.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
23 SENDMSG() function number.
segment_index Index of segment to retrieve the length from. If this value is greater than the number of segments, an
invalid parameter error will be generated.
$$ 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.
Description
This function returns a three-byte formatted string that contains the borders of the segments within the status bar.
279
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
24 SENDMSG() function number.
int Always zero.
$$ Always null.
Description
This function sets the minimum height of the status bar and returns a null string.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
25 SENDMSG() function number.
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.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
26 SENDMSG() function number.
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.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
27 SENDMSG() function number.
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.
Description
This function returns the INPUTE control title text, minus the mask characters.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
20 SENDMSG() function number.
0 Always zero.
string$ Always null.
281
Description
This function sets the INPUTE control title text.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
21 SENDMSG() function number.
0 Always zero.
title$ INPUTE control title text.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
22 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function sets the INPUTE control's mask.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
23 SENDMSG() function number.
0 Always zero.
mask$ INPUTE control mask.
Description
This function returns the INPUTE control's caret position.
Parameter Description
sysgui Valid SYSGUI channel.
282
id Object ID.
24 SENDMSG() function number.
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.
Description
This function sets the INPUTE control's caret position.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
25 SENDMSG() function number.
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.
Description
This function returns a one-byte string that contains the INPUTE control's pad character.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
26 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function sets the INPUTE control's pad character.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
283
27 SENDMSG() function number.
character INPUTE control pad character.
$$ Always null.
Description
This function returns the INPUTE control's restore string. The returned string contains the mask.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
28 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function sets the INPUTE control's restore string.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
29 SENDMSG() function number.
0 Always zero.
restore$ Restore string.
Description
This function sets the left margin of the INPUTE control's first character.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
30 SENDMSG() function number.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
31 SENDMSG() function number.
color Text color specified as DEC($00$+$RRGGBB$), where $RRGGBB$ defines the RGB value.
$$ Always null.
Description
This function sets the INPUTE control's background color.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
32 SENDMSG() function number.
color Background color specified as DEC($00$+$RRGGBB$), where $RRGGBB$ defines the RGB value.
$$ Always null.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
33 SENDMSG() function number.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
34 SENDMSG() function number.
length Length of the INPUTE string.
$$ Always null.
Description
This function returns the INPUTE control's last error.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
35 SENDMSG() function number.
0 Always zero.
$$ Always null.
The returned string can be used with the DEC() function to determine the error.
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$.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
36 SENDMSG() function number.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
37 SENDMSG() function number.
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.
Description
This function returns the title text of the INPUTN control, minus the mask characters.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
20 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function sets the title text of the INPUTN control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
21 SENDMSG() function number.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
22 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function sets the output mask of the INPUTN control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
23 SENDMSG() function number.
0 Always zero.
omask$ INTPUTN control output mask.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
24 SENDMSG() function number.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
25 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function returns the output mask, which is the restore string of the INPUTN control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
26 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function sets the left margin of the INPUTN control's first character.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
27 SENDMSG() function number.
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.
289
Description
This function sets the text color of the INPUTN control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
28 SENDMSG() function number.
color Text color, specified as DEC($00$+$RRGGBB$), where $RRGGBB$ defines the RGB value.
$$ Always null.
Description
This function sets the background color of the INPUTN control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
29 SENDMSG() function number.
color Background color, specified as DEC($00$+$RRGGBB$), where $RRGGBB$ defines the RGB
value.
$$ Always null.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
26 SENDMSG() function number.
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.
Description
This function sets the restore string of the INPUTN control.
Parameter Description
290
sysgui Valid SYSGUI channel.
id Object ID.
31 SENDMSG() function number.
0 Always zero.
restore$ Restore string.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
32 SENDMSG() function number.
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.
Description
This function sets the character entry mode of the INPUTN control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
33 SENDMSG() function number.
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$.
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)
292
20 SENDMSG() function number.
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)
Description
This function returns the bounding rectangle of a tab on the control. A null string is returned if the function fails.
Parameter Description
sysgui A valid SYSGUI channel.
id Object ID.
21 SENDMSG() function number.
tabidx% An integer value used to identify a particular tab or tab location within the tab control.
$$ Always null.
Description
This function returns the number of tab rows in the control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
22 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function sets the width and height of each tab on a fixed-width tab control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
23 SENDMSG() function number.
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)
Description
This function sets the amount of padding space around the icon and label of each tab.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
24 SENDMSG() function number.
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.
Description
This function removes all tabs from the control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
25 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function removes a tab from the control. The programmer is responsible for removing controls associated with tabs.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
26 SENDMSG() function number.
tabidx% Tab to be removed.
294
$$ Always null.
Description
This function returns tab information.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
27 SENDMSG() function number.
tabidx% Zero-based tab index.
$$ Always null.
If the operation fails, a null string is returned.
Description
This function returns the index of the tab that currently has focus.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
29 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function returns the ID of the image list used by the control.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
30 SENDMSG() function number.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
31 SENDMSG() function number.
0 Always zero.
$$ Always null.
Description
This function performs a hit test of a given point. The point value is specified in pixels.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
32 SENDMSG() function number.
0 Always zero.
pt$ Four-byte string representing the hit point, as described using the following template:
x:i(2),y:i(2)
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%.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
33 SENDMSG() function number.
tabidx% Location in which to insert the tab.
tabdes$ 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.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
34 SENDMSG() function number.
0 Identifies the tab to be selected.
$$ Always null.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
35 SENDMSG() function number.
imagelist_id Image list ID.
$$ Always null.
Description
This function sets tab attributes.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
36 SENDMSG() function number.
tabidx% Identifies the tab for which to set attributes.
tabdes$ 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.
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.
Description
This function causes a selection change notice received by a selected tab item (identified by tabidx%) to be ignored.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
37 SENDMSG() function number.
tabidx% Tab item for which to ignore the selection change notice.
$00$ Always $00$
Description
This function causes a selection change notice received by a selected tab item (identified by tabidx%) to be processed.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
37 SENDMSG() function number.
tabidx% Tab item for which to process the selection change notice.
$01$ Always $01$
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
38 SENDMSG() function number.
0 Always 0.
$$ Always null.
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.
Parameter Description
sysgui Valid SYSGUI channel.
id Object ID.
39 SENDMSG() function number.
tabidx% Tab index.
$$ Always null.
Index
.
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
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
Defining in GUIBuilder ............................................................................................................. 78
Event Mask Property Setting ....................................................................................................... 226
Events
SYSGUI ................................................................................................................................. 143
Exiting ResBuilder........................................................................................................................ 176
External Code
Importing into GUIBuilder ........................................................................................................ 81
External Editor
Using in GUIBuilder ................................................................................................................. 82
F
302
G
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
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
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
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
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
Defining in GUIBuilder ............................................................................................................. 80
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
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
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
313
Windows and Dialogs Defined in ResCompiler ........................................................................... 194
Word Wrap, Preventing Property Setting..................................................................................... 233
Word Wrap, Setting Property Setting........................................................................................... 238
314