ClarifyCRM® eFrontOffice 11.

User Interface Editor Guide

Part Number. M30060-00E11050000

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

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

 Contents

About This Guide

Audience for This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
How to Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Organization of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
What’s New In This Document . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 1 The CeFO User Interface

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
How the CeFO User Interface Works . . . . . . . . . . . . . . . . . . . . . 22
Applications and Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Baseline and Custom Form Versions. . . . . . . . . . . . . . . . . . . 24
Contextual Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
How Contextual Objects Work. . . . . . . . . . . . . . . . . . . . . 25
Form Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Simple Form with Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Multipane Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Comparison of Simple and Multipane Forms . . . . . . . . . . . 29
Extended Contextual Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
How the User Interface Is Displayed . . . . . . . . . . . . . . . . . . . . . 31
Making Form Changes Available to Users . . . . . . . . . . . . . . 32

Contents 3
 Customizing a CeFO Application . . . . . . . . . . . . . . . . . . . . . . . . 32
Customizing with the UI Editor . . . . . . . . . . . . . . . . . . . . . . 32
Customizing the CeFO Web Client . . . . . . . . . . . . . . . . . . . . 33
Customizing with the Data Dictionary Editor. . . . . . . . . . . 33
Customizing with the ddcomp Utility . . . . . . . . . . . . . . . . . 34
Customizing with ClearBasic . . . . . . . . . . . . . . . . . . . . . . . . . 34
Customizing with Policies and Customers . . . . . . . . . . . . . 34
Customizing a Mobile Implementation . . . . . . . . . . . . . . . . 34
Recommended Flow for Customization. . . . . . . . . . . . . . . . 35

Chapter 2 Getting Started

Starting the User Interface Editor . . . . . . . . . . . . . . . . . . . . . . . . 38
Starting the UI Editor in ClearBasic Mode . . . . . . . . . . . . . . 39
Opening a Form to Customize. . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Using the Form Select Filter Criteria . . . . . . . . . . . . . . . . . . . 41
Searching by Form ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
The User Interface Editor Window . . . . . . . . . . . . . . . . . . . . . . . 43
Previewing a Form in the UI Editor . . . . . . . . . . . . . . . . . . . 45
Viewing Control Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Saving the Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Using the Toolbars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Using the Standard Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Using the Form EditorToolbar . . . . . . . . . . . . . . . . . . . . . . . . 50
Using the Toolbox Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Examples of Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Context-Sensitive Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Correcting Mistakes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Setting Up the Display Grid Layout . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 3 Working with Forms

About Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Parent and Child Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
About Resource Configurations . . . . . . . . . . . . . . . . . . . . . . . . . 61
CeFO Baseline Resource Configuration . . . . . . . . . . . . . . . . 61
Users and Resource Configurations . . . . . . . . . . . . . . . . . . . 61
Defining a Resource Configuration. . . . . . . . . . . . . . . . . . . . . . . 62
Adding Forms to a Resource Configuration . . . . . . . . . . . . 63
Specifying a Form as Pre-Loaded . . . . . . . . . . . . . . . . . . . . . 68
Removing a Form from a Resource Configuration . . . . . . . 69
Adding Users to a Resource Configuration . . . . . . . . . . . . . 70
Exporting Resource Configurations . . . . . . . . . . . . . . . . . . . . . . 71
Modifying Existing Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Saving a Custom Version of a Baseline Form . . . . . . . . . . . 74

4 Contents
 Creating Child Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Exporting and Importing Forms . . . . . . . . . . . . . . . . . . . . . . . . . 75
Creating a New Parent Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Form Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Adding an Item to a Context-Sensitive Menu . . . . . . . . . . . . . . 80
CeFO-Supplied Customizations . . . . . . . . . . . . . . . . . . . . . . . . . 81
Form License Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Template Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Chapter 4 Layout and Arranging Controls

Selecting Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Selecting Several Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Selection Order Determines Reference Control . . . . . . . . . . 85
Cancelling the Selection of Controls . . . . . . . . . . . . . . . . . . . 85
Moving Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Resizing Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Resizing Controls Using a Reference Control . . . . . . . . . . . 87
Deleting Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Copying and Pasting Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Cautions for Copying and Pasting. . . . . . . . . . . . . . . . . . . . . 89
Aligning Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Spacing Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Resizing the Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Recommended Form Sizing . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Viewing the Properties Window . . . . . . . . . . . . . . . . . . . . . . . . . 93
Changing the Value of a Property . . . . . . . . . . . . . . . . . . . . . . . . 95

Chapter 5 Working with Controls

Types of Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Adding Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Common Properties of Controls . . . . . . . . . . . . . . . . . . . . . . . . . 99
Using the Name and Control ID Properties . . . . . . . . . . . . 101
Control Names on Existing Forms. . . . . . . . . . . . . . . . . . . . 101
Naming Conventions for Controls. . . . . . . . . . . . . . . . . . . . 102
Reserved Names for Controls. . . . . . . . . . . . . . . . . . . . . . . . 102
Control ID Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Changing the Tab Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Adding Context-Sensitive Menus for Controls . . . . . . . . . . . . 106
Adding New Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Modifying Existing Items . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Handling Menu Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Contents 5
 Chapter 6 Display Controls
The ActiveX Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Sharing ActiveX Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
ActiveX Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
The Animation Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Animation Control Properties . . . . . . . . . . . . . . . . . . . . . . . 113
The Bitmap Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Bitmap Control Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 114
The Graph Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Specifying Graph Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Graph Appearance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Graph Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
The Group Box Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Group Box Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
The Label Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Using HyperLinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Label Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
The Line Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Line Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
The Progress Bar Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Progress Bar Control Properties. . . . . . . . . . . . . . . . . . . . . . 125

Chapter 7 Navigation and Action Controls

The Button Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Using Command Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Assigning Mnemonics . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Using Form Init Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Using Frame Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Dismissing a Child Form . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Close/Done Buttons for Child Forms . . . . . . . . . . . . . . . . . 135
Displaying Pictures in Buttons. . . . . . . . . . . . . . . . . . . . . . . 137
Reserved Button Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Button Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
The Tab Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Shown/Hidden Tab Titles . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Tab Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Planning for Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Designing the Tab Layout. . . . . . . . . . . . . . . . . . . . . . . . 142
Creating Child Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Adding Tab Controls to the Parent Form . . . . . . . . . . . 143
Adjusting the Ordering of Tabs . . . . . . . . . . . . . . . . . . . 146
Setting the Default Tab . . . . . . . . . . . . . . . . . . . . . . . . . . 147

6 Contents
 Tab Controls for Multipane Forms . . . . . . . . . . . . . . . . . . . 147
Tab Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
The Treeview Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Keyboard Navigation with the Treeview Control. . . . . . . 151
Treeview Control Properties. . . . . . . . . . . . . . . . . . . . . . . . . 151

Chapter 8 Input Controls

The Check Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Check Box Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
The Option Button Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Values Passed from Option Selected . . . . . . . . . . . . . . . . . . 156
Grouping Option Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Adding Option Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Option Button Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
The Text Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Text Box Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Currency Text Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Date/Time Text Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Mask Edit Text Box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Entering Default Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Text Box Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Using the Format Property . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Using the Input Mask Property . . . . . . . . . . . . . . . . . . . . . . 165
The Multiline Text Box Control . . . . . . . . . . . . . . . . . . . . . . . . . 167
Types of Multiline Text Boxes . . . . . . . . . . . . . . . . . . . . . . . 167
Entering Default Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Using Find and Replace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Multiline Text Box Properties . . . . . . . . . . . . . . . . . . . . . . . . 169
The List Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Using List Boxes in Query Forms. . . . . . . . . . . . . . . . . . . . . 172
List Box Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
The Dropdown List Box Control . . . . . . . . . . . . . . . . . . . . . . . . 175
Types of Dropdown List Boxes . . . . . . . . . . . . . . . . . . . . . . 176
CeFO List Dropdown List Boxes . . . . . . . . . . . . . . . . . . . . . 176
Static List Dropdown List Boxes . . . . . . . . . . . . . . . . . . . . . 177
User Data Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Pop-up List Dropdown List Boxes. . . . . . . . . . . . . . . . . . . . 180
Dropdown List Box Properties . . . . . . . . . . . . . . . . . . . . . . . 184
The Dropdown Combo Box Control . . . . . . . . . . . . . . . . . . . . . 185
Dropdown Combo Box Properties. . . . . . . . . . . . . . . . . . . . 186
Using the List Items Property . . . . . . . . . . . . . . . . . . . . . 187

Contents 7
 The Slider Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Keyboard Navigation with the Slider Control. . . . . . . . . . 189
Slider Control Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
The Updown Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Keyboard Navigation with the Updown Control . . . . . . . 190
Using the Updown to Rotate Through Tabs . . . . . . . . . . . 191
Updown Control Properties . . . . . . . . . . . . . . . . . . . . . . . . . 191

Chapter 9 The Grid and CBX Controls

The Grid Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Simple Grids and Multigrids . . . . . . . . . . . . . . . . . . . . . . . . 194
Grids and Contextual Objects . . . . . . . . . . . . . . . . . . . . . . . 195
Grids and Contextual Object Types . . . . . . . . . . . . . . . . . . 196
Grids and Column Links. . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Adding a Grid to a Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Using the Grid Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Modifying Grid Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Making the Grid Editable . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Creating a Multigrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Grid Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Column Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
The Select CBX Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Creating a Select Form: Example . . . . . . . . . . . . . . . . . . . . . 214
Editing Filter Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Supporting Ad Hoc Queries. . . . . . . . . . . . . . . . . . . . . . . . . 221
MultiCBX Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Select CBX Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Chapter 10 Understanding Contextual Objects

About Contextual Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Source and Destination Contextual Objects. . . . . . . . . . . . 226
Designing Contextual Objects . . . . . . . . . . . . . . . . . . . . . . . 227
Adding Contextual Objects to a Form . . . . . . . . . . . . . . . . . . . 229
Contextual Object Names . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Database Object Types and Sub Types . . . . . . . . . . . . . . . . 233
Sub Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
User-Defined Contextual Object Types . . . . . . . . . . . . . . . 235
Contextual Objects and Controls. . . . . . . . . . . . . . . . . . . . . . . . 235
Propagating Contextual Objects . . . . . . . . . . . . . . . . . . . . . . . . 238
Child Forms and Extended Contextual Objects . . . . . . . . 239
Propagating Contextual Objects . . . . . . . . . . . . . . . . . . . . . 239

8 Contents
Chapter 11 Using the Extended Contextual Object Editor
About Extended Contextual Objects . . . . . . . . . . . . . . . . . . . . . 244
The Extended Contextual Objects Window . . . . . . . . . . . . . . . 244
Extended Contextual Objects and Contextual Objects . . . 245
Listing Methods and Properties . . . . . . . . . . . . . . . . . . . . . . 247
Displaying Key/Value Pairs. . . . . . . . . . . . . . . . . . . . . . . . . 247
Navigating the Extended Contextual Object Treeview . . 248
Context Menus in the Extended Contextual Object Window
250
Copy Special and Paste Special . . . . . . . . . . . . . . . . . . . . . . 250
Configuring Extended Contextual Objects. . . . . . . . . . . . . . . . 251
Adding Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Adding Methods to Extended Contextual Objects . . . 253
Using Method Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Types of Method Templates . . . . . . . . . . . . . . . . . . . . . . . . . 255
Steps to Add and Use Templates . . . . . . . . . . . . . . . . . . . . . 255

Chapter 12 Using the Action Editor

About Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Action Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
How Actions Work with CeFO Applications . . . . . . . . . . . . . 260
Using Actions to Invoke Stored Procedures. . . . . . . . . . . . 261
Asynchronous Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Synchronous Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Actions on Button Controls. . . . . . . . . . . . . . . . . . . . . . . . . . 262
How Actions Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Interpretation of Command-Line Syntax . . . . . . . . . . . . . . 263
Execution of the Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Defining an Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Platform Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Input and Output Arguments . . . . . . . . . . . . . . . . . . . . . . . 265
Writing the Script or Interface . . . . . . . . . . . . . . . . . . . . . . . 267
What Are Form Init Actions? . . . . . . . . . . . . . . . . . . . . . . . . 268
How Form Init Actions Are Defined . . . . . . . . . . . . . . . 269
Adding a Button to Invoke an Action . . . . . . . . . . . . . . . . . . . . 269
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Defining the Stored Procedure . . . . . . . . . . . . . . . . . . . . . . . 272
Adding the Command Button Action . . . . . . . . . . . . . . . . . 273

Contents 9
 Chapter 13 Using the Code Editor
About the Code Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Code Editor Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
The Code Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Text Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Auto-Indenting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Automatic Statement Completion . . . . . . . . . . . . . . . . . . . . 280
Creating Form Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Creating Global Code Modules . . . . . . . . . . . . . . . . . . . . . . . . . 283

Chapter 14 Merging Different Form Versions

Specifying the Forms to Merge . . . . . . . . . . . . . . . . . . . . . . . . . 286
Generating a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Previewing the Difference Report . . . . . . . . . . . . . . . . . . . . 290
Merging the Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Resolving Merge Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Deleting a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Appendix A Examples
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Customizing the WIPbin and Queue Windows . . . . . . . . . . . 296
Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Find Caller Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Adding Custom Find Caller Fields to the Database . . . . . 300
Adding Find Caller Filters to the New Case Window . . . 301
Using the Find Caller Customize Feature . . . . . . . . . . . . . 302
Adding Multi-Field Filtering to a Form . . . . . . . . . . . . . . . . . . 302
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Only Some Forms Can Use Multi-Field Filtering . . . . 303
Multi-Field Filtering vs. Select CBX. . . . . . . . . . . . . . . . 303
Database Objects Used by NEW_FILTER. . . . . . . . . . . 303
Limitations on Multi-Field Filtering . . . . . . . . . . . . . . . 304
How Multi-Field Select Operates. . . . . . . . . . . . . . . . . . . . . 304
Adding Fields to the NEW_FILTER Contextual Object . . 305
Adding Filters to a Select Window . . . . . . . . . . . . . . . . . . . 305
Adding Filters to the Select Contracts Window . . . . . . . . 306
Adding Fields to a “Sort by” List. . . . . . . . . . . . . . . . . . . . . 309
Changing the Method of Part Selection for Cases . . . . . . . . . 310
Customizing the New Case Window . . . . . . . . . . . . . . . . . 313
Specifying Required Filters for Part Selection . . . . . . . . . . 316

10 Contents
 Adding SQL Controls to the Query Windows. . . . . . . . . . . . . 317
How the SQL Feature Works . . . . . . . . . . . . . . . . . . . . . . . . 317
Implementing the SQL Feature . . . . . . . . . . . . . . . . . . . . . . 318
Forms That Use the SQL Feature . . . . . . . . . . . . . . . . . . . . . 318
Adding SQL Controls to Query Windows . . . . . . . . . . . . . 319
Adding KeyPhrases to Part Classes. . . . . . . . . . . . . . . . . . . . . . 324
Adding The KeyPhrase Button to the
Part Class Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Adding the KeyPhrase Button to the
KeyPhrase Selection Window . . . . . . . . . . . . . . . . . . . . . . 327
Passing Login Information to Shell Scripts . . . . . . . . . . . . . . . 329
Creating a Multigrid/MultiCBX Form . . . . . . . . . . . . . . . . . . . 329
Step 1: Create the Form and Add the Controls . . . . . . . . . 330
Step 2: Define a Resource Configuration . . . . . . . . . . . . . . 332
Step 3: Define Contextual Objects . . . . . . . . . . . . . . . . . . . . 332
Step 4: Define Control Properties. . . . . . . . . . . . . . . . . . . . . 335
Step 5: Define extended contextual object properties . . . . 339
Step 6: Add ClearBasic Code to the Form. . . . . . . . . . . . . . 343
Step 7: Test the Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Appendix B Customization Guidelines

Adjusting the Form Size for Smaller Monitors . . . . . . . . . . . . 348
Saving the New Form Size . . . . . . . . . . . . . . . . . . . . . . . . . . 348
User Preferences and Form Size. . . . . . . . . . . . . . . . . . . . . . 348
User Version Numbering for Forms . . . . . . . . . . . . . . . . . . . . . 348
Guidelines for CeFO Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Grid Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Form Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Label Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Text Box and Multiline Text Box Controls . . . . . . . . . . . . . 351
List Box Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Command Button Controls. . . . . . . . . . . . . . . . . . . . . . . . . . 351
Tab Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Tab Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Default Control Dimensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Contents 11
 Appendix C User Interface Editor Commands and Windows
User Interface Editor Commands . . . . . . . . . . . . . . . . . . . . . . . 356
File Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Edit Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Format Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Window Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
User Interface Editor Windows . . . . . . . . . . . . . . . . . . . . . . . . . 361
Button Actions Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Code Editor Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Code Editor Settings Window . . . . . . . . . . . . . . . . . . . . . . . 365
Format Tab Field Definitions . . . . . . . . . . . . . . . . . . . . . 365
Options Tab Field Definitions . . . . . . . . . . . . . . . . . . . . 366
Control Inspector Window . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Edit Form Contextual Objects Window . . . . . . . . . . . . . . . 367
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Edit Form Extended Contextual Objects Window . . . . . . 369
Left Pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Right Pane Field Definitions. . . . . . . . . . . . . . . . . . . . . . 371
Export to File Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Extended Contextual Object Template Window. . . . . . . . 372
Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Field Definitions, Templates Tab . . . . . . . . . . . . . . . . . . 374
Field Definitions, Edit Template Tab. . . . . . . . . . . . . . . 374
Form Merge Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Form Select Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Grid Settings Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Import Dat File Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Insert OLE Control Window . . . . . . . . . . . . . . . . . . . . . . . . 381
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Membership Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Object Type Selection Window . . . . . . . . . . . . . . . . . . . . . . 383
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

12 Contents
 Preview Differences Options Window . . . . . . . . . . . . . . . . 384
Propagate Contextual Objects Window . . . . . . . . . . . . . . . 386
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Propagate Contextual Objects Window (Multi). . . . . . . . . 387
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Properties Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Resource Config <title> Window. . . . . . . . . . . . . . . . . . . . . 389
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Save Form As Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Select Resource Config Window . . . . . . . . . . . . . . . . . . . . . 392
Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Index
14 Contents
 About This Guide

This guide provides information about the User Interface Editor (UI Editor).
The UI Editor is CeFO’s tool for customizing the user interface in
ClarifyCRM eFrontOffice (CeFO) applications. This guide accompanies the
CeFO software release.

The UI Editor can be purchased with a separate option for ClearBasic, which
gives you the ability to write custom code behind your forms, as well as
additional capabilities within the UI Editor itself.

Some of the tasks described in this guide can only be performed with
ClearBasic installed.

NOTE: This version of the User Interface Editor is for Windows 95 and Windows
NT only.

Audience for This Guide

The primary audience for this guide consists of database designers and user
interface developers who implement functions and user interface screen
changes in the CeFO application.

15
Related Documentation

Related Documentation
In addition to this guide, you can refer to the following manuals in the CeFO
documentation set for information about customizing a CeFO application:
• Setting Up Your Data
• Data Dictionary Editor Online Help
• Data Dictionary Guide
• Managing Email
• ClearBasic Object Reference
• ClearBasic Programmer’s Guide
• ClearBasic Customization Guide
• ClearBasic Control Reference
• ClearSales Implementation Guide
For detailed information about any of the applications you have installed in
addition to the User Interface Editor, see the guide(s) for that application.

How to Use This Guide

This guide provides you with the information needed to use the User
Interface Editor application. Use the table of contents and index as
navigation aids into the guide.

If you are customizing portions of the CeFO application that use the new
form layout (ClearSales), you should also read the SFA White Paper that
describes some of the high-level concepts and architecture used for extended
contextual objects. This document is included on the Documentation
CD-ROM.

If you are reading this document as a PDF file online, the cross-references to
other pages in the guide are hypertext links (although cross-references to
other books in the CeFO documentation set are not hypertext links). Use the
hypertext links to move from one page to an associated page for additional
information.

16 About This Guide

 How to Use This Guide

Organization of this Guide

This guide contains the following sections:
• Chapter 1, The CeFO User Interface provides a high-level overview of the
User Interface Editor and how forms are used in the CeFO application.
• Chapter 2, Getting Started describes how to start the User Interface Editor
application and presents an overview of the windows, toolbars, and
toolboxes in the User Interface Editor.
• Chapter 3, Working with Forms describes how to create forms, and how to
associate a group of users to a set of form versions (also called a resource
configuration).
• Chapter 4, Layout and Arranging Controls describes how to select, move,
and align objects in a form. It also describes how to assign and update
control properties.
• Chapter 5, Working with Controls provides an overview of the control
types available and how to add controls to a form. It also lists the
properties common to all controls.
• Chapter 6, Display Controls describes controls that are used mainly to
display information to the user, but do not require the user to interact or
enter data. This includes labels, animations, bitmaps, and progress bars,
as well as ActiveX controls, which invoke a third party utility or
application.
• Chapter 7, Navigation and Action Controls describes the button, tab, and
treeview controls.
• Chapter 8, Input Controls describes controls that accept or assist in user
selection and input, including various text box and list box controls.
• Chapter 9, The Grid and CBX Controls describes controls used to generate
a list of selectable records, or for use in user-defined filtering operations.
• Chapter 10, Understanding Contextual Objects provides an overview of
contextual objects and how to link them to forms and controls.
• Chapter 11, Using the Extended Contextual Object Editor describes how to
work with extended contextual objects in the UI Editor, including
methods and properties. Includes a description of each method type, and
the key/value pairs used with each.
• Chapter 12, Using the Action Editor describes how to use a command
button to invoke an operating system command, a program, or a stored
procedure.

About This Guide 17

What’s New In This Document

• Chapter 13, Using the Code Editor describes how to use the integrated
Code Editor window to write ClearBasic code.
• Chapter 14, Merging Different Form Versions describes how to combine the
layout and properties of two different versions of a form.
• The Appendixes contain supplemental information:
– Appendix A, Examples
– Appendix B, Customization Guidelines
– Appendix C, User Interface Editor Commands and Windows

What’s New In This Document

In this revision of the User Interface Editor Guide, the following new features
have been documented:
• Support for use of multiple contextual objects on a single grid or CBX
control through extended contextual objects
• Enhancements to the UI Editor interface to support extended contextual
objects
• A general overview of the baseline form layouts that have been updated
to utilize the new extended contextual object model
• Description of how to set up grid and CBX controls to use multiple
contextual objects
• New properties of existing controls

Conventions
Notes and picture icons are used in this guide to highlight additional
aspects, to notify you of situations where special care is required, or to point
you to additional sources of information.

NOTE: Provides additional information.

IMPORTANT: Highlights key considerations to keep in mind.

18 About This Guide

 Conventions

CAUTION: Highlights situations that could potentially damage data or cause

system failure.

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

Typographical Conventions
Monospace is used for the following:
• Programming elements such as code fragments, objects, methods,
parameters, command-line syntax, field and table names, HTML tags,
executable programs, and scripts
• System elements such as file names, directories, paths, or URLS
• Common operating system commands or utilities such as the MS-DOS
dir command
• Windows paths use backslashes as in
C:\Clarify\clarify.exe
• UNIX pathnames use front slashes. For example,
/usr/tech2/salesdev/test/scripts (absolute pathname)
or $SALESDEV/scripts (same path using an environment variable).

Monospace bold is used in two cases:

• Commands typed by the user are bold to distinguish them from system
prompts, for example “type y when prompted to continue.”
• In examples where detailed system prompts or screen output is shown,
along with the user responses needed to continue, the user responses are
in bold.
ftp> binary
200 Type set to I.
ftp> put readme.txt
200 PORT command successful.
150 binary data connection for readme.txt <etc.>

About This Guide 19

Conventions

Optional and substituted information is represented as follows:

• Monospace italic is used for placeholders, which are terms you replace
with values specific to your site. For example:
Clarify_home_directory\dbadmin\dbupgrade\
• Straight brackets signal options in command-line syntax []. For example:
uiedit [-cb]

20 About This Guide

Chapter 1

The CeFO User Interface

In This Chapter
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
How the CeFO User Interface Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Form Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Extended Contextual Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
How the User Interface Is Displayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Customizing a CeFO Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

21
Overview

Overview
This chapter provides a quick get-started overview of the CeFO user
interface and how it works. A few underlying concepts are also presented
from the standpoint of a user interface designer who needs to customize the
user interface.

How the CeFO User Interface Works

The user interface in CeFO applications enables users to read and write
information from a client to the CeFO database on a server. Figure 1
illustrates client interaction with the CeFO server.

Figure 1 Client interaction with the CeFO server

Enter information in the application

Save information to the database

Access information from the database

Display information in the application
CeFO Client CeFO
Application Server DB

Applications and Data

The CeFO user interface contains several applications to organize the data
contained within CeFO. Each CeFO application focuses on a different aspect
of the CeFO workflow. For example, ClearSales manages the sales process,
whereas ClearQuality handles defect reports and enhancement requests.

Each application has a set of primary workflow objects. For example, you
would use ClearSales to track Opportunities and Leads, but you would use
ClearSupport to track Cases (support calls).

22 Chapter 1
 How the CeFO User Interface Works

In addition, there are other related data objects such as Customers, Sites,
Contacts, Accounts, and Employees. These items appear in all CeFO
applications as objects related to the primary workflow object. Thus, a user
reviewing a primary workflow object such as a Case can see the Site and
Contact data related to that Case in an integrated fashion.

Generally, each workflow object and data object is represented by a

corresponding database object (table) in the CeFO database.

Forms
In a CeFO application, a window or dialog box is called a form. Each form is
organized around a focus object such as a Case or Part Request. Some forms
display additional information from other related objects. Figure 2 shows
forms in a CeFO application.

Figure 2 Forms in a CeFO application

Contact form

Part Request
Query form

The CeFO User Interface 23

How the CeFO User Interface Works

Controls
The visual elements on a form are called controls. Text boxes, dropdown lists,
and command buttons are all examples of controls.

Baseline and Custom Form Versions

The CeFO application contains a complete set of forms that can be modified
in the UI Editor. The forms provided by CeFO are called the baseline forms.
Each form is identified by a unique number, the Form ID.

When you modify a baseline form, it is saved as a new version of the

original baseline form with the same Form ID but a different user version.
The modified baseline form is called a custom form. You can modify or
delete custom forms, but not the baseline forms.

Contextual Objects
When users work with any form in a CeFO application, they view and enter
information on their local client machine. To temporarily hold the data on
the client, CeFO applications use spaces in local memory called contextual
objects.

Each form in a CeFO application is associated with a set of contextual

objects. These contextual objects store all of the data associated with a form.

Contextual objects can contain data from several sources. For example, a
contextual object can be directly associated with a CeFO database table, or it
can store a list of records selected from a table. Contextual objects can also
store other values such as calculations. Typically, one of the contextual
objects associated with a form represents the CeFO database table or view
that corresponds to the focus object of the form itself. Figure 3 illustrates
contextual objects.

24 Chapter 1
 Form Layouts

Figure 3 Contextual objects

Application Contextual objects Database object

Example: New Case form table_case

Case
CObject

Data temporarily stored Data written to DB upon Save

You can also use contextual objects to store calculations, such as the number
of records selected. This value can be passed to a label control for the end
user to see.

How Contextual Objects Work

CeFO applications use contextual objects as follows:
• When an application loads a form, it reads information from the database
and uses contextual objects to temporarily hold this information in local
memory.
• When the user enters new information in a form, the application
temporarily holds the information in contextual objects. When the user
decides to save data permanently, the application transfers the data from
the appropriate contextual objects to the database.

Form Layouts
There are two main types of CeFO forms:
• A simple form or single-table form shows data from one database object
or view, which is the focus object of the form. Tabs may allow data from
related objects to appear in child windows on the parent form.
• A multipane form also shows data from a focus object that corresponds to
a database table. However, the grid and CBX controls can dynamically
switch among contextual objects based on user selections, without
having to load a different grid.

The CeFO User Interface 25

Form Layouts

Simple Form with Tabs

Figure 4 shows an example of a simple form with tabs for child forms.

Figure 4 Form with tabs

Focus object:
Contact

Tab
controls

User clicks a tab

to bring
associated child
form to the front.

Child form: Site

The Site is a related object.

Multipane Forms
A different form layout and organization applies to CeFO baseline forms
that use the multigrid and multiCBX controls. These controls can store and
switch between displays of multiple contextual objects.

The multipane forms look similar to the one shown in Figure 5.

26 Chapter 1
 Form Layouts

Figure 5 Multipane form example

Focus 1
object

3 List (Grid)
Related
objects 2
5 4 Action
View

Detail

The end user proceeds from general to specific details by selecting

successively finer levels of detail. The subsequent form areas display
information related to what the user has selected. Figure 6 illustrates the
layout for a multipane form.

Figure 6 Multipane form layout

Focus object 1

Related objects List (Grid)

2 3
5 4 Action

View

6 Detail

The CeFO User Interface 27

Form Layouts

The user navigates the areas of the form, which are as follows:
1. The focus object represents the data object which is the focus of the form.
2. The user clicks on a related object to view more information. A list of
related records displays in the grid.
3. The user clicks a record in the grid.
4. The user chooses an action to apply to the record. The appropriate
information appears in the Detail area.
5. Optionally, the user can select from the View list to display different
portions of the selected record.
6. The Detail pane displays different information depending on user
selections made in the other window areas.

Table 1 lists the areas of a multipane-style form.

Table 1 Areas of a multipane-style form

Focus Object This data object is the focus of the form. When the form is
opened, a particular record appears. Examples of focus
objects (each with an accompanying form) are Account, Site,
Account, Contract, Campaign, Lead, Forecast, Opportunity,
and Territory.
Related Objects A treeview shows objects that are related to the focus object.
For example, in the Account form, a particular customer
record would appear as the focus object, and the related
objects would show a listing for Sites, Contacts, Forecasts,
Quotes, and so on. When the user clicks a related object, the
selection grid lists all records of that type that are related to
the focus object.
Grid This grid is associated with multiple contextual objects, which
allows different data to appear depending on which related
object the user selects. When the user clicks an item in the
grid, the Action menu is populated.
Action The menu items change depending on earlier user selections.
The detail information changes depending on which action
the user selects.
View List Displays different portions of the selected record. This
provides the same benefit as using the Tab buttons on other
forms.
Detail This shows the greatest level of detail for the selected record.

28 Chapter 1
 Extended Contextual Objects

Comparison of Simple and Multipane Forms

Figure 7 illustrates the comparison between simple and multipane baseline
form layouts:
• On the simple form the user can display a related object by using the tabs
(2), but if there is a one-to-many relationship between the focus object
and the related object, the grid has to be separately defined for each child
form, and the details presented either in the grid or in an additional form
normally accessed by an Open button.
• On the multipane form, the multigrid control switches to display a list of
selected records, based on which related object is selected in the treeview.
An Action menu (sometimes multiple menus) further directs the search.
Based on selections in 2, 3, and 4, the details appear in panel 5.

Figure 7 Comparing the layout of simple and multipane forms

1 Focus object 1
tabs
Select related 3
2 object to view 2
treeview 4
5 Related 5
object details

Multigrid
Action to selection:
perform with related object
related object records

Extended Contextual Objects

Extended contextual objects represent a “metadata-driven” approach by
giving users the ability to define additional key/value pairs that can then be
used by ClearBasic code to implement functions for that extended
contextual object. The extended contextual objects extend the capabilities of
regular contextual objects by allowing users to associate multiple sets of data
with a single grid or CBX control.

The CeFO User Interface 29

Extended Contextual Objects

While a regular contextual object only has attributes corresponding to the

original data type, an extended contextual object can have both methods and
properties associated. Also, you cannot edit contextual objects other than to
change their names, but you can edit various attributes of extended
contextual objects.

Every time you create a contextual object for a form, an extended contextual
object is automatically created to hold the extra information. Figure 8
illustrates extended contextual objects.

Figure 8 Extended contextual objects

Extended contextual object Database object

Focus object
Example: Account table_case

Multigrid CObj

Methods Properties

Extended contextual objects have the following associated items:

• Properties are used to store grid settings such as whether the grid is
multi-select, as well as grid column and CBX settings. As a general rule,
if an extended contextual object uses properties, the property list items
correspond to fields in a table within the CeFO database.
• Methods are used to store user-defined attributes of the extended
contextual object. You can modify the ClearBasic code behind the form to
use the method information for customized form behavior.
• Key/value pairs represent data to be associated with either methods or
properties, and are processed by ClearBasic code.

30 Chapter 1
 How the User Interface Is Displayed

How the User Interface Is Displayed

Controls, their associated contextual objects, and the links between them are
all stored in the database as part of a form specification. Figure 9 shows how
information is displayed in forms.

Figure 9 How information in forms is displayed

Objects in the database contain specifications for:

The layout of the form
The controls in the form
The links to contextual objects

CeFO
database
Server

Form Specifications

Client
Form (created from specifications)

When you open a form in the CeFO application, the application reads the
form specification from the database (or the cached local file that mirrors the
database information) and uses this information to draw the form on your
client.

The CeFO User Interface 31

Customizing a CeFO Application

Making Form Changes Available to Users

Since form specifications are stored in the database, any changes you make
to a form can be made available. However, merely changing a form
specification does not make those changes instantly available. You must first
add your version of the form specification to a resource configuration, and
ensure that the end users who need the new form are members of that
resource configuration. For more information about resource configurations,
see About Resource Configurations on page 61.

Customizing a CeFO Application

CeFO provides the following tools for customizing CeFO applications:
• User Interface Editor (uiedit)
• Data Dictionary Editor (ddedit)
• Data Dictionary Compare utility (ddcomp)
• ClearBasic (licensed separately)
• Policies and Customers (part of the CeFO client application)

NOTE: This manual describes only the User Interface Editor. This version of the
User Interface Editor is for Windows 95 and Windows NT only.

Customizing with the UI Editor

Use the User Interface Editor to log in to the CeFO database and perform the
following customizations:
• Create new forms and modify the layout of existing forms.
• Add controls to forms to allow additional information to be entered/
displayed.
• Define form buttons that invoke non-CeFO commands or applications.

32 Chapter 1
 Customizing a CeFO Application

• Maintain different versions of the same form for different

CeFO users.
• Merge your custom forms when you receive new versions of the forms
from CeFO.
• Export your custom forms to a data file, allowing you to import these
forms to other databases.
• Add actions or ClearBasic code to implement the behavior of a form.
Application code may need to be modified for new or existing controls.

Customizing the CeFO Web Client

You cannot use the User Interface Editor to directly customize the user
interface in the CeFO Web client application. However, the CeFO Web client
gets its form information from the CeFO database the same way the CeFO
LAN/WAN client does. Therefore, you can create a custom set of forms for
use with the Web client, assign them to a special resource configuration, and
add your Web users to that resource configuration.

Customizing with the Data Dictionary Editor

Use the Data Dictionary Editor to log in to the CeFO database and perform
the following tasks:
• Add fields to the CeFO data dictionary to allow the storage of additional
information.
• Apply a customized version of the data dictionary schema to the CeFO
database.

If you need to add a new table or perform other database schema changes
not supported through the Data Dictionary Editor, you can edit the
object.sch schema file and use the Apply Changes command in the Data
Dictionary Editor to apply the changes.

The CeFO User Interface 33

Customizing a CeFO Application

Customizing with the ddcomp Utility

The ddcomp utility is a command-line tool for performing certain database
modifications not supported by other CeFO tools. Generally, ddcomp is used
conjunction with other database modification tools such as the Data
Dictionary Editor.

Customizing with ClearBasic

ClearBasic is a programming language that you use to customize CeFO
applications. Using ClearBasic, you can do the following:
• Write code to access the database.
• Define the driving logic behind your new forms and controls.
• Customize the logic on CeFO forms.
• Create interfaces to other applications.

Customizing with Policies and Customers

Policies and Customers is a CeFO application that you use to modify business
rules, user-defined pop-up list values, queues, employee information, and
privilege classes.

Customizing a Mobile Implementation

Traveler is the mobile component of the CeFO client. It requires special
alterations to the database and a careful analysis of the data distribution
rules used to share data with the offline clients. The data distribution
requirements, plus the data latency inherent in a connection that is only
intermittent between the offline users and the main CeFO database, can
potentially affect your business rules and workflow processes.

The offline client runs off a local copy of the CeFO database that has been
re-created using Microsoft Access. Because Access does not support certain
database features such as stored procedures, some UI customizations might
need to be implemented differently for the offline clients.

See the guide titled Customizing ClarifyCRM Applications for more

information.

34 Chapter 1
 Customizing a CeFO Application

Recommended Flow for Customization

If you are using both the Data Dictionary Editor and the User Interface
Editor to customize CeFO applications, you should perform your
customization on a development database before applying the changes to
your production database.

Customize the forms in the development database, and verify that they
operate correctly. After you have tested these forms, you can export each
form to a data file, which you can then import into your production
database.

To customize CeFO applications

1. Start the UI Editor and open your development database.
2. Select and open the form to customize.
3. Customize your form.
4. Save the form as a specific user version in your CeFO database.
5. Assign the form version to one or more user resource configurations.
6. Add ClearBasic code (requires ClearBasic), or Button Actions.
7. Export the form from the UI Editor.
8. Import the form into your test database and test thoroughly.
9. Export the final version of the form and import into your production
database.

The CeFO User Interface 35

Customizing a CeFO Application

36 Chapter 1
Chapter 2

Getting Started

In This Chapter
Starting the User Interface Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Opening a Form to Customize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
The User Interface Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Using the Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Context-Sensitive Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Correcting Mistakes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Setting Up the Display Grid Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57

37
Starting the User Interface Editor

Starting the User Interface Editor

With the User Interface Editor, you can modify the form specifications
contained in a database. As a result, when you launch the User Interface
Editor, you must log in to the database whose forms you want to modify.

There are two ways to start the UI Editor:

• ClearBasic mode is available only if you have purchased a ClearBasic
license from CeFO. Certain functions in the UI Editor are enabled only in
ClearBasic mode.
• If you start the UI Editor without ClearBasic, you will be able to modify
existing forms but not create new ones.

To start the User Interface Editor

1. Double-click the User Interface Editor icon.
The login dialog box appears, as shown in Figure 10.

Figure 10 UI Editor login

2. Enter your login information.

a. Type your CeFO user name and password in the fields for User Name
and Password.
Your password is case-sensitive. To protect your password, the
characters that you type are displayed as asterisks.
b. Type the name of your database server and the database name in the
Server and Database fields.

38 Chapter 2
 Starting the User Interface Editor

3. Click the Login button.

The Form Select window appears as shown in Figure 11. See Opening a
Form to Customize on page 40 for instructions on selecting the desired
form to work with.

If you are using the User Interface Editor to edit forms with double-byte
characters, you must add the DOUBLE_BYTE setting to the application’s
clarify.env file. The DOUBLE_BYTE setting tells the application to be
aware of double-byte characters. To use this setting, you would add the
following line to the clarify.env file of the User Interface Editor:
DOUBLE_BYTE=TRUE

Starting the UI Editor in ClearBasic Mode

If you purchased ClearBasic, you can start the User Interface Editor with the
-cb option to access the features needed for programming in ClearBasic. The
general format for starting the User Interface Editor from the command line
is as follows:
uiedit -cb

If you want to use User-defined Data Types (UDTs), you must also specify
the UDT file name on the command line:
uiedit -cb -c=UDTs_file

You can create a Windows shortcut for the application. Right-click on the
executable file and choose Create Shortcut. Then right-click on the new
shortcut and choose Properties. In the shortcut properties window, select the
shortcut tab and add any appropriate options to the target edit box.

If you are starting from the MS-DOS prompt, specify the appropriate options
in the command line.

IMPORTANT: You must have ClearBasic installed on your system before using the
User Interface Editor with the -cb option. Unexpected results may occur if you
edit forms without ClearBasic installed.

More Information: For more information about ClearBasic and User-defined Data
Types, see the ClearBasic Programmer’s Guide and the ClearBasic Customization
Guide.

Getting Started 39
Opening a Form to Customize

Opening a Form to Customize

You must open a form in order to perform any customizations. When you
first log in to the UI Editor, the Form Select window appears as shown in
Figure 11.

Figure 11 Form Select window

Search string

Use Filter Criteria and

click Find to list forms by
Title, Name, ID, User
Version, or Description

To open a form in the UI Editor

1. Enter your filtering criteria and click List to see a list of forms.
2. Select the form to customize, and click Open.
3. The selected form appears as shown in Figure 12.

40 Chapter 2
 Opening a Form to Customize

Using the Form Select Filter Criteria

Use the Filter area on the Form Select window to search for forms matching
a specified search string. The four controls from left to right are:
• A dropdown list box labeled “List forms whose” that specifies the
criterion.
• A dropdown list box next to it that lets you specify Starts With, Ends
With, or Contains.
If the “List forms whose” selection has Form ID selected, the second
dropdown list shows the following choices:
= (equals)
> (greater than)
< (less than)
>= (greater than or equal to)
<= (less than or equal to)
!= (does not equal)
• A text field that allows you to enter a string to search on.
• A List button that executes the search and shows the resulting list of
forms.

You can filter the forms list using one of the criteria listed in Table 2.

Table 2 Form Select filter criteria

Criterion Description
Title The title of the form as it appears on the window title bar seen by
the end user.
Name The name of the form as shown in the Name field of the Properties
window for the form.
ID The unique Window ID (also called Form ID) used to identify
every form.
User Version The user-specified version number of a custom form. All custom
forms derived from the same baseline form will have the same
Form ID but different User Versions.
Description A one-line description of the form. To edit, open the Form > Save
As dialog, edit the text, and replace the form when saving.

Getting Started 41
Opening a Form to Customize

You can specify a list of all forms where the criterion starts with, ends with,
or contains the phrase entered in the last text box to the right.

Searching by Form ID
To search for a CeFO baseline form by form ID, use the information in
Table 3 as a guideline.

Table 3 CeFO baseline form ID numbers

CeFO Release Version Form ID Number Range CeFO Application

Functionality
CeFO 200-299 Admin
300-399 ClearQuality
400-499 ClearSupport
500-599 ClearLogistics
600-699 Product Manager
700-799 Policies & Customers
800-899 Queries
900-999 Data Dictionary Editor
1005, 1007-7999 Customer custom
windows
8200-8299 Task Manager
8400-8499 ECO/Depot Repair
8500-8599 Account Manager
9000-9099 Billing Manager (obsolete)
9100-9299 ClearContracts
9500-9599, ClearCallCenter
11000-11500
9600-9799 ClearSales
10000-10099 User Interface Editor

42 Chapter 2
 The User Interface Editor Window

Table 3 CeFO baseline form ID numbers (Continued)

CeFO Release Version Form ID Number Range CeFO Application

Functionality
CeFO 8 11600-11649 Lead
11650-11699 Account
11850-11899 Territory
11950-11979 Campaign/Lead Source
12000-12100 My Clarify
13000-13100 Opportunity
14000-14010 Action Items
20000-20050 Generic Lookup

The User Interface Editor Window

The User Interface Editor displays a form in a form edit window, as shown
in Figure 12. Within this window, you can add new controls, change the
properties of existing controls, and move controls.

Getting Started 43
The User Interface Editor Window

Figure 12 UI Editor form open for editing

Standard toolbar
gives you access
to common
file commands.

Title displays form

name, form ID, and
version number.

Grid lines help

you place objects.

Form Editor Toolbar

Toolbox

Status bar displays object coordinates

and object dimensions.

The pattern of dots represents the grid guidelines. These grid markings do
not show in Preview mode or in the CeFO application. The title bar, shown
in Figure 13, displays the form title, form ID, CeFO version, and user
version, in that order.

44 Chapter 2
 The User Interface Editor Window

Figure 13 Title bar for UI Editor form edit window

Form
ID
CeFO User version
Form title version

Previewing a Form in the UI Editor

After editing a form, you can display the form in a form preview window as
shown in Figure 14, to see how it looks in the CeFO application
environment. To preview a form, open the form and do one of the following:
• Click the Play Form icon in the Standard toolbar.
• Choose Edit > Play Form from the menu bar at the top.
• Right-click the form and choose Play Form from the context menu.

Getting Started 45
The User Interface Editor Window

Figure 14 Previewing a form in the UI Editor

Click Play Click the Close

Form to view box to exit from
your form in preview mode.
preview mode.

In preview mode,
you can view the
form as it appears
in a CeFO
application.

Note that the form behavior is not identical to what the end user would see,
because the preview cannot show any contextual data. You cannot use the
preview to test form workflow (buttons that lead to other forms), nor will
the Search or Save commands actually execute queries or save data to the
database.

Viewing Control Properties

The visual features of a form are called controls. This includes not only
command buttons and data entry fields, but also graphical elements such as
lines and group boxes.

Each control has a set of associated properties. The types of properties

available depend on the type of control. To view and edit the properties of a
control, right-click the control and select Properties. See Figure 15 for an
example.

46 Chapter 2
 The User Interface Editor Window

Figure 15 Example of a control’s properties window

Right-click a control.
1

The Properties
3 window is displayed
2 for the selected
control.
Choose Properties
from the context
menu.

Note that the dropdown selection list for the Properties window lists all the
controls on that particular form. To edit the Properties for a different control
or the form itself (called “TheForm”), select it from the list and edit the
control properties.

Saving the Form

Any changes you make to the form or to any control properties for the form
are stored in memory until you save. If you try to close the form with
unsaved changes, the UI Editor prompts you to save.

Getting Started 47
Using the Toolbars

Using the Toolbars

The toolbars in the UI Editor are named Standard, Form Editor, and Toolbox.
By default, they display along the top, side, or bottom borders of the UI
Editor window. To make a toolbar free-floating, click and drag it by the
handle on the left-hand side of the toolbar, as shown in Figure 16.

Figure 16 Moving a toolbar

To make a free-floating toolbar fixed, click and drag it to one

of the borders of the UI Editor window.

Click and drag a toolbar by

the left-hand border to make
it free-floating Free-floating toolbar

Fixed toolbar

You can also use the left-hand border to slide a toolbar back and forth along
the UI Editor window border.

Using the Standard Toolbar

The Standard toolbar (shown in Figure 17) gives you easy access to
frequently used commands.

48 Chapter 2
 Using the Toolbars

Figure 17 Standard toolbar

Show/ View
Open Cut Redo hide Control About
Paste code
form toolbox inspector

New Save Play Compile View

form form Copy form form
Undo Properties Print

Table 4 lists the Standard toolbar icons and commands.

Table 4 Standard toolbar icons and commands

Icon Name Description

New form (ClearBasic mode only) Creates a new form.

Open form Displays the Form Select window from which you
can select a form to open.
Save form Saves the form in the database.

Cut Copies selected controls to the clipboard and deletes

them from the form.
Copy Copies the selected controls to the clipboard.

Paste Places objects in the Clipboard onto the form.

Undo Cancels the previous command.

Redo Repeats the previous command.

Play form Displays the form as it would appear in a CeFO

application.
Show/hide toolbox Displays or hides the Toolbox toolbar.

Properties Lets you view and change the properties of a

selected control.

Getting Started 49
Using the Toolbars

Table 4 Standard toolbar icons and commands (Continued)

Icon Name Description

Control Inspector Use the Control Inspector to change the tab ordering
between controls.
Print Prints the form to the selected printer.

About Displays the version number of the User Interface

Editor and the name of the database that it is
accessing.
Compile (ClearBasic mode only) Compiles the code in the
current code editor window.
View code (ClearBasic mode only) View the code associated
with the current form.
View form (ClearBasic mode only) View the form associated
with the current code window.

Using the Form EditorToolbar

The Form Editor toolbar, shown in Figure 18, contains buttons for placing
and aligning objects. The tools displayed in the layout toolbar also appear as
commands in the User Interface Editor Format menu.

Figure 18 Form Editor toolbar

Space Same
Show/ Align Align Align evenly
middles height
hide lefts rights across Same Button
grid width Same actions
marks Align Center size
tops Align Align vertically
centers Space
bottoms Contextual
evenly
Center down objects
horizontally

50 Chapter 2
 Using the Toolbars

Table 5 lists the Form Editor toolbar icons and commands.

Table 5 Form Editor toolbar icons and commands

Icon Name Description

Grid marking Displays or hides the grid markings.

Align tops Aligns selected controls along their top edges.

Align middles Aligns selected controls along their middle.

Align bottoms Aligns selected controls along their bottom edges.

Align lefts Aligns selected controls along their left edges.

Align centers Aligns selected controls along their centers.

Align rights Aligns selected controls along their right edges.

Center vertically Centers selected controls vertically in the form.

Center horizontally Centers selected controls horizontally in the form.

Space evenly across Spaces selected controls with equal distance

horizontally.
Space evenly down Spaces selected controls with equal distance
vertically.
Same width Resizes selected controls to have the same width.
The control that is selected last (green handles) will
be used as the standard.
Same height Resizes selected controls to have the same height.

Same size Resizes selected controls to have the same width

and height.
Contextual objects Use this command to add or delete contextual
objects associated with a form.
Button actions Associates a command-line function or stored
procedure with a button.

Getting Started 51
Using the Toolbars

For more information about arranging objects, see Layout and Arranging
Controls on page 83.

Using the Toolbox Toolbar

Use the Toolbox, shown in Figure 19, to add controls to the form.

Figure 19 Toolbox toolbar

Select Label Multiline Combo Progress Select

Tab
text Box bar Slider CBX
Grid
box List Updown
Group Check
Bitmap box box box Graph
Dropdown Line Animation Treeview ActiveX
list box

Command
button Option
button

Table 6 lists the Toolbox toolbar icons and commands.

Table 6 Toolbox icons and commands

Icon Name Description

Select Lets you select controls on the form.

Bitmap Lets you add pictures to a form.

Label Lets you write static text.

52 Chapter 2
 Using the Toolbars

Table 6 Toolbox icons and commands (Continued)

Icon Name Description

Text box Creates a text box control object.

Multiline text box Creates a multiline text box control object.

Group box Creates a group box control object.

Command button Creates a button control object.

Check box Creates a check box control object.

Option button Creates an option button control object.

Dropdown List box Creates a pull-down menu control object that

combines features of a text box and a list box.
List box (ClearBasic mode only) Creates a list box control
object.
Dropdown Creates a pull-down menu control object.
Combo box
Line Draws a line.

Grid (ClearBasic mode only) Creates a grid control

(sometimes called a field array or custom list). Note
that the grid control is distinct from the grid
markings used to align the controls on a form.
Tab Creates a tab control.

Animation Inserts an AVI animation file.

UpDown Creates a control for incrementing and decrementing

the value of a field.
Progress bar Displays the progress of a lengthy operation.

Getting Started 53
Using the Toolbars

Table 6 Toolbox icons and commands (Continued)

Icon Name Description

Treeview Displays a hierarchical list of nodes.

Slider Creates a slider control for selecting a value from a

specific range.
Graph Displays statistical data graphically.

Select CBX (ClearBasic mode only) Lets you add a control which
provides database filtering functionality to a grid.
ActiveX Use this command to add ActiveX controls to the
form.

Some examples of controls are shown in the next section. For more
information about using controls, see Working with Controls on page 97.

54 Chapter 2
 Using the Toolbars

Examples of Controls
Figure 20 Examples of controls
Check box Option button

Text box

Label

List box

Grid

Dropdown list box Command button Select CBX

Tabs

Treeview (ClearSales)

Getting Started 55
Context-Sensitive Menus

Context-Sensitive Menus
Use the left mouse button for standard selection tasks. Use the right mouse
button to display the context-sensitive menu (also called the shortcut menu)
associated with an item. This menu displays the common commands that
you can apply to the item, as shown in Figure 21.

Figure 21 Shortcut menu commands

Table 7 describes the various functions available when using the mouse with
keys on the keyboard.
Table 7 Mouse clicks with Shift and Control keys

Mouse Action Used With... Action Produced

Left-click no modifier If no controls are selected, this selects a control. If user clicks a control
that is already selected within a group of controls, that control
becomes the active control, while the other controls remain selected.
Shift or Control Adds or removes controls from a group of selected controls.
Shift + Control Same as left-click.
Right-click no modifier Shows context-sensitive shortcut menu for control or for the form,
depending on where the cursor is when you right-click
Drag no modifier Selects all controls inside or partially inside the selection rectangle.
Cancels the selection of all other controls.
Shift or Control Adds or removes controls from the current selection that are either
inside or partially inside the selection rectangle. Retains any other
selected controls.
Shift + Control Selects backgroundobject.
Double-click any modifier Property window appears, if double-clicking on a form or control.

56 Chapter 2
 Correcting Mistakes

Correcting Mistakes
You can cancel the effects of most commands by choosing Edit > Undo.
There is an almost unlimited undo memory in the User Interface Editor; you
can undo almost all the operations you performed, in reverse order, by
repeatedly using the Undo command.

You cannot, however, undo the following commands:

• Merge
• Form Delete
• Save or Save As
• Print
• Import or Export

Setting Up the Display Grid Layout

Grid markings are a pattern of dots that serve as a guide to help you align
controls when editing a form. These markings are visible only in the User
Interface Editor, not in the CeFO applications. A snap-to-grid option
automatically aligns controls to the nearest grid mark. Figure 22 shows the
same form with and without grid markings.

Figure 22 Grid markings

Grid markings shown in edit form Preview form does not show grid

You can choose your own spacing for the grid.

NOTE: Grid markings are not the same as the grid control, which is used on a form
to show a list of selected records to the end user.

Getting Started 57
Setting Up the Display Grid Layout

To set the grid options

1. Choose View > Grid Settings.
The Grid Settings window appears, as shown in Figure 23.
2. Make your selections and click OK.

Figure 23 The Grid Settings window

Select Show Grid

to display the grid
marks. Draw guidelines at the
specified distances from
Select Snap to Grid the form borders.
to have objects (measured in pixels)
automatically aligned
to a grid.
Enter the space in pixels, between
grid marks here.

Grid settings are saved only as long as the form is open.

58 Chapter 2
Chapter 3

Working with Forms

In This Chapter
About Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
About Resource Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Defining a Resource Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Exporting Resource Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Modifying Existing Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Creating Child Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Exporting and Importing Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Creating a New Parent Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Form Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Adding an Item to a Context-Sensitive Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
CeFO-Supplied Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

59
About Forms

About Forms
Forms are the building blocks of your user interface.

With the User Interface Editor, you can save many different versions of the
same form. A resource configuration associates a group of users to a set of
form versions.

You can also export saved versions of a form to a data file. This makes the
form portable between databases. For example, you might set up custom
forms in a test database and verify that the customization works properly. To
bring the forms from the test database to the production database, you can
export the forms to data files and then import the data files into your
production database.

Parent and Child Forms

A parent form is a stand-alone form. You need ClearBasic to create a new
parent form that is not saved as a user version of a previous baseline form.
Creating a new parent form can involve significant efforts for designing,
coding, and database modification. See Creating a New Parent Form on
page 77 for an outline of the tasks necessary to create a new parent form.

A child form is accessed either through a tab control (to show on parent
form) or a frame button control (to show in a separate window). You do not
need ClearBasic to create a new child form.

You can modify existing CeFO baseline parent and child forms without
ClearBasic.
• For information on creating child forms as tabs, see The Tab Control on
page 139.
• For information on creating child forms that open separately from the
parent form, see Using Frame Buttons on page 133.

60 Chapter 3
 About Resource Configurations

About Resource Configurations

A resource configuration defines a complete set of forms for CeFO
applications. A resource configuration can contain some standard CeFO
forms (referred to as the baseline version) and some customized CeFO forms.
You can use resource configurations to display different versions of the
application forms to different users (for example, a development version or
a German version).

When you customize a form, you specify which resource configuration

contains that form. Because you cannot add forms to the baseline resource
configuration, you must create a different resource configuration and add
your form to it.

CeFO Baseline Resource Configuration

A default resource configuration with baseline forms is shipped with CeFO
applications. You cannot add custom forms to this baseline, or edit the
baseline forms themselves.

The CeFO baseline resource configuration and forms are used for change
control during CeFO upgrades.

Users and Resource Configurations

A resource configuration also defines the list of users who work with this
form set. When a user runs CeFO applications, the forms that appear on
screen are the forms in that user’s resource configuration.

Each user must belong to only one resource configuration. By default, new
employees use the baseline version of forms.

You do not need to create custom versions of every form every time you add
a new resource configuration. If no custom form is available, users who are
members of that resource configuration will see the baseline version of the
form instead.

Working with Forms 61

Defining a Resource Configuration

Defining a Resource Configuration

A default resource configuration with baseline forms is shipped with the
CeFO application. All users use this default resource configuration unless
they are assigned to a new resource configuration.

To define a new resource configuration

1. Start the User Interface Editor application, using your development
database.
2. Choose File > New > New Resource Config.
The Resource Config window appears, as shown in Figure 24.

Figure 24 Creating a new resource

3. In the Configuration Title field, type a name for the new resource
configuration.
4. In the Description field, type a description of the new resource
configuration.
5. Click Add, then click Done.

62 Chapter 3
 Defining a Resource Configuration

6. Add forms and users to this resource configuration.

For more information, see Adding Forms to a Resource Configuration on
page 63 and Adding Users to a Resource Configuration on page 70. These
instructions assume that your development database contains the same
user information as your production database.
7. Export the resource configuration, then import it into your target
database.
This exports all the form information as well as the resource
configuration itself.
8. Verify that the correct users are members of this new resource
configuration, in your production database.

Adding Forms to a Resource Configuration

You must add each form to a resource configuration in order to make the
form available to users.

To add a form to a resource configuration

1. In the UI Editor, choose File > Open > Resource Config...
The Resource Configuration window appears as shown in Figure 25.

Working with Forms 63

Defining a Resource Configuration

Figure 25 Resource Configuration window (no filter applied)

2. Enter filtering information.

This filter allows you to search by Title or Description which Starts With,
Ends With, or Contains a specified search string. Click List to display
your filter results.

Figure 26 Resource Configuration window (filter applied)

3. Select a resource configuration and click Open.

The Resource Config window appears as shown in Figure 27. You must
use the filter information to list the forms you want to add to the resource
configuration you have selected.

64 Chapter 3
 Defining a Resource Configuration

Figure 27 Resource Config window

Search string

Form filter

List button

4. Use the first dropdown list box to select one of the following criteria:
Title - Form title
ID - Form ID, assigned by the UI Editor
User Version - Your versioning of the baseline form
CeFO Version - CeFO-supplied version referencing the CeFO software
release in which this form was introduced
5. Use the second dropdown list box to select the filter operation to
perform.
For all except ID, the search criteria Starts With, Ends With, Contains,
or Not Equal To.
If the “List forms whose” selection has Form ID selected, the second
dropdown list shows the following choices:
= (equals)
> (greater than)
< (less than)
>= (greater than or equal to)
<= (less than or equal to)
!= (does not equal)

Working with Forms 65

Defining a Resource Configuration

6. Enter a search string in the text field and click the List button.
The Database list on the left displays all forms in the database meeting
your filter criteria, as shown in Figure 28. This list includes any
customized versions of forms that you create.

Figure 28 Resource Config: List forms

Database list shows

all forms meeting
filter criteria

7. (Optional) List the custom forms that are already in this resource
configuration.
By default, the Resource Config list on the right shows all forms that are
in the resource configuration, both baseline and custom. Because each
new resource configuration automatically includes all the baseline forms
until they are replaced by custom versions, it is difficult to see which
custom forms are already in the resource configuration unless you select
the Custom option button.
Selecting the Custom option button filters the Resource Config list.

66 Chapter 3
 Defining a Resource Configuration

8. Select a custom form to add to the resource configuration, and click Copy.
You cannot add baseline forms to another resource configuration.
Therefore, the Copy button only activates when you select a custom
version of a form, as shown in Figure 29.
To change the version of a form in the resource configuration, select the
new version from the Database list and click Copy.
The form appears in the Resource Config list on the right.

Figure 29 Adding forms to a resource configuration

Choose Custom to
list only custom
forms in this
resource
configuration.

Forms (and
versions) in
All forms already
the database
associated
are listed here.
with this
resource
configuration
are listed
here.

Select a form and click Copy to add

the form to the resource configuration.

9. Repeat for every form to add to the resource configuration.

10. Click Replace to save changes.
11. Click Done to close the Resource Configuration window.

Working with Forms 67

Defining a Resource Configuration

Specifying a Form as Pre-Loaded

After you add a form version to the resource configuration, you need to
specify when the form is read from the database to the client:
• Pre-loaded forms are read from the database and saved to the local cache
file when the user logs in to the database.
• On-demand forms are read from the database when the user selects a
command or clicks a button to display the form during a session.

After the form is read from the database, the form specifications are stored in
a cache file on the client. If changes are made to the form in the database, the
CeFO application reads the new version of the form to the client:
• During login if the form is pre-loaded
• When the Update Desktop command is selected
To specify a form as preloaded
1. Add the form to the resource configuration as described in To add a form
to a resource configuration on page 63, but do not close the Resource
Configuration window.
2. Select the form from the Resource Config list to the right and click the
Pre-Load button, as shown in Figure 30.

68 Chapter 3
 Defining a Resource Configuration

Figure 30 Specifying a form as pre-loaded

Scroll to the right to see the Preloaded column. An X

appears for every form currently specified as
pre-loaded.

3. Scroll to the right in the Resource Config button to verify the results.
An X appears in the Pre-Load column for every form that is currently
specified as pre-loaded.
4. Click Replace and then Done to save changes and close the Resource
Config window.

Removing a Form from a Resource

Configuration
To remove a form from a resource configuration, select the form to remove
and click Remove, as shown in Figure 31.

Working with Forms 69

Defining a Resource Configuration

Figure 31 Removing a form from a resource configuration

All forms (and

all versions) in
the database
are listed here. All forms
associated
with this
resource
configuration
are listed
here.

Click Remove to remove a form

from the resource configuration.

Adding Users to a Resource Configuration

In order for users to access new forms, make sure that they are members of a
resource configuration containing the new forms.

Each user can be a member of only one resource configuration. Adding a

user to a new resource configuration automatically removes them from their
current resource configuration.

To add or remove users to or from a resource configuration

1. Open the Resource Configuration window for the resource configuration
where you want users added or removed.

• Choose File > Open > Resource Config.

• Enter your filtering criteria and click List.
• Select the desired resource configuration from the list and click
Open.

70 Chapter 3
 Exporting Resource Configurations

2. Click Membership.
The Membership window appears, as shown in Figure 32.

Figure 32 Adding users to a resource configuration

1. Enter your filtering

criteria and click List.

2. Select the users to add

to the resource configuration.

3. Click Copy.

3. Enter your filter selection criteria and click List.

A list of users who match your filtering criteria appears in the list box on
the left side of the window.
4. To add a user, select the user from the list and click Copy. To remove a
user from the resource configuration, select the name from the list on the
right side of the window and click Remove.
Use the Shift or Control key to select multiple users in a contiguous or
noncontiguous fashion, respectively.
5. Click Done when members of this resource configuration have been
added or removed.

Exporting Resource Configurations

When you export a resource configuration, all the customized forms
associated with it are also exported. Therefore, you do not need to
individually export each of the customized forms.

NOTE: Only the forms that are different from the baseline forms are exported when
you export a custom resource configuration.

Working with Forms 71

Exporting Resource Configurations

To export a resource configuration

1. Choose File > Open > Resource Config.
The Resource Configuration window appears, as shown in Figure 33.

Figure 33 Selecting a resource configuration to export

1. Enter your filtering

criteria and click List.

2. Select the resource configuration

from the list and click Export.

2. Enter your filtering criteria and click List.

3. Select the resource configuration and click Export.
The Export to File window appears, as shown in Figure 34.

72 Chapter 3
 Modifying Existing Forms

Figure 34 .Naming the export file

4. Enter the name for the data file and click OK.

Modifying Existing Forms

You can modify any existing form, either a baseline or a user-defined version
of a baseline form. If you modify a baseline form, the UI Editor forces you to
use the Save As command, and specify a user version (the form’s ID number
remains the same as that of the baseline version).

To modify a form
1. Use the Form Select window to open the form.
2. Make your changes.
These changes may include any of the following:
• New controls
• Modification to existing control properties
• New contextual objects
• Changes to the form layout
• Changes to the ClearBasic code associated with the form (requires
ClearBasic installed)
3. Choose File > Save As from the menu.
The Save Form As window (page 74) appears.
4. Specify a User Version and a Description, and click Save.

Working with Forms 73

Modifying Existing Forms

5. Add the form to a resource configuration as described in Adding Forms to

a Resource Configuration on page 63.

Saving a Custom Version of a Baseline Form

After making changes to a form, save the form in the database as a specific
version. If you want to save the form and load it into a different database,
you must export the form as described in Exporting and Importing Forms on
page 75.

More Information: For more information about user version numbering

methodology, see Appendix B, Customization Guidelines.

To save a form:
1. Choose File > Save Form As.
The Save Form As window appears, as shown in Figure 35.

Figure 35 Saving a custom form

2. In the User Version text box, type the version of the form.

NOTE: You cannot overwrite the baseline version of a form.

3. In the Description text box, type a description of the form.

4. Click Save.
5. Add the custom form to a resource configuration, as described in Adding
Forms to a Resource Configuration on page 63.

74 Chapter 3
 Creating Child Forms

Creating Child Forms

You can create a child form in two ways, either by using Frames or by using
Tabs:
• For information on creating child forms as tabs, see The Tab Control on
page 139.
• For information on creating child forms that open separately from the
parent form, see Using Frame Buttons on page 133.

You must add the child form to a user-defined resource configuration in

order to use it.

Exporting and Importing Forms

To copy a new form from your development database to your production
database, you must use the Export and Import function in the UI Editor.
After a version of the form is saved to the database, you must export the
form to a data file so that it can be imported into another database.

To export a form to a data file

1. In the UI Editor, choose File > Open > Form...
The Form Select window appears as shown in Figure 11.
2. Use the filtering function to locate the form if needed.
See Using the Form Select Filter Criteria on page 41 for information on how
to use the filter in the Form Select window.
3. Select the form to export and click Export.
You can also open the form, and then choose File > Export Form. The
Export to File window appears as shown in Figure 36.

Working with Forms 75

Exporting and Importing Forms

Figure 36 Exporting a form to a data file

4. Enter a name for the data file and click Save.

A dialog box prompts you whether to export the user privilege class
information along with the form. Choose Yes or No and continue.

To import a form from a data file

1. Open the UI Editor and connect to the target database.
This is the database into which you want to import the form.
2. Choose File > Import.
The Import Dat File window appears.
3. Select or enter the file name to import and click Open.
A dialog appears informing you if the import was successful.

76 Chapter 3
 Creating a New Parent Form

Creating a New Parent Form

You must have a ClearBasic license in order to create a parent form. Note
that modifying an existing form is not the same thing as creating a new form
without using a CeFO-provided baseline.

IMPORTANT: Creating a new form can be fairly complex, particularly if the form
uses the multigrid or multiCBX control features. You must be familiar with
ClearBasic, the existing CeFO user interface, and with the CeFO data model before
attempting to design and create your own parent forms.

To create a new parent form

1. Open the UI Editor in ClearBasic mode using the -cb option.
2. Select File > New Form from the menu or click the icon.
A new form window appears, as shown in Figure 37, with a new ID
number at the top.

Figure 37 New form

3. Edit the form properties.

At a minimum, the properties you’ll probably want to customize are
Caption, Name, and User Version.

Working with Forms 77

Creating a New Parent Form

4. Add the form controls.

Generally, a form should have the following controls as standard
features:
• A Save or other appropriate action button (if the form allows the user
to commit some sort of action, whether that action be a database
commit or some sort of select operation)
• A Done button to close the form
5. Edit the properties of each control.
6. Preview the form.
7. Save the form, specifying a user version.
8. Add the form to a resource configuration.
You cannot add ClearBasic code until the form has been added to at least
one resource configuration.
9. Add ClearBasic code to the form, and save the code.
At a minimum, you must supply a Form_Load routine.
10. Provide a way for users to access the form.
Add the form from a CeFO application menu, using a ClearBasic global
code module.
11. Test the form in the CeFO application.
Log in to the CeFO client as one of the users for whom the form is
intended, connecting to your development database. Use the Update
Desktop command if needed to re-cache the new form information.
Then, open the form the same way you expect the users to access it, and
test all functionality.

After you are satisfied with the form, you can export the form and import it
into your target or production database. See Exporting and Importing Forms
on page 75.

78 Chapter 3
 Form Properties

Form Properties
Form properties are used to define basic characteristics of the form, such as
versioning, associated context-sensitive help topic, context menu, and
background color. The properties available for the form itself are listed in
Table 8.
Table 8 Form properties

Property Type Property Name Description

Appearance Caption The title that shows in the window title bar for
the end user to see.
BackColor Background color of the form. If left Nil, the
default Windows settings are used.
Data Edit Contextual Clicking on the value portion of this property
Object (the ellipsis button ...) displays the Edit Form
Contextual Objects window. You can add,
rename, or delete the contextual objects
associated with the form.
Misc Name Internal name of the form, displayed in the
Properties window menu, the Control
Inspector window, and used in CB code.
Window ID The unique identifier of this form window.
Version User version of the form.
Baseline Baseline version of the form.
Help topic If you are using context-sensitive Help, this is
the topic the end user will see when invoking
the Help system from this window.
WinHelp topic Online help topic associated with this form.
You can use this to specify a custom help topic.
Context menu Displays a dialog box to define the context
menu to be displayed when the user
right-clicks on the form.
Position (Positioning) Positioning information in pixels for Top,
Bottom, Left, Right, Width, and Height

Working with Forms 79

Adding an Item to a Context-Sensitive Menu

Adding an Item to a Context-Sensitive Menu

Context-sensitive menus appear when the end user right-clicks a particular
form or control.

To add an item to a context-sensitive menu

1. Open the form.
2. If necessary, select the control to which the context menu should apply.
If you do not select a control, your change will apply to the context menu
for the form itself.
3. Open the Properties window and click on the value column for the
Context Menu property.
The Item Properties window appears, as shown in Figure 38.

Figure 38 Item Properties window

80 Chapter 3
 CeFO-Supplied Customizations

4. Add the menu items.

The column properties are as follows:
LabelItem that the user sees on the context menu.
NameName as referenced in ClearBasic code. If you are translating CeFO
into another language, you only need to translate the Label but not the
Name.
Application MenuYou can associate an action from an existing menu
item without having to write any ClearBasic code. Use the syntax
Menu.Item. For example, to allow users to dispatch a case directly from
the Case window, create a context menu item for the Case form with a
Label value of “Dispatch”, and supply an Application Menu value of
Desktop.Dispatch.
FlagFlags are:
Normal - regular menu item
Disabled - grayed on the menu; does not trigger any actions
Hidden - temporarily removes item from the menu. However, you can
use ClearBasic code to control the visibility of the item at runtime.
Separator - entry is a separator bar rather than an active menu choice
5. Click OK when finished to exit the Item Properties window.

CeFO-Supplied Customizations
This section outlines a few areas where CeFO has included some commonly
requested customization options as part of the baseline product.

Form License Dependencies

Your CeFO licensing options can affect the form IDs you use for certain
forms. For example, you use different form IDs for the New Case and Edit
Case forms if you have purchased a Sales Manager license.

Working with Forms 81

CeFO-Supplied Customizations

Template Forms
CeFO has supplied some optional controls (with ClearBasic code behind
them) that you can copy and paste to use on your own forms, even if you
don’t have ClearBasic. These controls are kept on special “template” forms.
The forms themselves are not used in the CeFO application. They are just a
holding place for the controls.

Each template form goes with a particular baseline form. Use only the
controls from the correct template form when modifying the baseline form.
Table 9 lists the CeFO-supplied template forms.

Table 9 CeFO-supplied template forms

Template Associated Baseline Form Template Form Title

Form ID
415 New Case (411 or 775) Additional Feature Options
422 Edit Case (420 or 776) Additional Feature Options
300 New Change Request (337) CR New and Edit Options
Edit Change Request (334)

CAUTION: Do not copy and paste CeFO-supplied controls from other forms onto
your own forms. Some of these controls contain code that will not function properly
on other forms.

82 Chapter 3
Chapter 4

Layout and Arranging Controls

In This Chapter
Selecting Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Moving Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Resizing Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Deleting Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Copying and Pasting Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Aligning Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Spacing Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Resizing the Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Viewing the Properties Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Changing the Value of a Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

83
Selecting Controls

Selecting Controls
When you place a new control on a form, it is automatically selected. You
can select different controls to change their properties or to move them
around the form. You can select one control or many controls.

When you select a control, a bounding box with handles appears around the
control to indicate that it has been selected, as shown in Figure 39.

Figure 39 Handles around a selected control

Handles indicate that

the control has
been selected.

To select a control, click the Select tool in the Object toolbox; then click the
control.

Selecting Several Controls

You can select several controls at a time, or you can add controls to an
existing selection.

To select a group of controls in the same area, click outside the area and drag
diagonally around them, as shown in Figure 40. This selects any control that
is even partially inside the selection rectangle.

Figure 40 Selecting multiple controls

1. Drag diagonally 2. Release the mouse

across controls. button to select.

To add a control to a selection, hold down the Shift key while you click the
new control.

84 Chapter 4
 Selecting Controls

Selection Order Determines Reference

Control
Note that the color of the selection handles indicates the last control selected.
All earlier selections have blue selection handles. The last control has green
handles.

If you are using the Same Height or Same Width commands, all controls in
the selection group will be resized to match the dimensions of the reference
control. When you use the Align commands, all controls are aligned with the
reference control.

Cancelling the Selection of Controls

You may occasionally select controls by accident. You can cancel the
selection of a single control or all controls.
• To cancel the selection of only the selected control, click outside the
control.
• To cancel the selection of all selected controls, click outside the group.
• To cancel the selection of one control in a group of selected controls, hold
down the Shift key while you click the control.

Layout and Arranging Controls 85

Moving Controls

Moving Controls
You can quickly move a control by dragging it, or you can make small
position changes by moving the control with the arrow keys.
• To quickly move a control, select the control and drag it.
• To move a control in small increments, select the control and hold the
Control key while pressing an arrow key.

NOTE: When snap to grid is enabled, objects move to the next grid unit. Turn off
the snap to grid feature to move objects a pixel at a time.

To center a control in the form, use one of the following commands:

• Format > Center in Window > Vertical
• Format > Center in Window > Horizontal
When you move a control, the status bar displays the distance from the
upper-left corner of the control to the upper-left corner of the form, as shown
in Figure 41.

Figure 41 Control offset in the status bar

Control’s offset from the upper-left corner

of the form is displayed here.

Resizing Controls
When you resize a control, the status bar displays the dimensions of the
control, as shown in Figure 42.

Figure 42 Control dimensions in the status bar

Control’s width and height are

displayed here.

Resize a control by dragging the corner of the control, or by changing the

height and width properties of the control.

86 Chapter 4
 Resizing Controls

To resize a control
1. Select the control.
2. Drag one of the handles, as shown in Figure 43.

Figure 43 Resizing a control

Drag the handles of the bounding box

to resize the control.

NOTE: You can also resize a control by selecting it and holding the Shift key while
pressing an arrow key.

Resizing Controls Using a Reference

Control
You can select a group of controls and make them all the same height or
same width as the last control selected. For example, you might have several
mismatched command buttons. Figure 44 shows an example of resizing
controls using a reference control.

Layout and Arranging Controls 87

Deleting Controls

Figure 44 Example: Resizing controls using a reference control

1 2 3 Right-click, 4
select Size,
blue and then
select Same
Height. (You
green can also select
Both.)

These controls are When you select the Button height is now
mismatched. controls, select the the same.
reference control last.
It will have green
selection handles.

5 6 7 8
Right-click Right-click,
again; select select Align,
Size > Same and then
Width. select Lefts.

Button width is Buttons are

now the same. aligned and all the
Now they need to same size.
be aligned.

Deleting Controls
You can easily delete a control or group of controls by selecting the control(s)
and pressing the Delete key.

88 Chapter 4
 Copying and Pasting Controls

Copying and Pasting Controls

You can use the Cut, Copy, and Paste commands to move or duplicate the
control. To access the commands, use the Edit menu, the standard keyboard
shortcuts, or the icon buttons. Table 10 lists Edit commands and shortcuts.
Table 10 Edit commands and shortcuts

Command Keyboard Icon

Shortcut
Cut Ctrl-X

Copy Ctrl-C

Paste Ctrl-V

Paste Special... (none) (none)

Undo Ctrl-Z

Redo Ctrl-Y

Controls remain on the Clipboard until you choose Copy or Cut again.

To copy and paste a control

1. Select the control and copy it to the Clipboard.
Choose Cut to remove the control and paste it elsewhere. Choose Copy to
leave the control unchanged and make a copy elsewhere.
2. Choose where you want to paste the control and choose Paste.
3. Change the source and destination contextual objects.
Change any other properties as necessary.

Cautions for Copying and Pasting

Use caution when pasting controls between different forms. Because each
form uses a different set of contextual objects, copying and pasting a control
to another form may result in source and destination links to nonexistent
contextual objects.

Layout and Arranging Controls 89

Aligning Controls

As a general rule of thumb:

• Do not copy and paste controls from the CeFO baseline forms to other
forms. The only exception to this is the CeFO “template” forms
containing extra optional controls that you can use on your own forms.
• You can copy and paste controls you have created from one form to
another, so long as you remember to edit any ClearBasic code and
properties you have defined.

Aligning Controls
You can align objects along a horizontal line by specifying the top, middle,
or bottom alignment. (See Figure 45.)

Figure 45 Aligning controls horizontally

Top Middle Bottom

You can align objects along a vertical line by specifying the left, center, or
right alignment. (See Figure 46.)

Figure 46 Aligning controls vertically

Left Center Right

Controls are aligned with respect to the last control you select. Different
colored handles appear on the bounding box of the last selected object to
show which is the reference control. (See Figure 47.)

90 Chapter 4
 Spacing Controls

Figure 47 Handles on a bounding box for last selected control

Different colored handles on the bounding box

indicate that this is the last control selected.
Alignment of other controls use this control
as a basis.

NOTE: You can change the reference control even after your group of controls has
been selected. Press the Control key and click the control that you want to be the
new reference.

To align controls
1. Select the controls.
Select the control to which you want the others aligned last.
2. Choose Format > Align, and choose the alignment you want.

Spacing Controls
You can move (distribute) controls so that they have an equal amount of
space between them. You can distribute controls horizontally and vertically,
as shown in Figure 48.

Figure 48 Distributing controls horizontally and vertically

Horizontal distribution Vertical distribution

When you distribute controls horizontally, the left and right objects stay in
place, and the other controls are spaced with equal distance. When
distributing controls vertically, the top and bottom objects stay in place, and
the other controls are spaced with equal distance.

Layout and Arranging Controls 91

Resizing the Form

To distribute controls
1. Select the controls.
You can select the controls in any order.
2. Choose one of the following options:
a. Format > Space Evenly > Down
• Format > Space Evenly > Across

Resizing the Form

To resize a form, move the cursor to the border of the form. Hold down the
mouse button and drag the form to its new size.

Figure 49 Resizing a form

Drag the border of

a form to resize it.

When a user resizes a form in CeFO applications, the size and position of the
form are kept in local memory as part of the user’s display preferences.
These preferences are saved in the user’s local cache file.

If the CeFO application was started with the -save_geom option, these
preferences are saved to the database when the user logs out of the CeFO
application. The user’s display preferences always override any size and
position changes made in the User Interface Editor.

92 Chapter 4
 Viewing the Properties Window

Recommended Form Sizing

With a screen resolution of 800 x 600, itis recommended that you size the
form small enough to avoid having to scroll through the form. Maximum
non-scrolling form sizes are:
• Desktop client: 740 x 440
• Web client: 740 x 320
Localized forms may require a smaller form size. For more information, see
Customization Guidelines on page 347.

Viewing the Properties Window

Each control has a set of associated properties that define the attributes of that
control. You can change the value of a property, but you cannot add or delete
properties. The types of properties available depend on the type of control.

Layout and Arranging Controls 93

Viewing the Properties Window

Figure 50 The Properties window

Click the dropdown

menu to view
properties of other
controls in the form.

Gray = noneditable

Properties are White = editable

automatically
updated when
you change the
value.

To view control properties

1. Open the properties window in one of the following ways:
• Double-click a control.
• Select a control; then choose View > Properties Window.
• Select a control; then click the Properties icon in the Standard
toolbar.
• Right-click a control and choose Properties.
• Select a control; then press Enter.
2. After the Properties window is open, you can view properties of other
controls by:
• Clicking a new control on the form
• Selecting a new control from the dropdown menu in the Properties
window

94 Chapter 4
 Changing the Value of a Property

Changing the Value of a Property

The Properties window (shown in Figure 51) is dynamic, meaning that
when you change the properties of a control, you do not have to close the
Properties window or click an Apply button. When you have entered a new
value, press the Tab key or click another property. The control is updated
with the new information. The changes are committed when you save the
form.

Depending on the property, the value of a property is changed in one of the

following ways:
• Entering the new value
• Selecting the value from a dropdown menu
• Selecting the value from a new window
Figure 51 Changing a property value

A shaded area indicates that the property

is read-only.
Some properties open a window so that
you can define or select values. (The
dots (...) indicate that a window opens.)

Some properties are set by selecting

values from a dropdown menu.

Some properties are set by entering

a new value.

If you accidentally enter the wrong value, use the Undo command to revert
to the previous value.

Layout and Arranging Controls 95

Changing the Value of a Property

Some properties selection lists might change depending on other property

values. For example, when specifying contextual object fields, the fields
available will depend on the contextual object specified.

96 Chapter 4
Chapter 5

Working with Controls

In This Chapter
Types of Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Adding Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Common Properties of Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Changing the Tab Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Adding Context-Sensitive Menus for Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

97
Types of Controls

Types of Controls
This guide groups the controls available through the UI Editor into the
following types, which are explained in the next few chapters:
• Display Controls such as labels or animations are used to display
information to the user, but do not allow direct user interaction.
Although some display controls are dynamically populated, they do not
execute actions within CeFO, and ActiveX controls execute third party
applications within CeFO.
• Navigation and Action Controls assist the user in navigating through a
form, and/or take the user to a different form as a result of an action.
• Input Controls such as text boxes and dropdown list boxes accept user
selection or input for filtering or data entry.
• The Grid and CBX Controls are special controls whose complexity requires
special attention. They handle list and filtering functions for groups of
records.

Adding Controls
All controls are added to a form using the same general steps.

To add a control to a form

1. On the Toolbox toolbar, click the button corresponding to the control you
want to add. (See Figure 52.)

98 Chapter 5
 Common Properties of Controls

Figure 52 Toolbox toolbar

Select Label Combo Progress Select

Multiline Tab
text Box bar Slider CBX
Grid
box List Updown
Group Check
Bitmap box box box Graph
Dropdown Line Animation Treeview
ActiveX
list box

Command
button Option
button

2. Position the cursor where you want the control and click the left mouse
button.

After the control has been placed, you can do the following:
• Resize or move the control.
• Edit the properties of the control.
• Add another control.
The following sections describe the controls and their properties.

Common Properties of Controls

The property sheet for a control contains the complete list of properties
available for that control. Although many of these properties are specific to
the type of control, some properties are common to all controls. Table 11
describes the common control properties.

A few of these, such as Caption, are not available for all controls. For
example, the Select CBX control does not use a caption. However, their use is
similar for all controls that do use them.

Working with Controls 99

Common Properties of Controls

Table 11 Properties common among (most) controls

Category Property Name Description

Appearance Caption Some controls can display a caption or static text that shows
on the CeFO application screen.
Text Used for text boxes and lists, to display initial value that the
end user can edit.
BackColor Changes the background color for controls such as labels.
ForeColor Changes the font color or color of the control.
Behavior Visible Determines whether the end user can see this control in the
CeFO application. Invisible controls can still perform
essential functions on the form. Select No if you don’t want
a control to appear in a form, but don’t want to delete the
control.
Enabled Use to disable a control on the form (for example, a revision
where the underlying code or data structures are not ready
yet). Note a disabled control will not necessarily appear
disabled to the end user (it will not be grayed).
Enabled on Currency Some controls can be disabled after a currency conversion
Convert to prevent user modifications.
Data Edit Contextual Objects Adds, deletes, or changes contextual objects associated with
the form where the control is placed. This does not associate
the control with any particular contextual object.
Source Contextual Object Generally, the source contextual object contains the initial
data for the control, for example a caption or list of data.
Destination Contextual Generally, the destination contextual object stores the
Object current value of the data.
Source Field Name References a particular field in the source contextual object.
Source Data Type The data type of the Source Field Name.

100 Chapter 5
 Common Properties of Controls

Table 11 Properties common among (most) controls (Continued)

Category Property Name Description

Misc Name Unique name of the control used internally by CeFO to
identify the control on the form. This is the reference used
in ClearBasic code. Some controls may require you to use
specific naming conventions.
Control ID Sequence number of the control. This number is assigned
by the User Interface Editor and is unique among the
controls on the given form.
Context Menu For the text box controls, you can specify a list of context
menu items using this property.
Position Refers to the coordinates, in pixels, of the control’s
bounding box, relative to the corners of the form. There are
positions for Left, Right, Top, and Bottom. The Width and
Height refer to the dimensions of the control itself.

For a list of each control’s specific properties, see the entry for that control
elsewhere in this manual.

Using the Name and Control ID Properties

Each control relies on a unique name and ID number for identification. The
Name property is not the “label” for the control that appears in the CeFO
application (that would be the Caption). Instead, it is a means for identifying
controls on the form. The ID is used for sequencing as described in Changing
the Tab Order on page 103.

Control Names on Existing Forms

The CeFO application uses the control name to locate the control on a form.
This is done through ClearBasic code included with the CeFO baseline
forms—code which you cannot access or change. For this reason, you should
not change the names of controls on existing CeFO forms. If you add new
controls, however, you can assign your own names.

Working with Controls 101

Common Properties of Controls

Naming Conventions for Controls

It is recommended that you adopt a consistent naming convention for your
controls. For example, you could name your option buttons optName, and
use txtName for text boxes. Except for a few special cases, there is no
requirement to use a particular naming convention.

Refer to the ClearBasic Customization Guide for guidelines.

Figure 53 Control names in the Dispatch form

CASE_ID

WIPBIN_NAME
LABEL18
LABEL14
ComboBox17

FILTER_BY SELECT

CANCEL_BTN OK_BTN

Reserved Names for Controls

In the following cases, you must follow the CeFO naming conventions for
controls:
• Certain button controls use reserved names to indicate special functions
such as the Close or Done function.
• In certain instances, the control name is used by the CeFO application to
find the control in a form. For this reason, you should not change the
names of controls on existing CeFO forms.

Refer to the ClearBasic Customization Guide for more information.

102 Chapter 5
 Changing the Tab Order

Control ID Numbers
The Control ID is distinct from the Window ID. The Window ID uniquely
identifies the form and distinguishes it from all other forms in the database.
The Control ID number identifies the sequence of the control within the
form.

All controls in a form are numbered sequentially, starting from 1. If you

delete a control or change the order of controls, the ID number for controls in
the form change.

Changing the Tab Order

After you’ve added controls or changed the location of controls, check the
ordering of the controls to make sure the cursor moves in the proper
sequence when the Tab key is pressed. The order is defined by the control ID
numbers. Pressing the Tab key moves the cursor to the control with the next
higher ID number. (See Figure 54.)

You can change the order in which the Tab key moves between controls by
changing the ID numbers of the controls.

To view the tab order, choose View > Control Inspector or Edit > Tab Order.

Working with Controls 103

Changing the Tab Order

Figure 54 Checking the tab ordering between controls

Numbers
indicate the
tab ordering
in the form.
A black box
indicates the
selected
control.

The object sheet

window displays
the tab ordering
in a text format.

You can change the tab ordering with either the Control Inspector or the Tab
Order command.

To change the tab ordering with the Inspector command

1. Choose View > Control Inspector.
2. Select the control from the list.
The first time you open the Control Inspector after Saving a form, the
Control List shows all controls listed by Control ID except for label
controls (which appear at the end of the list).
3. For each control to move, click Up or Down until the control is at the
location you want.
The numbers in the form edit window update as you click Up or Down.
4. Click OK.

104 Chapter 5
 Changing the Tab Order

To change the tab ordering with the Tab Order command

1. Select the control you want to change.
2. Choose Edit > Tab Order.
Numbers appear around each control in the form, and the cursor changes
to show a small TAB icon.
The selected control is numbered in a black box, as shown in Figure 55.

Figure 55 Using the Tab Order command

The tab
number in the
black box
indicates the
The cursor selected
changes to control.
show a TAB
icon.

3. Press Tab to increment the number or press Shift+Tab to decrement the

number.
You can also click the left mouse button to increment the number and
click the right mouse button to decrement the number.
The tab numbering for the other controls updates to show the new tab
order for all the controls.

Working with Controls 105

Adding Context-Sensitive Menus for Controls

Adding Context-Sensitive Menus for Controls

Some controls support the ability to display a context-sensitive menu (also
known as a shortcut menu). A context-sensitive menu provides a list of
commands related to the operation of the control. The user displays the
context-sensitive menu by right-clicking the control.

NOTE: Context-sensitive menus require ClearBasic to implement the menu event

handlers.

Adding New Items

You can add a context-sensitive menu to grid controls, multiline text boxes,
and standard text box controls. (You cannot add context-sensitive menus to
date/time, currency, or mask edit text box controls). The menu items you
add appear after any default menu items defined by the application. For
example, a text box control already has application-defined menu items for
Clipboard operations such as Cut, Copy, and Paste.

NOTE: When you add custom menu items to a control, the control automatically
adds a separator between any application-defined menu items and your custom
menu items.

To add a context-sensitive menu to a control

1. Open the property sheet of the control.
2. Click the property titled Context Menu.
The Item Properties window appears as shown in Figure 56. For grid
controls, this window is titled Column Properties but is otherwise
identical in appearance.

106 Chapter 5
 Adding Context-Sensitive Menus for Controls

Figure 56 Item Properties window for a context-sensitive menu

Parentheses show associated Form ID
control name or TheForm, if
context menu is associated with CeFO version User version
the form itself

3. Select an empty row and add the menu item information for a new menu
item. Repeat the process for each new item you want to add.
For each menu item, you must specify the following information:
• Item label
• Name of the item (used to generate menu events)
• Name of the application menu (if any) to which the item belongs
• Type of item
4. Click OK to save the items.

Modifying Existing Items

You use the Menu Properties window to modify your custom menu items.
You can move items up or down in the menu or change the values currently
associated with the items. You cannot modify any application-defined menu
items. For example, you cannot modify the Cut, Copy, and Paste commands
associated with a text box control.

Working with Controls 107

Adding Context-Sensitive Menus for Controls

To modify a context-sensitive menu

1. Open the property sheet of the control.
2. Click the Context Menu property to open the Item Properties window.
3. Modify the menu item:
• To modify the menu item name and other properties, click the
appropriate cell and enter a new value.
• To move a menu item up or down in the menu, select the menu item’s
row and click the Up or Down button.

Handling Menu Events

When you add an item to a context-sensitive menu associated with a control,
you must use ClearBasic code to respond to menu events. When an item is
selected, the control generates an event whose name is derived from the
name of the control and the name of the menu item. For more information
on handling menu events related to a particular control, see the description
of that control in the ClearBasic Object Reference.

NOTE: The menu event used in ClearBasic has been renamed from
myControl_MenuName() to
myControl_ContextMenu.Select(MenuName). Although the former
event name is still supported, it is recommended that you use the new naming
convention wherever possible.

108 Chapter 5
Chapter 6

Display Controls

In This Chapter
The ActiveX Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
The Animation Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
The Bitmap Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
The Graph Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
The Group Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
The Label Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
The Line Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
The Progress Bar Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

109
The ActiveX Control

The ActiveX Control

Your CeFO forms can include any ActiveX controls that reside on your local
system. However, the end user must also have the same ActiveX control on
his or her system in order to use the control.

ActiveX controls are distributed as COM components (usually in a file with

a .ocx extension). If you intend to use ActiveX controls, you must distribute
the correct COM components to your end users or store the ActiveX control
in a shared area. Information on storing ActiveX controls in a shared area is
described in Sharing ActiveX Controls on page 111.

Figure 57 shows an example of an ActiveX control object.

Figure 57 Example of an ActiveX control object

Calendar ActiveX
object placed in the
Site Notes tab form.

Properties unique to
the ActiveX control are
listed here.

When you add an ActiveX control to a form, the Insert OLE Control window
appears and displays all the ActiveX controls that are installed on your
machine. Figure 58 shows an example of this window.

110 Chapter 6
 The ActiveX Control

Figure 58 Selecting an ActiveX applet

ActiveX applets installed on your machine.

(Your screen may look slightly different.)

ClearBasic code needs to be generated in order to pass data to and from the
ActiveX control. Otherwise, the ActiveX control functions independently
from the CeFO application.

The following is an example of ClearBasic code for a Web browser control.

Sub form_load
ocxweb.Navigate \
"http://www.amdocs.com/"
end sub

Sharing ActiveX Controls

To make sure your users have access to the required COM components,
place the components in a shared directory on your network and create a
script to register the component. Your installation script should be a batch
file (.bat extension) that registers the ActiveX control with the user’s
system. The contents of the batch file should be similar to the following:
regsvr32 path_to_COM_Component

For example,
regsvr32 c:\winnt\system32\msacal70.ocx

Store the batch file along with the COM component in a shared directory. In
the User Interface Editor, open the property sheet for the ActiveX control.
Click the Installation Path property and select the batch file you just created.
The control displays the path to this batch file in the Install From property.

Display Controls 111

The ActiveX Control

For example, suppose the .bat file is called active.bat and is located on
the C: drive of Pc_Gary. Place the ActiveX control on the form and open the
Properties window. Click the Installation Path property and locate the
active.bat file. When you select the file, the path
(\\Pc_gamma\shared\active.bat) appears in the Install From
property.

Specifying a registration script allows the user to use the ActiveX control
locally without downloading it. When a window containing an ActiveX
control is opened on a machine that does not have the proper COM
component installed, the user is asked to register the component. If you do
not provide a registration script, the user must locate and install the ActiveX
control manually.

NOTE: The first time the user opens a window with an ActiveX control, the control
is not displayed. The user must install the component either manually or using the
provided registration script. After installation, the user must either quit and restart
the CeFO application or choose Desktop > Update Desktop to see the ActiveX
object.

ActiveX Properties
Table 12 lists special properties of the ActiveX control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 12 Properties of the ActiveX control

Property Type Property Name Description

Misc Install From Displays the location of the registration script for shared controls.
See Sharing ActiveX Controls on page 111 for more information.
Installation Path Click to select the location of the registration script for a shared
ActiveX control. See Sharing ActiveX Controls on page 111 for
more information.
ActiveX These vary depending on the ActiveX control itself.
Properties

Some ActiveX controls may contain other unique properties. These

properties are defined by the vendor of the control. For more information
about ActiveX control properties, see the vendor documentation that
accompanied the control.

112 Chapter 6
 The Animation Control

The Animation Control

The animation control is a rectangular window that displays AVI (Audio
Video Interleave) clips. An AVI clip is a series of bitmap images or frames,
and is the standard audio/video format for Windows systems. When played
in succession, these images appear like a simple movie.

The animation control can play only simple AVI clips. The following is a list
of requirements for clips displayed by the animation control:
• There must be exactly one video stream and it must have at least one
frame.
• There is a maximum limit of two streams in the file. The AVI file cannot
have more than that. (Typically the other stream, if present, is an audio
stream.)

NOTE: The animation control ignores all audio information. It will play only
video streams.

• The clip must either be uncompressed or compressed with RLE8

compression.
• There can be no palette changes in the video stream.
• The AVI file(s) used must be located in a directory that is available to, or
distributed with, each client.

See Table 13 for a list of properties for the animation control.

Animation Control Properties

Table 13 lists special properties of the animation control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Display Controls 113

The Bitmap Control

Table 13 Properties of the animation control

Property Type Property Name Description

Appearance BackStyle Sets the background appearance for the animation clip. (Opaque
displays the background color of the AVI clip. Transparent
displays the color of the underlying CeFO form.)
Behavior AutoPlay Determines whether the animation control will begin to play an
AVI file when the AVI file is loaded into the control. (The AVI file
plays continuously if this property is set to Yes.)
Misc FilePath Contains the file name of the AVI clip file, including its path
information.

More Information: In ClearBasic, use the Play method of the Animation object to
initiate the playback of an AVI clip file. This method lets you specify which frames
of the clip file to play. See the ClearBasic Control Reference for more information on
this method.

The Bitmap Control

Use the bitmap control to place bitmap images in your forms.

Bitmap Control Properties

Table 14 lists special properties of the bitmap control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 14 Properties of the bitmap control

Property Type Property Description

Appearance Picture The name of the bitmap file. Do not enter the full pathname;
instead, select the file using Bitmap dialog.

114 Chapter 6
 The Bitmap Control

When you create a new bitmap control, the UI Editor displays the Bitmap
Dialog window so that you can select a bitmap file. The name of the file you
choose is placed in the Picture property. To modify the file name, click the
Picture property in the Properties dialog box and select a new bitmap from
the Bitmap Dialog window.

In the Bitmap Dialog window, click the Load button to display the standard
file browsing window. From this window, you can select the bitmap file you
want do display in the control.

NOTE: The bitmap file you select must reside on the client’s machine, and the path
relative to the UI Editor application (and the CeFO application) must be 80
characters or less. One way to ensure that your bitmaps are included is to create a
subdirectory for bitmaps in the CeFO application folder.

In the Bitmap Dialog window, you can also select a color from the
Transparent dropdown list, to make a particular bitmap color transparent.
For example, if you select red from the dropdown list, all instances of red in
your bitmap become transparent, letting whatever is underneath it show
through. Figure 59 shows the Bitmap Dialog window.

Figure 59 The Bitmap dialog box

Display Controls 115

The Graph Control

The Graph Control

Graph controls display statistical data graphically. At run time, the graph
control generates a bitmap image representing the associated data and
displays it in the control rectangle. The bitmap image makes it easier for
users to detect trends in the data by providing immediate visual
comparisons among all of the data points.

The graph control supports many different graph styles, including different
types of bar charts, pie charts, and statistical plots. When you create a graph
control, you must decide which graph style is most appropriate for the data
you expect to display.

Specifying Graph Data

Graphs can use data from one or more contextual objects or you may enter
the graph data programmatically using ClearBasic code. You may not use a
mixture of contextual objects and ClearBasic code to supply the graph data.

Normally, the data points you specify must be numerical values. However,
you can also specify strings by setting the Aggregate property of the graph
control to Yes. Using aggregation, the graph control groups identical strings
together and assigns them a specific number. The control then uses the
assigned number to plot the data.

Graph Appearance
At run time, the graph control generates a bitmap from the given data and
displays that bitmap in the control’s rectangle. The exact appearance of the
bitmap depends on the current values on the control’s Property sheet.
However, most graphs have three main elements: data points, graph labels,
and a graph legend.

Each data point is displayed on the graph control’s bitmap using a graphical
element, such as a rectangle or pie shape. The value of the data point directly
affects the size and shape of the graphical element.

The graph legend and labels identify the groups to which each data point
belongs. The graph legend identifies elements of a particular data set using a
unique color. Graph labels identify related elements of one or more data sets.
Figure 60 shows the graph elements, labels, and legend associated with a
graph control.

116 Chapter 6
 The Graph Control

Figure 60 Sample form with a graph control

Data Legend
Points

Labels

Graph Properties
Table 15 lists the special properties of the graph control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 15 Properties of the graph control

Property Type Property Name Description

Appearance Graph Type Specifies the style of graph displayed by the control. Options
include bar graphs, pie graphs, statistical plots, and many others.
Border Style Specifies the type of border (if any) to draw around the graph
control.
Back Color Specifies the background color of the graph.
Back Style If set, uses the color in the Back Color property for the graph
background; otherwise, the graph control displays a black
background.
Show Legend Specifies whether or not the graph displays its associated legend.
The legend identifies each data set using a specific color.
Legend Position Specifies the edge of the graph along which the legend lies. The
legend may be placed along the left, right, top, or bottom edges
of the graph.
Show Grid Line Specifies whether the graph displays grid lines at major
incremental values.

Display Controls 117

The Group Box Control

Table 15 Properties of the graph control (Continued)

Property Type Property Name Description

Font Legend Font Specifies the font to use when drawing the legend text. You can
select one of the listed fonts, or choose None to use the default
application font.
Legend Font Color Specifies the color to use when drawing the legend text. You can
choose one of the specified color values from the dropdown list.
Label Font Specifies the font to use when drawing graph labels. You can
select one of the listed fonts, or choose None to use the default
application font.
Label Font Color Specifies the color to use when drawing graph labels. You can
choose one of the specified color values from the dropdown list.
Data Use Contextual Specifies whether or not the graph gets its data from a contextual
Objects object. If this property is No, you must use ClearBasic code to
associate the graph data with the control.
Aggregate Specifies whether the graph control aggregates identical string
values.
Data Sets As Specifies whether data sets are organized by row or by column.
Source Contextual Click the button to display the Item Properties window. From
Object this window, select the contextual objects and fields from which
to obtain the graph data.

Graph controls deal exclusively with numerical data. If you want to use
strings as data points, you must set the Aggregate property of the control to
Yes. When you do this, the Graph control groups identical strings together
and then enumerates the resulting string data points.

The Group Box Control

Use the group box control to visually group controls in a form. Figure 61
shows an example of a group box control.

118 Chapter 6
 The Group Box Control

Figure 61 Example of a group box control

Group box
control

You can define the “label” that appears in the group box control, or use a
contextual object as the source of the text string to display.

Group Box Properties

Table 16 lists the special properties of the group box control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 16 Properties of the group box control object

Property Type Property Name Description

Appearance Text Text string to be displayed. If you want to use a contextual object
as the source of the text string, leave this property blank.
Alignment Alignment of the text string with respect to the group box.
Style Draws the box as a solid line or creates a 3-dimensional effect.
ForeColor Specifies the color of the group box text. If you specify Nil, the
control uses the default color (usually black).
Data Source Contextual (optional) Name of the contextual object to use as the source of
Object the text string to be displayed. The contextual object must be a
string data type.
Source Field Name Contextual object field to use as the source of the text string to be
displayed.
Source Data Type (read-only) Data type of the source contextual object.
Font Font Specifies the font to use for the group box text. You can specify
font name, style, and size for the text.

Display Controls 119

The Label Control

The Label Control

The most common use of a label is to identify another control. The example
in Figure 62 shows label controls.

Figure 62 Examples of label controls

Labels

A label control can also be used to display a string value contained in a

contextual object. To use a contextual object as the source of the text string,
open the label Properties window and select the source contextual object
(and field name) to use.

You can also use label controls to show calculated values. For example, a
select window in ClearSupport can show the number of cases selected by a
particular query operation. Figure 63 shows how the New Case window
uses a label to display the number of open cases for a site.

120 Chapter 6
 The Label Control

Figure 63 Using a contextual object as the label string source

This label
uses the
OPEN_TEXT
contextual
object as the
text string to
display.

Select the source contextual

object here.

Because a label control can display only string values, non-string values
must be converted to string before loading them into the control. You can
use ClearBasic to convert an integer value to a string.

More Information: For more information about using ClearBasic to convert values
to strings, see the ClearBasic Language Reference and the ClearBasic Control
Reference.

Using HyperLinks
HyperLinks allow a label to serve as a link to either a URL or a file path. If it
is a URL, then the specified location opens in the user’s default Internet
browser. If it is a file, and an application is associated with that file type, the
application starts and opens the file. If the file specified in the HyperLink is
itself an executable, then the application opens.

Display Controls 121

The Label Control

The properties are:

• HyperLink—toggles all hyperlink behavior on or off
• HyperLink color—causes label to change color when cursor passes over
it
• Use Link String—toggles use of Link String on or off
• Link String—specifies a fixed URL or file path to use
• HyperLink Font—specifies font for hyperlink
The following rules apply:
• If the HyperLink property is set to No, none of the other hyperlink
properties are enabled. The label behaves as a regular static text control.
• Setting the HyperLink property to Yes enables the HyperLink Color,
HyperLink Font, and the Use Link String properties.
• Setting the Use Link String property to Yes enables the Link String
property. The value you enter as the Link String is used as the URL or file
path.
• If the HyperLink property is set to Yes and Use Link String is set to No,
then the Caption is used as the URL. The Link String is disabled. If you
link the Caption to a source contextual object of type String, you can
dynamically change the URL at runtime
• If the Use Link String is set to Yes, the Link String value, if any is
supplied, is used as the URL.
• If Use Link String is set to Yes, but no Link String value is specified, then
clicking on the label triggers an event named controlName_click that is
passed to the ClearBasic code behind the form.

Label Properties
Table 17 lists the special properties of the label control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

122 Chapter 6
 The Label Control

Table 17 Properties of the label control

Property Type Property Name Definition

Appearance Caption Text string to be displayed in the window.
BackColor Specifies the color to place behind the text string. A Nil setting
for BackColor means that the control will inherit the background
color from the form. If the form’s BackColor setting is also Nil,
then the form uses the Windows color settings on the user’s
machine.
ForeColor Specifies the color of the group box text. For ForeColor, any
control with a Nil setting directly inherits the font color set by the
user. This font color may be set in the CeFO application under
My Preferences, or it may be set at the Windows application
level.
HyperLink Color (Activated if HyperLink set to Yes) If set to a color, the label text
is highlighted in this color whenever the mouse cursor passes
over it.
Behavior Enable On If set, this control remains enabled after a currency conversion
Currency Convert occurs.
HyperLink All other Hyperlink properties are only activated if this control is
set to Yes. This causes the label can act as a hyperlink to open a
URL in an Internet browser window, or as a link to an executable
file.
Use Link String Yes or No:
• If set to Yes, the value of the Link String property is treated as
a URL.
• If No, Link String is disabled and the Caption is used as the
URL.
Resize Determines whether control resizes when form is resized. If set to
Yes, the label stretches to fit the form when a user maximizes or
enlarges the form. This property is useful when labels are used as
decorative colored areas (as for example, on the CeFO multipane
forms).
Link String URL or file path to use. Use Link String is Yes, but no value is
specified here, then a ControlName_click event is passed to
the CB code behind the form.

Display Controls 123

The Line Control

Table 17 Properties of the label control (Continued)

Property Type Property Name Definition

Data Source Contextual (optional) Name of contextual object to use as the source of the
Object text string to be displayed. The contextual object must be a string
data type.
Source Field Name (optional) Contextual object field to use as the source of the text
string to display.
Source Data Type (read-only) Data type of the source contextual object (defined in
the Edit Contextual Object window).
Font Font With this property, you can specify the font face for the text
string. If the font face you specified is not installed on a user’s
system, Windows uses the best guess for font substitution.
HyperLink Font If set, the label text changes to this font whenever the mouse
cursor passes over it.

The Line Control

Lines can be used to visually group or separate controls on a form. You can
draw lines at any angle by either drawing them at the angle you want, or
drawing them and then adjusting their angle.

Line Properties
Table 18 lists the special properties of the line control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 18 Properties of the line control

Property Description
PenStyle Draws a solid or dashed line.
PenWidth Width of the line (in points.)
ForeColor Selects a color for the line. The default color is Nil, which draws a black line (no color).
Height Determines the number of vertical pixels between the endpoints. Set to 1 for a horizontal
line.
Width Determines the number of horizontal pixels between the endpoints. Set to 1 for a vertical
line.

124 Chapter 6
 The Progress Bar Control

The Progress Bar Control

Use the progress bar control to display the progress of an operation. Use this
control to report the status of long operations, like database reads and
writes, file copying, or the synchronizing of mobile clients. Figure 64 shows
an example of a progress bar control.

You can set a range for data using the Max and Min properties.

Figure 64 Example of a progress bar control

Progress bar control

Progress Bar Control Properties

Table 19 lists the special properties of the progress bar control. (For a list of
the common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 19 Properties of the progress bar control

Property Type Property Name Description

Behavior Enabled If set, the user can interact with the control; otherwise the
control is disabled when the form is posted.
Data Destination Contextual object to use to track the progress of an operation.
Contextual Object The contextual object must be an Long integer data type.
Destination Field Contextual object field to use as the source of the operation to
Name track.
Destination Field (read-only) Data type of the destination contextual object.
Type
Misc Max Sets the maximum value of the range for the progress bar
control.
Min Sets the minimum value of the range for the progress bar
control.

Display Controls 125

The Progress Bar Control

126 Chapter 6
Chapter 7

Navigation and Action Controls

In This Chapter
The Button Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
The Tab Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
The Treeview Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150

127
The Button Control

The Button Control

Buttons give a user the ability to invoke an action or to open a frame (or a
form if the User Interface Editor is started with the -cb option). A button can
also invoke a command or stored procedure that you defined.

There are three types of buttons:

• Command—executes an action or group of actions
• Form Init—used as invisible placeholders for actions to be executed
when a form is displayed
• Frame—opens a child form as a separate window
Figure 65 shows an example of button controls.

Figure 65 Example showing button controls

Buttons

IMPORTANT: Do not define a default button for forms that contain multiline text
boxes, because this will prevent users from using carriage returns in those fields.

128 Chapter 7
 The Button Control

Using Command Buttons

Command buttons execute a specified action or group of actions.

IMPORTANT: CeFO buttons access special routines in the code associated with the
name of the button. Do not reuse CeFO button names or change the name of a
CeFO button. See Figure 70 for a list of reserved names.

For information about using a command button to call an action, see

Chapter 12, Using the Action Editor.

Assigning Mnemonics
Some buttons can be accessed with a keyboard shortcut. For example, the
Add button in the Part Request Detail form can be accessed by pressing the
modifier key and the A key. For example, if the Alt key is the modifier, the
keyboard shortcut would be Alt-A.

Figure 66 shows an example of mnemonics in the Part Request Detail form.

Figure 66 Example showing button mnemonics

The Add and Clear buttons can be

accessed with a keyboard shortcut.

Navigation and Action Controls 129

The Button Control

If at all possible, the letter used for a keyboard shortcut should be

mnemonic. It should be the first letter of the button name, or it should have
some other relevance so that it can be remembered.

NOTE: On the PC, the modifier key is the Alt key. On a Sun workstation, the
modifier key is the Meta key.

To assign mnemonics to a button, type an ampersand (&) before the desired

“trigger” character in the text of the button’s Caption property. See Figure 67
for an example.

For example, to assign the mnemonic “D” for a button labeled “Details,”
enter “&Details” as the text property. To assign the letter “v” as the
mnemonic for a button labeled “Availability,” enter “A&vailability” as the
text property. You can use alphabetic or numeric characters as mnemonics;
special characters are not allowed.

130 Chapter 7
 The Button Control

Figure 67 Assigning mnemonics to a button

1 Select the button

control.

Type an ampersand (&)

2 in front of the character
The letter for the keyboard shortcut
that is the shortcut key. 3 is underlined in the preview mode.

Navigation and Action Controls 131

The Button Control

Buttons That Accept Mnemonics

You cannot assign mnemonics to all button types. In order to be assigned a
mnemonic, a button must be:
• Editable within the UI Editor: You cannot assign mnemonics to buttons
that use a source contextual object for the button name.
• Single function: You cannot assign mnemonics to a button that toggles
functionality, for example a Yes/No button, where the ClearBasic code
updates the button caption.

Checking for Duplicate Mnemonics

Although you can use the same mnemonic character more than once on the
same form, this is not recommended. You can use the same mnemonic
character in different forms.

If you assign the same mnemonic character to more than one button, the
action taken when that mnemonic key is pressed depends on the following
conditions:
• Order of the control IDs
The control with the lowest ID number (assigned the mnemonic) is
used.
• Whether the associated button is enabled or disabled
Mnemonics assigned to disabled buttons are ignored.

Choose Edit > Verify Form to check that you have no duplicate mnemonics.

Mnemonic Precedence
You can reuse characters that are used as accelerator keys on menus. An
accelerator is a key or combination of keys that invoke a function (often a
menu item) without displaying the menu, associated forms, or dialogs.

NOTE: Accelerator keys take precedence over mnemonics. If the same character is
used as a mnemonic on the active form and as an accelerator key on a menu, the
accelerator key on the menu takes precedence; the mnemonic action is ignored.

132 Chapter 7
 The Button Control

Using Form Init Buttons

Form init buttons are not displayed in CeFO applications. Instead, they are
used as placeholders for button actions to be executed when a form is
displayed. Only one button per form can be defined as a form init button.

More Information: For more information about using Form Init buttons, see
Chapter 12, Using the Action Editor.

Using Frame Buttons

Frame buttons open child forms that appear in a separate window from the
parent form. The child form is still dependent on the parent, and closes
when the parent form is closed. The form that contains the frame button is
called the parent form. The form that is opened when the frame button is
clicked is called the child form.

NOTE: The difference between child forms (frames) and parent forms is that you
can open a child form without writing ClearBasic code.

Figure 68 shows an example of a frame button in the Subcase window from

ClearSupport.

Navigation and Action Controls 133

The Button Control

Figure 68 Example of a frame button in the Subcase window

The Case History

button is an example
of a frame button.

The Subcase: Case History

window appears as a
“child” window of the
subcase window when the
Case History button
is clicked.

Dismissing a Child Form

To close a child form and return to the parent form, create a frame button on
the child form and enable the Dismiss property. For example, the Done
button on the Subcase: Case History window has the properties shown in
Figure 69.

134 Chapter 7
 The Button Control

Close/Done Buttons for Child Forms

Child forms should have a button to close the form. If you don’t have this
button, the child form can be closed only when the parent form is closed.
• If the parent form has a button with the name DONE, create a command
button on the child form with the name CLOSE (you can set the
command button caption to whatever you like).
• If the parent form has a button with the name CLOSE, create a command
button on the child form with the name DONE.

The names DONE and CLOSE are special because the CeFO application looks
for these buttons when the user clicks the window close icon or uses a
standard keyboard shortcut like Control-F4 to close the window. If your
form does not have them, the window close icon will not work.

More Information: For more information about frames, see The Group Box Control
on page 118.

To define a frame button to open a child form

1. Open the parent form.
2. Click the Button icon on the Object toolbox and place the button on the
parent form.
3. Double-click the button control to open the Property window.
The button properties window appears as shown in Figure 69.

Navigation and Action Controls 135

The Button Control

Figure 69 Using the button Dismiss property

Select the Dismiss

property to close
a child frame.

4. Type a name and caption for the button.

For example, type NEXT_FRAME and More Info... as the Name and
Caption properties, respectively.
5. Choose Frame as the Button Type property.
6. In the Dialog ID property, enter the Form ID number of the child form.
When the user clicks this button, the child form will open.
7. Open the child form.
8. Click the Button icon on the Object toolbox and place a button on the
child form.
9. Double-click the button control to open the Property window.
10. Enter a name and text for the button.
For example, enter DONE and Done as the Name and Caption properties,
respectively.

IMPORTANT: When adding a frame command button to a custom form, make sure
that the name you assign to the button is not used by any other control on the
parent or child windows. If the control name is not unique, the button may not link
correctly to its child frame.

11. Choose Frame for the Button Type property.

136 Chapter 7
 The Button Control

12. In the Dialog ID property, enter the Form ID of the parent form.
13. In the Dismiss property, select 1 - Yes.
Setting the Dismiss property to Yes causes the child form to close when a
user clicks this button to return to the parent form.

Displaying Pictures in Buttons

Instead of providing a caption for a button, you can display pictures
“inside” a button. You can assign pictures to command buttons and Frame
buttons, but not to form init buttons.

To associate a picture with a button, assign a value to the button’s Icon ID

property. This value specifies an icon resource. lists the icon ID and
associated image for various types of buttons.

Figure 70 Button icons

Button function Image Icon ID

Email 1142

Dial 1148

Date and Time 1150

Edit Filter 1152

Elapsed Time 1154

Lookup 1158

More 1160

Next 1162

Previous 1166

Date 1168

Up 1170

Down 1172

Navigation and Action Controls 137

The Button Control

All picture buttons should measure a minimum of 24 x 20 in size, to ensure

that the images fit without clipping. When appropriate, picture buttons can
be wider than 24 pixels, but should always be 20 pixels in height. Regardless
of the dimensions of the button, the image is always centered in the
available space, and is clipped as needed (if the button is smaller than 24 x
20, some clipping will occur).

Reserved Button Names

Certain button names within CeFO are reserved for special functions, such
as closing a window. You can use these buttons on your forms, to perform
those same functions. Refer to the ClearBasic Customization Guide for a list of
reserved names.

Button Properties
lists the special properties of the button control. (For a list of the common
properties supported by all controls, see Common Properties of Controls on
page 99.)

Figure 71 Properties of the button control

Property Type Property Name Description

Appearance Caption Text string to be displayed on the button. If you want to use
a text string from a source contextual object, leave this field
blank. Use the ampersand (&) to add a mnemonic, as
described in Assigning Mnemonics on page 129.
Behavior Default If set, this button is registered as the default button. Pressing
the Enter or Return key has the same result as clicking the
button. Do not use on forms containing multiline text boxes.
Dismiss For frame buttons only. Closes the frame when the button is
clicked.
Enabled If set, the user can interact with the control; otherwise the
control is disabled when the form is posted.
Enable On Currency If set, this control remains enabled after a currency
Convert conversion occurs.

138 Chapter 7
 The Tab Control

Figure 71 Properties of the button control (Continued)

Property Type Property Name Description

Data Source Contextual Object (optional) Name of contextual object that supplies the
button caption. The contextual object (or referenced field)
must contain a string data type.
Source Field Name (optional) Contextual object field that is the source of the
text string to be displayed on the button.
Source Data Type (read-only) Data type of the source contextual object.
Misc Button Type Defines the button type:
• Command—executes action or group of actions.
• Form Init—used to initialize form
• Frame—opens the child form
Dialog ID (Frame buttons only) Identification number of the child
form to display when this button is pressed.
Icon ID (Optional.) Identification number in the icon ID field is
mapped to the picture to be displayed on the button.
Icon Type (Optional.) Specify whether you want the icon and text or
only the icon to appear on the button.

The Tab Control

A tab is a child form that is displayed entirely within the parent form. Tabs
are convenient for displaying information when users need to see the parent
form at the same time, but need to switch among other subsets of
information.

Tabs are generally created as a group, as shown in the example form in

Figure 72.

Shown/Hidden Tab Titles

You can implement a group of tabs to either show the tabs titles as in
Figure 72, or you can hide the tab titles. When the tab titles are shown, the
user clicks on each tab’s title to bring that tab to the front. However, with
hidden tabs, you must use ClearBasic code to specify the events or user
actions that bring each tab to the front.

See Tab Controls for Multipane Forms on page 147 for more information on
using tabs with hidden titles.

Navigation and Action Controls 139

The Tab Control

Figure 72 Tabs displayed in CeFO vs. UI Editor

CeFO - Tab displays on parent form

Tabs

UI Editor—Tab appears as separate, child form.

The Tab Form ID property of

each tab control references
the Form ID of the associated
child form.

140 Chapter 7
 The Tab Control

All tabs in a form must have the same set of contextual objects as the parent
form. Never add new contextual objects to an existing child form. Instead,
you should add the new contextual objects to the parent form and then use
the Propagate command to copy those contextual objects to the child form.

Tab Restrictions
The following is a list of rules for using tabs.
• Forms must share the same set of contextual objects. (You can propagate
contextual objects from a parent form to a tab using the Propagate
Contextual Objects command. See Propagating Contextual Objects on
page 238 for more information.)
• Only one row of tabs is allowed.
• A tab control can only be used to post a child form, but not a parent form.
• Select CBX controls must reside on the parent form.
• The color of the Tab label text cannot be changed.
• Tab background text cannot be changed. The color is determined by the
form background resource.
• The Tab label text is displayed in 12-point Helvetica font only.
• The order in which tabs appear is determined by the control ID. The
order in which the Tab key navigates through tabs is also determined by
control ID. The order is from left to right beginning with the lowest
number.
• Tabs cannot be nested (a tab cannot contain other tabs).
• Keyboard mnemonics cannot be assigned to tabs.
• It is recommended that you place required text boxes and dropdown list
boxes in the default tab.
• User-defined dropdown lists must reside on the parent form or the
default tab.

NOTE: If you are planning on using this version of the User Interface Editor with
forms imported from a previous version of CeFO, use the tab naming convention
set by the previous version for those forms.

Navigation and Action Controls 141

The Tab Control

Planning for Tabs

Adding tabs to a form involves:
• Designing the layout for each tab
• Creating child forms
• Adding tab controls to the parent form
• Adjusting the ordering of tabs
• Setting the default tab

Designing the Tab Layout

Before creating tabs, identify the area on the parent form that will contain
the tabs. All of your child forms must fit into this area. Then determine the
information to display, and divide it into logical groups. Each logical group
should go on its own tab. Finally, decide how you want the information to be
displayed. This will influence the arrangement of the controls on the child
form.

Creating Child Forms

Create a separate child form for each tab control.

To create a child form for a tab control

1. Open the parent form.
2. Choose File > New > Child Form.
A new form window appears.
3. Adjust the size of the child form to be within the bounds of the default
tab.
For best results, you might want to specify a width that is equal to the
width of the first tab control’s bounding box minus 25. Also, specify a
height that is equal to the height of the first tab control’s bounding box
minus 45.
4. Add the desired controls to the child form.

142 Chapter 7
 The Tab Control

5. Record the Form ID of the child form.

You need the Form ID when defining the tab control on the parent form.
The Form ID identifies which child form is displayed when the tab
control is clicked.
6. Save and close the child form.
7. Repeat Step 2 through Step 6 for the other child forms.
8. Add all the child forms to a resource configuration.
Resource configurations define the set of forms that can be used by a
group of users. The child forms should belong to the same resource
configurations as the parent form, so that any user who can access the
parent form can also open the child forms.
For more information about resource configurations, see Adding Forms to
a Resource Configuration on page 63.

Adding Tab Controls to the Parent Form

After creating the tab frames, you must add one tab control to the parent
form for each child form that will be displayed.

NOTE: For best results, specify a width that is equal to the width of the first tab
control’s frame plus 25. Also, specify a height that is equal to the height of the first
tab control’s frame plus 45.

Navigation and Action Controls 143

The Tab Control

Figure 73 Setting the display area for the tab frames

In the New Case

form, the Case
tab is the first tab
in the control
order. The
bounding box of
the Case tab
defines the
display area of
the tab frames.

To add tab controls to a parent form

1. Place each tab control on the parent form.
The bounding box of the first tab in the tab order determines the display
area for the tab frames. In other words, resize the bounding box of the
first tab control you place on the form to the width and height of the tab
frames. (See Figure 73.)
The tab order is the order in which controls on a form are selected when
the user presses the Tab key. To change the tab order, see Changing the Tab
Order on page 103.
2. Open the properties window for each tab.
Double-click the first tab control open the Properties window. For
subsequent tabs, selecting the tab on the form causes the Properties
window to show the properties for the selected tab.
Some properties only show for the first tab (shown in Figure 74).

144 Chapter 7
 The Tab Control

Figure 74 Defining the tab properties

Properties for the first tab Properties for subsequent tabs

Enter the text to be displayed

on the tab here.
Set the Default property to
Yes for the default tab.

3. Determine which tab is the default.

The default tab is the one displayed when the form is opened. Set the
Default property to Yes for the default tab.
4. For each tab, specify the Form ID of the child form to link to as the Tab
Form ID property.
5. Save the form to commit your changes.

Navigation and Action Controls 145

The Tab Control

Tab Sizes
For a form such as the one shown in Figure 73, the size of the bounding
boxes of other tab controls is not important because all the tab controls
inherit the size of the first tab control. Other tab controls can be placed
anywhere in the form, but it is a good idea to place them inside the
bounding box of the default tab control.

However, for multipane forms the tab buttons do need to be appropriately

sized.

Adjusting the Ordering of Tabs

The control IDs of the tabs determine the order in which tabs appear. Tabs
appear from left to right, beginning with the tab that has the lowest control
ID. Figure 75 shows an example of tab ordering.

Figure 75 Reordering tabs in the New Case form

Tab Order ID 13 14 15 16 17 18 19

The order of the tabs has been reversed for

More Info and Prev. Cases.

The procedure for reordering tabs is just like changing the tab order between
controls. See Changing the Tab Order on page 103.

NOTE: The Control ID property for each tab is different from the Tab Order ID
shown when changing the tab order. However, both IDs re-number when you
change the tab order.

146 Chapter 7
 The Tab Control

Setting the Default Tab

One tab must be defined as the default tab. The child form associated with
the default tab is the one that appears when the parent form is displayed.
Use the Default property to specify the default tab, as shown in Figure 74 on
page 145.

Tab Controls for Multipane Forms

In multipane form layouts, the tab button no longer appears. However, the
underlying method of constructing the form is similar, with the use of tabs
and child forms.

Figure 76 shows the Action Item form in the ClearCallCenter application. It

has two tabs: the Log Notes tab for CeFO notes, and the Outlook Notes tab
for notes synchronized from the Microsoft Outlook application. The View
menu is used to front one tab or the other.

Figure 76 Example of multipane-style tabs

Each tab is
fronted using the
View menu

Tab
area

Navigation and Action Controls 147

The Tab Control

Tab Properties
Some of the tab control properties only appear on the properties window of
the first tab control created on the form. If you create a set of tab controls,
then delete the first tab, the second tab shows the properties listings
formerly shown for the first tab.

If you want the extra properties to appear for a different tab without having
to delete the first tab, you can reorder the tabs to give the new tab the lowest
tab order within the group of tab controls. See Changing the Tab Order on
page 103.

Table 20 lists the special properties of the tab control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 20 Properties of a tab control

Property Type Property Name Description

Appearance Text Text string to be displayed on the tab.
Behavior Child First tab control only. If Yes, then tab is created without the
clickable header (the “tab” itself). Used for multipane forms. In
order to bring the form to the front you must use
{Tabcontrol}.Value in your ClearBasic code.
This property is only set for the first tab in a group of tabs, as
determined by tab order. See Changing the Tab Order on page 103.
Default If set, this tab appears when the form is posted. Not used for tabs
where titles are hidden (Show Title is set to No).
Dependent For internal use only. Always Yes.
Enabled If set, the user can select the tab; otherwise the tab is disabled
when the form is posted.
Is Grouped First tab control only. Enabled if Child property is set to “Yes”.
Used for multipane forms. If No, the tab is created in the
rectangle specified by the control, and tabs are hidden or fronted
using ClearBasic code. If Yes, the tab always appears in front of
the “master” tab.
This property is only set for the first tab in a group of tabs, as
determined by tab order.

148 Chapter 7
 The Tab Control

Table 20 Properties of a tab control (Continued)

Property Type Property Name Description

(Behavior) Show Border First tab control only. Enabled only if Child property is set to
“Yes” and Show Title is set to “No.” Used for multipane forms.
Show the border of the child. This property is only set for the first
tab in a group of tabs, as determined by tab order.
When the Show Title property is set to “Yes,” the Show Border
property is automatically set to “Yes” and is disabled. Show
Border is enabled if Show Title is set to “No.”
Show Title First tab control only. Enabled if Child property is set to “Yes.”
Used for multipane forms. Setting this to Yes will show the
caption for the child form. Applicable only if Child property is set
to “Yes.”
This property is only set for the first tab in a group of tabs, as
determined by tab order.
Data Destination Not used.
Contextual Object
Destination Field Not used.
Name
Destination Data Not used.
Type
Source Contextual Not used.
Object
Source Field Name Not used.
Source Data Type Not used.
Misc Icon ID Resource ID of the icon that is displayed on the tab.
Tab Form ID ID of the child form that will be shown in the tab area.
Group Items Shows other tab controls grouped with this one.

Navigation and Action Controls 149

The Treeview Control

The Treeview Control

The treeview control displays a hierarchical list of items, referred to as nodes,
much like the Windows Explorer program in Microsoft Windows. Each node
is made up of a label and an optional bitmap image. For example, the
treeview control can be used to display a hierarchical list of parts, part
numbers, and serial numbers located or installed at a certain site.

Figure 77 shows the treeview control from the Lead Manager form as it
appears in the CeFO application, and then as it appears in the UI Editor
application.

Figure 77 Example of a treeview control

As seen in CeFO application As seen in the UI Editor application

150 Chapter 7
 The Treeview Control

Keyboard Navigation with the Treeview

Control
The following keyboard navigation can be used by application users, when
they use the treeview control:
• The Up Arrow and Down Arrow keys cycle upward and downward
through all expanded nodes. (Nodes are selected from left to right, and
top to bottom.)
• The Left Arrow and Right Arrow keys also cycle upward and downward
through expanded nodes, except for the following:
• If the Right Arrow key is pressed while an unexpanded node is selected,
the node expands.
• If the Left Arrow key is pressed while an expanded node is selected, the
node collapses.
• If a user presses an alphanumeric key, the focus will jump to the nearest
node that begins with that letter. Additional keystrokes of that key will
cycle downward through all expanded nodes that begin with that letter.

Treeview Control Properties

Table 21 lists the special properties of the treeview control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

NOTE: You must have a ClearBasic license in order to add or modify treeview
controls.

Navigation and Action Controls 151

The Treeview Control

Table 21 Properties of the treeview control

Property Type Property Description

Name
Appearance BackColor Sets the background color of the treeview control.
ForeColor Sets the foreground color of the treeview control.
Indentation Sets the width in pixels of indentation for child nodes. Each new child
node is indented by this much.
LineStyle Sets the style of lines displayed between nodes. Values are
• TvwRootLines - show expand/collapse icons for root-level nodes as
well as child nodes
• TvwTreeLines - show expand/collapse icons only for child nodes
Behavior Enabled If set, the user can interact with the control; otherwise the control is
disabled when the form is posted.
Hide Selection If not set, then the selection is retained when user clicks on another
control.
Hot Tracking If set to yes, then the tree items behave like hyperlinks, and show an
underline as the mouse cursor passes over them.
Sorted Controls whether the nodes are sorted alphabetically or not.
Style Sets the display style of the lines and nodes in the treeview control. The
options are as follows:

Option Displays
tvwTextOnly (default) Text only
tvwPictureText Image and text
tvwPlusMinusText Plus/minus signs and text
tvwPlusPictureText Plus/minus signs, image, and
text
tvwTreelinesText Lines and text
tvwTreelinesPictureText Lines, image, and text
tvwTreelinesPlusMinusText Lines, plus/minus signs, and text
tvwTreelinesPlusMinusPictureText Lines, plus/minus signs, image,
and text
Font Font Specify font to use for treeview listings.

152 Chapter 7
Chapter 8

Input Controls

In This Chapter
The Check Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
The Option Button Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
The Text Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
The Multiline Text Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
The List Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
The Dropdown List Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
The Dropdown Combo Box Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
The Slider Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
The Updown Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190

153
The Check Box Control

The Check Box Control

Check boxes act as toggle switches. Use check boxes to indicate that an
option is either selected or not selected. Check boxes appearing together are
independent of each other; any number can be on or off. Figure 78 shows an
example of check box controls.

Figure 78 Example showing check box controls

Check boxes

A check box control can have a source and destination link to contextual
object fields.
• The optional source link can display a character string stored in a
contextual object field as the text label next to the check box.
• The destination link writes the value of the check box to the contextual
object. If the check box is selected, a 1 is written. If the check box is not
selected, a 0 is written.

NOTE: The destination must link to an integer field.

Check Box Properties

Table 22 lists the special properties of the check box control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

154 Chapter 8
 The Option Button Control

Table 22 Properties of the check box control

Property Type Property Name Description

Appearance Caption Text string to be displayed next to the check box. If you want to
use a text string from a source contextual object, leave this field
blank.
Behavior Enabled If set, the user can interact with the control; otherwise the control
is disabled when the form is posted.
Enable On If set, this control remains enabled after a currency conversion
Currency Convert occurs.
Data Destination Contextual object used to store the value of this check box. The
Contextual Object contextual object must be an integer data type.
Destination Field Contextual object field name used to store the value of this check
Name box.
Destination Data (read-only) Data type of the destination contextual object. The
Type data type for check boxes must be Integer.
Source Contextual (optional) Name of contextual object that is the source of the text
Object string to be displayed next to the check box. The contextual object
must be a string data type.
Source Field Name (optional) Contextual object field that is the source of the text
string to be displayed next to the check box.
Source Data Type (read-only) Data type of the source contextual object.
Position AutoSize Yes or No. Setting this to Yes causes the control to resize based on
the length of the caption text. This can happen at runtime if the
ClearBasic code changes the label text, or if a user’s system has a
larger font size than that for which the form was designed.

The Option Button Control

Option buttons (sometimes called radio buttons) allow users to choose one
option out of many. Each option is defined by a different option button. If a
group of option buttons specifies one set of options, these option buttons are
“associated” with each other. The Group Items property shows the
associated option buttons.

Figure 79 shows an example of option button controls.

Input Controls 155

The Option Button Control

Figure 79 Example of option button controls

Option buttons.
Caption property
holds the text
associated with
each option
button.

Values Passed from Option Selected

The option button Caption property is used to pass on the value from the
option selected. For example, if you have three option buttons labeled Red,
Yellow, and Blue, the value “Red,” “Yellow,” or “Blue” will be passed
depending on the user selection. You need to make the caption match the
data type of the destination contextual object field (the table column in the
CeFO database that the option button group is populating).

Option buttons can have source and destination contextual objects:

• The optional source link can display a character string stored in a
contextual object field as the option button caption.
• The destination link saves the caption of the option button that is
selected. Associated option buttons all share the same destination
contextual object, which is generally a field in the CeFO database.

156 Chapter 8
 The Option Button Control

Grouping Option Buttons

If option buttons are placed on the form in consecutive operations, they are
automatically associated with each other. If option buttons are not placed in
a consecutive fashion and they are meant to be associated with each other,
use the Edit > Associate Controls command to make them consecutive in the
tab order. See Changing the Tab Order on page 103.

Grouped option buttons should also be placed next to each other, to help the
user understand the association.

Make sure the Group Items property of the buttons contains the same value.
Adding the buttons sequentially should ensure this.

Adding Option Buttons

To add a group of option buttons
1. Open a form.
2. Add the option buttons.
3. For each button, specify the same values for the Destination Contextual
Object and Destination Field Name properties.
The Destination Data Type property is read-only, and changes based on
your other selections.
4. Make sure all the option buttons are listed in the dropdown list for the
Group Items property.
If they aren’t all listed, select all the option buttons that you wish to
group and use Edit > Associate Controls.
5. Set the tab order for the option buttons using the Control Inspector.
Make the numbering contiguous among the option buttons so that the
user progresses in the correct order when using the Tab key to change
selections.

Input Controls 157

The Option Button Control

Option Button Properties

Table 23 lists the special properties of the option button control. (For a list of
the common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 23 Properties of the option button control

Property Type Property name Description

Appearance Caption Text string to be displayed next to the option button. If you want
to use a contextual object as the source of the text string, leave
this field blank. User selection passes this value back to the
database.
Behavior Default The option button is selected when the form is posted in CeFO
applications.
Enabled If set, the user can interact with the control; otherwise the control
is disabled when the form is posted.
Enable On If set, this control remains enabled after a currency conversion
Currency Convert occurs.
Data Destination Contextual object used to store the value of this option button.
Contextual Object The contextual object must contain a string data type.
Destination Field Field name in the contextual object used to store the value of this
Name option button.
Destination Data (read-only) Data type of the destination contextual object.
Type
Source Contextual (optional) Name of contextual object used as the source of the
Object text string that appears next to the option button. The contextual
object must be a string data type.
Source Field Name Contextual object field used as the source of the text string that
appears next to the option button.
Source Data Type (read-only) Data type of the source contextual object.
Misc Group Items Names of option buttons grouped with this one. Grouped option
buttons specify a set of options. Use Edit > Associate Controls to
group them.
Position AutoSize Yes or No. Setting this to Yes causes the control to resize based on
the length of the caption text. AutoSize is useful if you need to
translate custom CeFO forms into another language where the
translated form labels and captions require longer words than in
the original language.

158 Chapter 8
 The Text Box Control

The Text Box Control

A text box (also called an edit field) gives users the ability to enter or view
text information. You can enter only one line of information in an text box. If
you need more than one line, you must use a multiline text box.

You can also use an text box to display a value. For example, you can use a
text box to display a count of records. Be sure to make the text box read-only.
However, often a label is a better control to use for cases such as this.

Four properties control the way that a text box is used:

• Required: A required text box forces users to enter data before closing a
form. Not all forms support required text boxes. Forms that support required
fields display the required field in yellow when viewed in the CeFO application,
or when you use Play Form in the UI Editor.

NOTE: To be set as required, a text box must be on the parent form or the
default tab. For example, you cannot make the District text box (located on the
Support Info tab of the Site form) a required text box.

• Read-only: A read-only text box prevents users from typing into the
field. Users can, however, copy information from read-only text boxes
and paste them into other fields or applications.
• Password: A password text box hides the entered text. Asterisks (*)
appear instead of the actual text.
• Type: The type of the text box determines what kind of data the text box
accepts and how that data is displayed. See Text Box Types on page 160 for
more information.

Figure 80 shows examples of text boxes.

Input Controls 159

The Text Box Control

Figure 80 Examples of text boxes

Required text box Read-only text box

Text box

DateTime
text box
with dropdown
Calendar

Text Box Types

The text box control is capable of accepting both formatted and unformatted
data. By default, the text box control accepts unformatted text. However,
you can set up the control to accept one of three types of formatted data:
currency, date/time, and masked input data.

To set the type of data (formatted or unformatted) accepted by the text box
control, choose the appropriate value from the Type property’s dropdown
list. The following sections describe how the text box behaves for each type
of formatted data.

160 Chapter 8
 The Text Box Control

Currency Text Box

A currency text box stores monetary values in the local currency. The text
box uses the system locale information to format values with the
appropriate currency symbol and punctuation.

At run time, the user can choose to convert information from the local
currency to a different currency using the application interface. When this
happens, the application converts all of the values in the relevant currency
text boxes to the new local currency. After a conversion, many form-related
controls are disabled to prevent the modification of the converted values.
However, you can set the Enable On Currency Convert property of a control
to enable it after a conversion.

Date/Time Text Box

A date/time text box stores a date or time value. The text box uses the
settings of the local machine to format the date or time value appropriately.
You can type new dates into the text box or use the attached arrows to
increment or decrement the date values. Figure 81 shows a sample date/
time text box.

Figure 81 Entering a date with the date/time text box control

DateTime text box

with Calendar
property disabled

DateTime text box

with Calendar
property enabled

Input Controls 161

The Text Box Control

After you set the text box Type property to DateTime, you can set up the text
box to show either the date only or both date and time. In addition, you can
specify whether it has a dropdown calendar or not.
• To enable or disable the dropdown calendar, set the Calendar property to
Yes or No.
• The Destination Data Type property determines whether the text box has
the date only, or the date and time. This is a text entry field which only
accepts values “date” or “date only display”.

Mask Edit Text Box

A mask edit text box accepts formatted data that matches a mask string.
When you specify this type of control, you must also specify the string to use
as the input mask. See Using the Input Mask Property on page 165 for more
information.

Entering Default Text

To show a default value in an text box, you must update the default value in
the CeFO schema.

NOTE: Entering text in the Text property field displays default text within the
User Interface Editor, but it does not appear in a CeFO application.

To update the default value in the CeFO database schema

1. Start the CeFO Data Dictionary Editor (ddedit) and connect to the
database that you want to update.
2. In the Data Dictionary Editor, use the Save command to export the
schema from the database to a schema file.
3. Open the resulting schema file using a text editor.
4. For the field to update, specify the default using the syntax
DEFAULT=value.
5. In the Data Dictionary Editor use the Apply Changes command to apply
the schema changes to the database.

See the Data Dictionary Editor Online Help for more information on using the
CeFO Data Dictionary Editor.

162 Chapter 8
 The Text Box Control

Text Box Properties

Table 24 lists the special properties available for the text box control. (For a
list of the common properties supported by all controls, see Common
Properties of Controls on page 99.)

Table 24 Behavior properties of the text box control

Property Type Property name Description

Appearance Text Enter a label for the text box that appears in the User Interface
Editor only. Text that you enter here does not appear in CeFO
applications.
Format Concatenates text for display. See Using the Format Property on
page 164 for more information.
Input Mask Specifies the format of user data. This property is available only if
the type of the text box is “Input Mask.” See Using the Input Mask
Property on page 165 for more information
Max Length The number of characters the user can enter. Specify the value 0 to
let the user enter the maximum number of characters specified by
the field length in the CeFO database schema.
Behavior Enable on Currency If set, this control remains enabled after a currency conversion
Convert occurs.
Password If set, the control displays an asterisk (*) for each character typed
by the user. Use this technique for security or protection
purposes.
ReadOnly Do not allow users to enter data in the text box.
Required If set, force the user to enter data into the control before closing
the form. Not all forms support required text boxes. .
Type Indicates the type of information stored in the text box: Currency,
DateTime, Mask Edit, or Text. See Text Box Types on page 160 for
more information.
Calendar Enabled if the value of the Type property is DateTime. Setting this
to Yes shows a dropdown button on the right side of the control
instead of the updown button that is normally displayed.
Clicking on the dropdown shows the calendar to select the date
and time.
Currency Convert If set, the value in the text box is automatically converted when
the user initiates a currency conversion. If not set, the value is not
converted. This property is only available for currency text boxes.

Input Controls 163

The Text Box Control

Table 24 Behavior properties of the text box control (Continued)

Property Type Property name Description

Data Destination Indicates the contextual object that is used to store the
Contextual Object information in this text box.
Destination Field Contextual object field name to use to store the information in this
Name text box.
Destination Data (read-only except when Type is DateTime) Data type of the
Type destination contextual object. If Type is DateTime, enter text of
“date” to show the full date time, or “date only display” to show
only the date.
Currency Data Type (read-only) This property contains the value Yes if the contextual
object field displays a currency value; otherwise it contains the
value No.
Misc Context Menu Click to associate a context-sensitive menu with the control. See
Adding Context-Sensitive Menus for Controls on page 106 for more
information.

NOTE: There is a 32K limit for text box controls within CeFO forms. Even if you
set the Max Length property to 0, this 32K limit still applies to CeFO users.

The position properties define the size and position of the control. See
Common Properties of Controls on page 99 for a complete list of these
properties.

Using the Format Property

The Format property concatenates text for display purposes.

NOTE: You can concatenate two fields as long as they are from the same contextual
object. For example, you can concatenate part number and model number. You
cannot, however, concatenate part name and part number in the New Case window
because they are fields from different contextual objects.

164 Chapter 8
 The Text Box Control

The syntax for concatenating (string) fields is:

%^field1$s %^field2$s %^fieldn$s

where:
%^ indicates a field delimiter
fieldn is the contextual object field name
$s indicates the field is a string format

For example,
%^first_name$s%^middle_name$s%^last_name$s

returns
JohnAndrewDoe

You can place characters, such as a comma or a space, between the fields. For
example,
%^last_name$s, %^first_name$s %^middle_name$s

returns
Doe, John Andrew

Using the Input Mask Property

The Input Mask property contains the expected format of the data entered
by the user. You can use this property in situations where you know the
expected format of user data such as telephone numbers and zip codes. The
input mask controls which characters the user can type and specifies the
formatting to be applied to those characters.

To construct an input mask, you use a combination of regular characters and

special formatting characters. Table 25 lists the formatting characters
recognized by the Input Mask property.
Table 25 Formatting characters for input masks

Character Input allowed for that character

# Numeric data (0-9)
A Alphanumeric characters (0-9, a-z, A-Z)
? Alphabetic characters (a-z, A-Z)
U Alphabetic characters (a-z, A-Z). Characters are forced
to uppercase (A-Z).

Input Controls 165

The Text Box Control

Table 25 Formatting characters for input masks (Continued)

Character Input allowed for that character

L Alphabetic characters (a-z, A-Z). Characters are forced
to lowercase (a-z).
& Any printable character
\ Escape character. Use this character to interpret one of
the preceding characters as a literal instead of as a
mask character.
(other) A literal character inserted in the string when it is
displayed.

When constructing your input mask, you must know the maximum number
of characters the user may need to type. Each formatting character
corresponds to a single character. Thus, to specify a 10-digit telephone
number (including area code), you could specify the following mask string:
(###) ###-####

Although the input mask imposes a maximum limit on the number of

characters the user can type, it does not impose a minimum limit. Thus, the
following input mask allows the user to type an optional 4-digit extension:
(###) ###-#### [####]

If the user does not have an extension, then the last four digits can be
omitted. Thus, the text box might display something like the following:
(919) 321-6186 [ ]

The parenthesis and hyphen in the preceding examples are literals that
appear only in the text box control. The user does not need to type these
literals and they are not part of the value stored in the contextual object.
Their only purpose is to provide visual formatting for the data entered by
the user.

Although the input mask limits the types of characters a user can type, it
does not validate the data entered by the user. Thus, if you have an input
mask of the form ##/##/## for specifying dates, the input mask allows the
user to enter a value such as 99/99/99. Your application is responsible for
validating the contents of the text box and for reporting appropriate errors.

166 Chapter 8
 The Multiline Text Box Control

The Multiline Text Box Control

Multiline text boxes allow uses to enter or view text information. Multiline
text boxes are used to accept multiple lines of user input or display multiple
lines of information. Common examples of multiline text boxes in CeFO
applications are user notes or comments stored with the record, for example,
log notes or case history for a case.

IMPORTANT: Do not define a default button for forms that contain multiline text
boxes, because this will prevent users from using carriage returns when entering
text in those fields.

Types of Multiline Text Boxes

Three properties control the way that a multiline text box is used:
• Required: A required multiline text box forces users to enter data before
closing a form. A user-selected color appears around required multiline
text boxes as a visual indication.

NOTE: To be set as required, a multiline text box must be on the parent form
or the default tab’s child form. For example, you cannot make the District text
box (located on the Support Info tab of the Site form) a required field.

• Read-only: A read-only multiline text box prevents users from typing in

the field. Users can, however, copy information from read-only text boxes
and paste them into other fields or applications.
• Password: A password multiline text box hides the entered text.
Asterisks (*) appear instead of the actual text.

Figure 82 shows a form containing multiline text boxes.

Input Controls 167

The Multiline Text Box Control

Figure 82 Examples of multiline text boxes

Multiline text boxes

Entering Default Text

If desired, you can display default text in a multiline text box. Use the same
procedure as for text boxes, which is described in Entering Default Text on
page 162.

Using Find and Replace

Multiline text boxes support string find and replace. If the multiline text box
is read-only, you can search for a string, but not replace it.

NOTE: You need the richedit20.dll in order to use the find and replace
feature (it is not enabled or disabled with a property). Contact your system
administrator for more information about obtaining this .dll file.

To search for a string, click in the multiline text box, click the right mouse
button, and then click Find. In the window that appears, enter your search
criteria and click Find Next.

168 Chapter 8
 The Multiline Text Box Control

Figure 83 Searching for strings in a multiline text box

1
In the CeFO application,
right-click in the multiline text box.

2
Choose Find.

Use the Replace dialog box

to find a specified string and
3 replace with the desired
string.

Multiline Text Box Properties

Table 26 lists the special properties of the multiline text box control. (For a
list of the common properties supported by all controls, see Common
Properties of Controls on page 99.)

Input Controls 169

The Multiline Text Box Control

Table 26 Properties of a multiline text box control

Property Type Property Name Description

Appearance Text Enter a label for the multiline text box that appears in the User
Interface Editor only. Text that you enter here does not appear in
CeFO applications.
Format Concatenates text for display. For more information, see Using
the Format Property on page 164.
Input Mask Not used.
Max Length The number of characters the user can enter. Set Max Length to
0 so as not to restrict the user.
Number of Lines (read-only) Calculates the number of lines that can be displayed
in the multiline text box based on the size of the multiline text
box.
Behavior Enable On If set, this control remains enabled after a currency conversion
Currency Convert occurs.
Password Displays asterisks (*) instead of the actual entered text. Used for
security or protection purposes.
ReadOnly Prevents users from entering data in the multiline text box.
Required Forces users to enter data before closing the form. Not all forms
support required text boxes.
Data Destination Contextual object used to store the information in the multiline
Contextual Object text box. The contextual object must be a string data type.
Destination Field Contextual object field name used to store the information in
Name the multiline text box.
Destination Data (read-only) Data type of the destination contextual object.
Type
Currency Data Type (read-only) This property contains the value Yes if the
contextual object field displays a currency value; otherwise it
contains the value No.
Misc Context Menu Click to associate a context-sensitive menu with the control. See
Adding Context-Sensitive Menus for Controls on page 106 for more
information.

170 Chapter 8
 The List Box Control

The List Box Control

NOTE: The list box control can be used only if you start the User Interface Editor
with the -cb option.

A list box allows users to select an item from a scrollable list. List boxes do
not allow multiple selection of items; the user can select only a single item.

Figure 84 shows an example of a list box control.

Figure 84 Example of a list box control

List box

A list box has no self-labeling abilities. If you need to label this control, you
must place a label control next to it.

You can use the List Items property to define the items in the list, as shown
in Figure 85, or use a source contextual object.

Input Controls 171

The List Box Control

Figure 85 Using the List Items property to define the items in the list

1
Right-click the list
box to show the
Properties
window.

2
In the Properties window,
click the ellipsis (...) next to
List Items to define the
items in the list.

3
Enter the items to be
displayed in the list.

4
Select an item and click Up
or Down to change the
order.

Using List Boxes in Query Forms

When using the list box control as part of a CeFO query form, set the query
property and define the schema path to the data.

The Case Query Edit has a Property list box used as part of the query
function, as shown in Figure 86.

172 Chapter 8
 The List Box Control

Figure 86 Using list boxes in query forms

This list box is

used as part of
the query.

Query
property is set
to Yes.

Path contains the CeFO relation to use in

the query.

Input Controls 173

The List Box Control

List Box Properties

Table 27 lists the special properties of the list box control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Table 27 Properties of the list box control

Property Type Property Name Description

Behavior Enabled If set, the user can interact with the control; otherwise, the
control is disabled when the form is posted.
Enable On If set, this control remains enabled after a currency conversion
Currency Convert occurs.
Data Destination Contextual object to store the selected item. The contextual
Contextual Object object must be a string data type.
Destination Field Contextual object field to store the selected item.
Name
Destination Data (read-only) Data type of the destination contextual object.
Type
Source Contextual (optional) Contextual object to use as the source of the items to
Object be displayed in the list. The contextual object must be a list data
type.
Source Field Name Contextual object field used as the source of the items in the list.
Source Data Type (read-only) Data type of the source contextual object.
Misc List Items Opens the Columns Property window, used to define the items
in the list.
Query Determines whether this list box is used as a property on an edit
query form. Selecting this option enables the Path column in the
List Items window.

174 Chapter 8
 The Dropdown List Box Control

The Dropdown List Box Control

Dropdown list boxes are used to present many user options. The user can
select only one item; dropdown list boxes do not allow multiple selections.

NOTE: There is a limit of 60 dropdown list boxes per form.

A dropdown list box has no Caption property (self-labeling property)

associated with it. If you want to label this control, you must place a Label
control next to it.

Figure 87 shows examples of dropdown list boxes.

Figure 87 Example of dropdown list boxes

Dropdown list boxes

let the user select from a
list.

Input Controls 175

The Dropdown List Box Control

Types of Dropdown List Boxes

You can define three types of dropdown list boxes:
• CeFO list: loads the list items from the source contextual object.
• Static list: gives you the ability to define the list items in the Property
window of the dropdown list box. You can change the items in a static list
only through the User Interface Editor.
• Pop-up list: uses the lists and values defined in the Policies and
Customers application.

IMPORTANT: Do not edit any CeFO list or Static list dropdown list boxes that
currently exist in CeFO forms. Both types have inherent logic behind them and
may not function properly if changed.

CeFO List Dropdown List Boxes

CeFO lists are provided by CeFO. Some CeFO lists can be updated in the
Policies and Customers application (for example, the ClearQuality Status
Codes list). Other CeFO lists cannot be changed (for example, the Type list in
the Site window).

Figure 88 shows CeFO dropdown list boxes in the New Change Request
form, as seen in the CeFO application.

176 Chapter 8
 The Dropdown List Box Control

Figure 88 CeFO list dropdown list boxes

These CeFO list

dropdown list boxes
can be updated in
Policies and Customers.

More Information: For more information about the Policies and Customers
application, see the ClarifyCRM Policies and Customers Help.

ClearBasic code can be written to fill the CeFO list dropdown list box with
values.

Static List Dropdown List Boxes

Static lists are defined by the List Items property. Static list items cannot be
changed in the Policies and Customers application. Figure 89 shows how to
create a static list.

Input Controls 177

The Dropdown List Box Control

Figure 89 Creating a static list

1. Choose
Static List as
the list type.
3. Enter the list values in the
2. Click List Items. Item column.

NOTE: When changing a dropdown list box to a static list, relations previously
supported by the dropdown list box are no longer supported.

User Data Column

You can use the user data column to map the data used in the destination.
For example, the Contracts Query Edit window uses a static dropdown list
box for sorting the results.

Figure 90 shows an example of a static dropdown list box.

178 Chapter 8
 The Dropdown List Box Control

Figure 90 Static dropdown list box example

The Item column lists what the user sees when they click this dropdown list
box. The User Data column lists the data that is used (or stored) when a user
chooses an item. In this example, if the user sorts by Administrator, then
contract2admin(1):login_name is used as the sorting criteria.

You can also use the User Data column to store values in the database that
are different from the ones displayed. This requires a ClearBasic code
license.

Figure 91 Storing non-displayed values in the User Data column

In the example shown in Figure 91, if a user selects “Light Red,” then 06322
is stored in the database.

Input Controls 179

The Dropdown List Box Control

Pop-up List Dropdown List Boxes

Pop-up list dropdown list boxes are defined and modified through the
Pop-Up List window of the Policies and Customers application.

More Information: For more information about the Policies and Customers
application, see the ClarifyCRM Policies and Customers Help.

Pop-up list dropdown list boxes can be single-level or hierarchical. A

single-level popup list dropdown list box is a typical pop-up list where the
selection of an item does not affect any other object in the window. In a
hierarchical pop-up list dropdown list box, the item selected in one pop-up
list determines the items that appear in other pop-up lists.

For example, the New Change Request window in the ClearQuality

application (shown in Figure 92) uses a hierarchical popup list to describe
the system configuration where the problem was found.
• Found on CPU identifies the computer on which the problem occurred.
• Operating System identifies the operating system used by the computer.
• System Memory identifies the amount of system memory available on
the computer.

The items in the Operating System and System Memory pop-up lists are
based on the item selected in the CPU list. For example, if PC is selected as
the CPU, the operating system choices are Windows 3.0, Windows 3.1, and
Windows 95.

180 Chapter 8
 The Dropdown List Box Control

Figure 92 Hierarchical pop-up list example

The item selected in the

CPU pop-up list
determines which choices
are available in the
Operating System and
System Memory
pop-up lists.

Hierarchical pop-up lists are implemented with two or more dropdown list
boxes. Each dropdown list box represents a specific level. See Figure 93 for
examples of hierarchical pop-up lists.

NOTE: You can have up to five levels of hierarchy.

Input Controls 181

The Dropdown List Box Control

Figure 93 Hierarchical pop-up lists

The list name (Name property of the dropdown list control) is defined in the
User-Defined Pop-Up List window of the Policies and Customers
application. Figure 94 illustrates the correlation between the user-defined
pop-up list items in Policies and Customers, and the dropdown lists on the
New Case form as it appears in the CeFO ClearSupport application.

NOTE: You must have a default value on each level in the Pop-Up List window.
Otherwise you cannot select this level in the User Interface Editor.

182 Chapter 8
 The Dropdown List Box Control

Figure 94 Identifying which pop-up list to use

The popup List Name property matches the

list name shown in the User-Defined Pop-Up List
window.

There are two methods for determining which item in the list is selected:
• Store the item string in the destination contextual object.
• Use the Long Value property to store the positional index of the entry in
the destination contextual object. The Long Value property is available
only when using the User Interface Editor with the -cb option.

For example, Figure 95 shows a dropdown list box with three entries. The
second entry is selected. If the Long Value property is not used, b is stored in
the contextual object. If the Long Value property is used, 2 is stored in the
contextual object (positional indexes start with 1).

Input Controls 183

The Dropdown List Box Control

Figure 95 Recording the option button that is selected

Positional index: 1
Positional index: 2
Positional index: 3

Dropdown List Box Properties

Table 27 lists the special properties of the dropdown list box control. (For a
list of the common properties supported by all controls, see Common
Properties of Controls on page 99.)

Figure 96 Properties of the dropdown list box control

Property Type Property Name Description

Behavior Enabled If set, the user can interact with the control; otherwise the control
is disabled when the form is posted.
Enable On If set, this control remains enabled after a currency conversion
Currency Convert occurs.
Data Destination Context Contextual object used to store the value of this dropdown list
Object box.
Destination Field Contextual object field name used to store the value of this
Name dropdown list box. The contextual object field must be either a
string or a long data type.
Destination Data (read-only) Data type of the destination contextual object.
Type
Source Contextual For CeFO list types only. Contextual object used as the source of
Object the items in the list. The contextual object must be a of primitive
type List.
Source Field Name Contextual object fields used as the source of the items in the list.
Source Data Type (read-only) Data type of the source contextual object.

184 Chapter 8
 The Dropdown Combo Box Control

Figure 96 Properties of the dropdown list box control (Continued)

Property Type Property Name Description

Misc Ignore Change If set, the user is not prompted to save changes when only the list
box value is changed in a form.
List Items For static list types only. Click to enter or modify the list items.
List Type Specifies the type of the dropdown list box: CeFO, Static, or
Popup.
Long Value If set, the control stores the index of the selected list item in the
destination contextual object.
Object Column Set to No by default. If this control is associated with a Select CBX
control, set this property to Yes.
Popup List Name For pop-up list types only. Name of the list in the User-Defined
Pop-up List window that this dropdown list box references.
Level Name For pop-up list types only. Name of hierarchical level in the
Pop-up List window that this dropdown list box references.

The Dropdown Combo Box Control

A dropdown combo box gives users the ability to choose an item from a list
of choices in a menu or enter text. Dropdown combo boxes do not allow
multiple selection of items; the user can select only a single item.

Figure 97 shows an example of dropdown combo box controls.

Input Controls 185

The Dropdown Combo Box Control

Figure 97 Examples of dropdown combo box controls

Dropdown
combo boxes

A dropdown combo box control can have source and destination links to
contextual object fields.
• The optional source contextual object defines the items in the list. You can
also use the List Items property to define the items in the list if a source
contextual object is not desired.
• The destination contextual object identifies the selected item from the list.
A dropdown combo box has no Caption property associated with it. If you
want to label this control, you must place a Label control next to it.

Dropdown Combo Box Properties

Table 27 lists the special properties of the dropdown combo box control. (For
a list of the common properties supported by all controls, see Common
Properties of Controls on page 99.)

186 Chapter 8
 The Dropdown Combo Box Control

Figure 98 Properties of a dropdown combo box control

Property Type Property Name Description

Behavior Required Forces users to select an item in this list before closing the form.
Not all forms support required controls.
(If you have a ClearBasic license, you can create your own forms
and have those forms use required fields.)
Data Destination Contextual object used to store the selected item in the list. The
Contextual Object destination contextual object must be a string data type.
Destination Field Field name of the contextual object that stores the selected item.
Name
Destination Data (read-only) Data type of the destination contextual object.
Type
Source Contextual (optional) Contextual object containing the items to be displayed
Object in the list. The source contextual object must be a primitive List
data type.
Source Field Name (optional) Field name of the contextual object containing the
items to be displayed in the list.
Source Data Type (read-only) Data type of the source contextual object.
Misc List Items Opens an Item Properties window in which you define the items
to display in the list. Leave this blank if you want to use a source
contextual object for the list of items.

Using the List Items Property

Click the List Items property to display the Item Properties window. From
this window, you can define the items to appear in the dropdown combo
box (see Figure 99).

Input Controls 187

The Slider Control

Figure 99 Using the Item Properties window to define list items

Type list items here.

Press Tab to enter
a new list item.

Click Up or Down to
arrange items in the list.
Or click Delete to remove
an item from the list.

Click OK when the list is complete.

The Slider Control

The slider control is used to select a discrete value from a given range. This
provides a visual cue to the user, for whichever value is selected.

You can also use the slider to control the input of values for a given
application. For example, to set a limit on the number of billable hours
charged to clients, use a slider control to select the amount of billable hours
from a given range.

Figure 100 shows an example of a slider control.

Figure 100 Example of a slider control

Slider

To create a slider control

1. Open the form.
2. Place the slider.
3. Add a label.
4. Set the range in the Properties window.
5. Add labels for the range on the form.

188 Chapter 8
 The Slider Control

Keyboard Navigation with the Slider Control

You can use the Up and Down Arrow keys to move the slider up and down,
when the slider is oriented vertically. Similarly, you can use the Left and
Right Arrow keys to move the slider left and right, when the slider is
oriented horizontally.

Slider Control Properties

Table 27 lists the special properties of the slider control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Figure 101 Properties of the slider control

Property Type Property Name Description

Appearance Orientation Orients the slider control horizontally or vertically.
AutoTicks Determines whether tick marks (demarcation marks) are drawn
or not.
TickFrequency Sets the frequency of tick marks on a slider control, relative to the
control’s range. (A lower number means more ticks; a higher
number means fewer.)
TickStyle Sets the positioning of tick marks on the slider control.
Behavior Enabled If set, the user can interact with the control; otherwise the control
is disabled when the form is posted.
Data Destination Name of contextual object to be updated by the slider control.
Contextual Object The contextual object must be a Long integer type.
Destination Field Contextual object field to be used by the slider control.
Name
Destination Field (read-only) Data type of the destination contextual object.
Type
Misc Max Maximum value of the scroll range for the slider control.
Min Minimum value of the scroll range for the slider control.

Input Controls 189

The Updown Control

The Updown Control

The updown control allows users to increment or decrement the value of an
associated “buddy” control. You can also use updown controls to rotate
through a series of items, such as the tabs associated with a frame (using
ClearBasic).

You link the buddy control to the updown control by setting the
BuddyControl property in the Properties window. The buddy control must
be a text box control.

To the user an updown control appears as a pair of arrow buttons. If the

updown control is linked to a buddy control, you can use the Alignment
property to position the updown control in relation to the buddy control as
follows:
• Set the Alignment property to AlignmentLeft or AlignmentRight if you
want the updown control and the buddy control to appear as a single
control to the user.
• Set the property to UnAttached if you want the two controls to appear as
separate controls.

Figure 102 shows an example of an updown control.

Figure 102 Example of an updown control

Text box with

updown control

Keyboard Navigation with the Updown

Control
In addition to mouse clicks on the updown control’s arrow buttons,
application users can use the Up and Down Arrow keys on their keyboards.
If the updown control is set up horizontally (set with the Orientation
property), then the Left and Right Arrow keys can be used.

190 Chapter 8
 The Updown Control

Using the Updown to Rotate Through Tabs

The updown control receives UpClick and DownClick events. The tabs on
a form can be selected by setting the Value property of the tab control to 1. In
the Form_Load routine, build a list of the tab controls on the form, order
them by their ID property, and then track which tab is currently active.
When the user clicks the updown control, use the UpClick and DownClick
events to activate that next tab in line.

Updown Control Properties

Table 27 lists the special properties of the updown control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

Figure 103 Properties of the updown control

Property Type Property Name Description

Appearance Orientation Aligns the control horizontally or vertically.
Behavior Enabled If set, the user can interact with the control; otherwise the control
is disabled when the form is posted.
Wrap Allows the value to increment past the Max property and start
again at the Min property. Conversely, allows the value to
decrement past the Min property and start again at the Max
property.
Alignment AlignmentLeft: Positions the updown control next to the left
edge of the buddy control. The buddy control is moved to the
right and its width is decreased to fit the additional width of the
updown control.
AlignmentRight: Positions the updown control next to the right
edge of the buddy control. The buddy control is moved to the left
and its width is decreased to fit the additional width of the
updown control.
UnAttached: Draws the updown control as a separate control.
EditBuddy Yes or No, defaulting to No.
• No: Does not cause the control to set the value of the text in
the buddy window.
• Yes: Causes the control to set the value of the text in the buddy
window.
(Behavior) BuddyControl (Optional.) With this property you can specify the control name
of the buddy control. This control must be a text box control.

Input Controls 191

The Updown Control

Figure 103 Properties of the updown control (Continued)

Property Type Property Name Description

Misc Increment Sets the amount by which the updown control position, and the
buddy control value, change when one of its arrow buttons is
clicked.
Max Sets the maximum value of the scroll range for the updown
control.
Min Sets the minimum value of the scroll range for the updown
control.

192 Chapter 8
Chapter 9

The Grid and CBX Controls

In This Chapter
The Grid Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
The Select CBX Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212

193
The Grid Control

The Grid Control

NOTE: Grid controls can be added to a form only if the User Interface Editor was
started with the -cb option. If the User Interface Editor was not started with the
ClearBasic option, you can edit only existing grid controls.

Grids (also called custom lists or field arrays) are tables that display
information in a series of rows and columns. You can use grids to display
database records or custom data. You can define grids which let the user edit
the data displayed in the grid.

Figure 104 shows an example of a grid control.

Figure 104 Example of a grid control

Grids

Simple Grids and Multigrids

There are two types of grids:
• A simple grid displays selected data from a single database table or view.
• A multigrid can switch between displaying data from different database
tables or views, based on selections the user makes on the form.

194 Chapter 9
 The Grid Control

In either case, you can’t show data from two tables in the grid at the same
time. If you need to do that, you can create new views in the CeFO database,
and associate the grid with each view using extended contextual objects.

Alternatively, you can use User Defined Types in ClearBasic. See the
ClearBasic Customization Guide for more information.

Figure 105 Example of a multigrid control object

multigrid

Grids and Contextual Objects

A simple grid requires two contextual objects:
• The source contextual object references a CeFO database object or view,
and contains a list of records with the column information from the
database object or view. It stores the records currently displayed in the
grid. You can use ClearBasic to create a User Defined Type of source
contextual object.
• The destination contextual object is of type List and stores the indexes of
the rows selected from the table.

The Grid and CBX Controls 195

The Grid Control

You must specify different source and destination contextual objects for each
database object or view that is displayed in a multigrid. For multigrids,
some of the properties and definitions that are normally handled through
the Grid control properties window are set through the Extended Contextual
Objects window instead.

Refer to the ClearSales Customization Guide for a description of how CeFO has
implemented multigrids on the baseline multipane forms.

Grids and Contextual Object Types

The source contextual object for a grid control must be specified as a list of
records in the Edit Contextual Objects window (see page 229). In this
window, you must associate the contextual object with a database object
using the Database Object Type selection, and then use the Sub Type
dropdown list to specify Record List.

Grids and Column Links

Each column in a grid uses a source link to display information from a
specific field in the same contextual object. This contextual object can be
either a table or a view in the database, or it can be a User Defined Type in
ClearBasic.

Figure 106 shows grid and column links.

196 Chapter 9
 The Grid Control

Figure 106 Grid column links in the Pop-Up List window

The grid column List Name is

linked to the title field of
the dlist source contextual
object.

Adding a Grid to a Form

To add a grid to a form
1. Open the form.
2. Place the grid on the form.

The Grid and CBX Controls 197

The Grid Control

3. Add a source contextual object that is a database object, specified as a list

of records.
Press F3 to open the Edit Form Contextual Objects window. Complete as
follows:
• Name is usually something like lorObject, but that naming
convention is optional.
• Click Database Object Type and select the desired database object by
name from the list. Click Use/Done to return to the Edit Form
Contextual Objects window.
• Specify any Caption you like.
• Select Record List as the Sub Type, and click Add.
See Adding Contextual Objects to a Form on page 229 for more information
on using the Edit Form Contextual Objects window.
4. Add a destination contextual object of type list.
Follow the same procedure as in the previous step, using these values:
• Name is usually something like losObject, but that naming
convention is optional.
• Specify a Database Object Type of List.
• Specify any Caption you like.
• Select Long as the Sub Type, and click Add.
5. Click Done to close the Edit Form Contextual Objects window.
6. Right-click the grid and choose Grid Wizard from the context menu.
The Grid Wizard window appears. The dropdown selection box lists all
the contextual objects associated with the form.
7. Choose the source contextual object you created in Step 3 from the
dropdown selection list.
After you make your selection, the Grid Wizard window closes. All the
columns from the associated database object appear on the grid, and a
list of new column properties appears in the Properties window for the
grid.

198 Chapter 9
 The Grid Control

8. Open the Column Properties window.

In the Properties window for the grid control, click the ellipsis (...) under
the property titled Columns. The Column Properties window appears.
This window is a shortcut form that shows a subset of the same
information shown in the Column Properties area of the grid’s Properties
window.
9. Specify how each column should be displayed in the grid.
NameName of column to be displayed
ContextDropdown selection list showing contextual objects associated
with the form. The source contextual object should already show
whatever object you specified in the Grid Wizard in Step 7. Do not
change this selection.
Field NameName of the column in the database object (source contextual
object) from which to obtain the value displayed in the grid.
VisibleSpecify whether this column is visible in grid. Set to No to hide the
column.
Click OK to save your changes and return to the form. (Note that Data
Type, Justify, Width, and Fixed are explained in Table 30 on page 210.)
10. Edit the grid properties.
Right-click the grid control and set the MultiCObj property to No, and
choose as the Destination Contextual Object the contextual object that
you created in Step 4.
11. Implement other grid features as needed.
• If you want to make your grid columns editable, see Making the Grid
Editable on page 203.
• Review the complete list of grid and column properties later in this
section for information on other features you want to implement.

The Grid and CBX Controls 199

The Grid Control

Using the Grid Wizard

For non-multigrid controls, you can use the Grid Wizard command to create
columns in the grid. The Grid Wizard lets you select the source contextual
object, and then it adds a column to the grid for each field in that contextual
object.

You can add or remove columns at any time using the Columns property in
the Grid properties window. When you click it, a dialog box appears as
shown in Figure 106, listing each column and the type of data that column
contains. You can use this dialog box to rearrange, add, update, or remove
columns.

The following procedure shows how to use the grid wizard to create the grid
columns using the address source contextual object as an example. (The
corresponding CeFO database table is table_address.)

To add address columns using the Grid Wizard (example)

1. Add a grid control to a form and open the Properties window for the
grid, as shown in Figure 107.

Figure 107 Adding a grid to a form

2. Click the ellipsis (...) next to Edit Contextual Objects.

The Edit Form Contextual Objects window appears.

200 Chapter 9
 The Grid Control

3. In the Contextual Object Name field, type address.

This Name will appear whenever a dropdown selection list is used for
contextual objects, for example in Button Actions or the grid Property
window.
4. Click Database Object Type.
The Object Type Selection window appears, as shown in Figure 108.

Figure 108 Object type selection window

5. Select Address from the list and click Use/Done.

6. Select Record List as the Sub Type.
7. Click Add to add the address contextual object to the list of objects for the
form.
8. Click Done to close the Edit Form Contextual Objects window.
9. Select the grid; then click the right mouse button and select Grid Wizard.

The Grid and CBX Controls 201

The Grid Control

Figure 109 Selecting the Grid Wizard command

The Grid Wizard window appears, as shown in Figure 110.

Figure 110 Grid Wizard window

10. Choose address from the pulldown menu and click OK.
The fields in the address contextual object appear as columns in the grid
control, as shown in Figure 111.

Figure 111 Automatically creating columns in a grid

If needed, you can rearrange the columns or remove columns from the grid.

202 Chapter 9
 The Grid Control

Modifying Grid Columns

After you’ve used the grid wizard to insert the grid columns, you may need
to rearrange the columns or remove some columns. Use the Columns
property in the Properties window to edit grid columns.

To modify grid columns

1. Select the grid control and open the Properties window.
2. Click the Columns property.
The Column Properties window appears, as shown in Figure 112.

Figure 112 The Column Properties window

To select an entire
row, click the gray
box.
Select a row
and click Up or
Down to
arrange the
order.

3. To change the order, select a row and click Up or Down. To remove a

column, select the row and click Delete. To change other properties, such
as the column heading, select the entry and make your edits directly in
the cells of the grid.

More Information: For information about other column properties, see Column
Properties on page 209.

Making the Grid Editable

The rows and columns of a grid are read-only by default. However, if you
set the value of the grid’s Is Editable property to Yes, you can enable in-place
editing for the grid cells.

The Grid and CBX Controls 203

The Grid Control

NOTE: In-place editing requires ClearBasic code to validate and save grid changes.
For more information about programming with ClearBasic, see the various CeFO
documentation titles on ClearBasic.

In-place editing allows the user to select a cell and modify that cell directly,
without posting a separate dialog. When the user selects a cell, the grid
replaces the cell text with a control box that allows the user to modify the cell
contents. When the user is finished, selecting a different cell removes the
control and updates the grid display. Figure 113 shows a grid with a cell
being edited.

Figure 113 Editing the value in a cell

Cell being edited

with a dropdown
list box

Table 28 lists control types that are supported for in-place editing.

Table 28 Controls supported for in-place editing

Control Type Description

Checkbox This control is a popup list containing two choices: Yes and No.
Currency This control is a text box designed to handle currency values. It
uses the currency locale settings to display its value. See Currency
Text Box on page 161 for more information.
Date/time This control combines a button and text box for choosing and
displaying a date or time value. See Date/Time Text Box on
page 161 for more information.
Dropdown This control displays a list of choices from which to choose. The
combo box user can also type in new choices.

204 Chapter 9
 The Grid Control

Table 28 Controls supported for in-place editing (Continued)

Control Type Description

Dropdown list This control displays a fixed list of choices from which to choose.
box
Editbox This control is the standard text box control used to enter string
data.
Lookup This control combines a text box and two buttons. The first button
allows the user to select a record. The second button displays the
details of that record.
Requires ClearBasic code to implement the selection and display
functions.
Masked This control is a text box modified to accept formatted values. See
Editbox Using the Input Mask Property on page 165 for more information.

For each column in an editable grid, you must specify the type of control to
use when editing its cells. Depending on which control you select, you may
also need to specify additional options. See Column Properties on page 209 for
more information.

Creating a Multigrid
A multigrid is a grid control that uses multiple contextual objects.

IMPORTANT: If you are creating a custom version of a CeFO form that already
contains an editable multigrid, leave the grid editable in custom form versions.

To create a multigrid
1. Open the form that will display the multigrid.
2. Place a grid control, but don’t add any columns to it.
3. Make a note of the grid name.
4. Set the MultiCobj property to Yes.
This makes the grid into a multigrid. Some of the Properties listings
disappear. (They reappear in the Edit Extended Contextual Objects
window.)

The Grid and CBX Controls 205

The Grid Control

5. Add a set contextual objects to the form for each database table or view to
display in the multigrid.
For each database object or view that the grid displays, create the
following:
• One source contextual object for the table, specifying the table or view
name as the Database Object Type, and Record List as the Sub Type.
• One destination contextual object to hold the indexes of the selected
data, specifying a Database Object Type of List and a Sub Type of
Long.
Unlike a simple grid, you do not specify the source and destination
objects in the grid properties window. Instead, that is done in the
Extended Contextual Objects window. For now, make a note of the
names of each contextual object that will be used for the grid.
6. Locate the extended contextual objects for the grid in the Extended
Contextual Objects window.
With the form open, choose Edit > Extended Contextual Objects or press
F4. You should see one extended contextual object for each contextual
object associated with the form. They are listed in the order in which they
were added to the form, rather than alphabetically.
7. Enable the grid properties for each extended contextual object you want
to associate with the grid.
To enable grid properties, expand the extended contextual object node in
the treeview to show Properties and Methods, as shown in Figure 114.
Under Properties, select the top node with the key icon next to it.

Figure 114 Selecting the key property

Key

In the right-hand detail panel, select the Grid check box at the bottom, as
shown in Figure 115. This indicates that the extended contextual object is
used in the grid.

206 Chapter 9
 The Grid Control

Figure 115 Enabling the Grid check box

Grid

8. Specify the grid name.

The Grid Name Key/Value property for the extended contextual object
lets you specify the grid name. Enter the Grid Name property of the Grid
control with which this extended contextual object is associated.
9. Select the fields to display.
With the extended contextual object node expanded to show the
properties, each property listing corresponds to a field in the database
object or view.
For each column to display, select the node for that field from the
treeview and click the Grid check box in the detail panel on the right.
The icon next to the node listing in the treeview changes as shown in
Figure 116.

Figure 116 Selecting grid columns to display

Icon

10. Modify the field properties using the extended contextual object window.
Select the field node from the treeview to the left. The detail panel on the
right displays the properties for that field. Modify as needed.
11. Repeat Step 7 through Step 10 for each extended contextual object to
display in the multigrid.
12. Add a ClearBasic routine to set a default contextual object when the form
is loaded.
In the Form_Load routine, set the default contextual object of the grid to
load at runtime.

The Grid and CBX Controls 207

The Grid Control

13. Add form controls and associated ClearBasic code so the user can select
the other extended contextual objects associated with the multigrid.
The most likely controls to use would be a treeview or a dropdown list
control. For each of these, modify the ClearBasic code to process he user’s
Click event and set the new contextual object for the multigrid
appropriately.
Refer to Creating a Multigrid/MultiCBX Form on page 329 for a
step-by-step example of this process.

Grid Properties
Table 29 lists the unique properties of the grid control. The properties
associated with individual columns are discussed in Column Properties on
page 209.

Table 29 Properties of a grid control

Property Type Property Name Description

Behavior Append Rows For editable grids, specifies whether the user is allowed to add
new rows to the grid. If you enable this option, the Is Editable
property must be set to Yes.
Enable On If set, this control remains enabled after a currency conversion
Currency Convert occurs.
MultiCobj Specifies whether the grid uses multiple contextual objects or
not. If Yes, certain grid properties are lost and you must specify
them as part of the extended contextual object instead. Does not
display on the Edit Extended Contextual Object window.
MultiSelect Determines whether multiple selection is allowed.
Is Editable Specifies whether the user is allowed to modify the contents of
the grid. ClearBasic is required if you want to give users the
ability to save their changes.
Prompt On Save For editable grids, specifies whether your code should ask the
user before saving changes to the grid data.
Data Destination Contextual object (of List type) to store the indexes of the
Contextual Object selected item(s) in the grid control. Not used for multigrids.
Destination Field Contextual object field to contain the selected item(s) in the grid
Name control. Not used for multigrids.
Destination Data (read-only) Data type of the destination contextual object. The
Type destination contextual object must be a List data type.

208 Chapter 9
 The Grid Control

Table 29 Properties of a grid control (Continued)

Property Type Property Name Description

Misc Context Menu Click to associate a context-sensitive menu with the control. See
Adding Context-Sensitive Menus for Controls on page 106 for more
information. Does not display on the Edit Extended Contextual
Object window
Column Columns Displays Column Properties window. When you select a grid
Properties column, the properties below this item change to reflect the
attributes of the selected column. Not used for multigrids.
See Table 30 on page 210 for a description of column properties.

For a list of the common properties supported by all controls, see Common
Properties of Controls on page 99.

Column Properties
Each column in the grid has a set of unique properties that you can use to
adjust the appearance and contents of the column. You can adjust the width
of the column, its text justification, and the control type used to display the
column data. If the grid is editable, the control also indicates the type of
control used to edit the data.

To view the properties of a column (simple grid)

1. Open the form and right-click the grid to show the Properties window.
2. Select one of two options under the Column Properties.
• Click on the ellipsis (...) to show the Column Properties window
(page 203). This window lets you modify selected column properties
quickly for a number of columns.
• Click the Field Name under Column Properties and select the desired
field from the dropdown selection list. This lets you modify all the
column properties for a single field.

To view the properties of a column (multigrid)

1. Open the form and press F4 to open the Extended Contextual Object
window.
2. Expand the extended contextual object that contains the field whose
properties you wish to view.

The Grid and CBX Controls 209

The Grid Control

3. Select the field from the extended contextual object Property listing.
The properties for that field are displayed on the right.

In an editable grid, you must specify the control and properties used by each
column of the grid. For a simple grid, you can set the properties of a column
using the Properties window or the Column Properties window.

Table 30 lists the properties that apply to all columns (regardless of which
window you use to set them).

Table 30 Basic properties of each column in a grid control

Property Name Description

Name Column header name.
Context Source contextual object for this column’s data. (For extended contextual
objects, this is the Object value of the Key listing.) This dropdown list
shows all contextual objects associated with the form. However, for grid
controls, you should select a source contextual object representing
database objects that are Lists of Records (set the Sub Type to Record List
in Edit Contextual Objects window.)
Field Name Contextual object field that contains the data to be displayed. (In
extended contextual objects for multigrids, field names are listed in the
treeview in the left, rather than as a key/value property.)
Datatype Data type of the selected contextual object field. See Date/Time Text Box on
page 161 for special information on datetime displays.
Currency Datatype If set, the column applies currency formatting rules to its values.
Justify Text justification within the column. Select Left, Center, or Right.
Width Width of the column in pixels. This determines how wide the column is
when initially displayed. The user can resize the column in CeFO
applications.
Fixed If set, the column remains visible when the user scrolls the list to the
right.
Visible If set, the column is visible; otherwise, the column is hidden. The user
can hide and unhide columns.
Control Type Allows the user to specify the type of control to use in an editable grid
column. Controls types are:
• Datetime
• Dropdown Combo Box
• Dropdown List
• Lookup
• Mask Edit
• Text (combo box)

210 Chapter 9
 The Grid Control

Table 30 Basic properties of each column in a grid control (Continued)

Property Name Description

Calendar Enabled if Control Type is Datetime:
• Displays Calendar control if set to Yes
• Displays date and time if set to No
Max length Enabled if Control Type is Text. Specifies the maximum number of
characters the user can type.
ReadOnly If set to Yes, values in the column cannot be edited.
Required If set to Yes, the user must enter a value in this column before saving the
data.
List Type Enabled if Control Type is Dropdown List or Dropdown Combo Box.
Contains the type of the list (CeFO, Static, or Pop-up).
Input Mask Enabled if Control Type is Mask Edit. Contains the input mask string. See
Using the Input Mask Property on page 165 for more information.
List Name Enabled if List Type is Pop-up. Contains the name of the pop-up list.
ListItems Enabled if Control Type is a dropdown:
• If Control Type is Dropdown Combo, then a dialog is posted allowing
user to add items.
• If Control Type is Dropdown List and the List Type is Static, then a
dialog allows the user to add Item, User Data and Default.
Control Cobj Shows a list of contextual objects associated with the form. If the column
Control Type is dropdown list box or dropdown combo box, and the List
Type is a CeFO list, this property specifies the contextual object from
which to obtain the list data. Must be a primitive List type.
Control Field Name Shows a list of fields from the selected Control Cobj. For dropdown list
box and dropdown combo box controls with a CeFO list, this property
contains the field name from which to obtain the list data.
Control Datatype Shows the data type of the selected field identified by the Control Cobj
and Control Field Name properties.
Currency Convert If set, the value in the text box is automatically converted when the user
initiates a currency conversion. If not set, the value is not converted. This
property is available only if the column uses a currency text box control.

The Grid and CBX Controls 211

The Select CBX Control

The Select CBX Control

NOTE: You must start the User Interface Editor with the -cb option if you want
to add select CBX controls to a form. You do not need to specify this option to
modify existing controls.

The Select ClearBasic extension (Select CBX) control is a paged custom list
that adds query capabilities to a form. The Select CBX control supports the
creation of static queries that can be saved in the database and recalled
quickly using a dropdown list. The control also supports the creation of
dynamic queries, called ad hoc queries, which use information in the
associated grid to perform the query.

The Select CBX control works in conjunction with other controls to gather
query information and display the query results to the user. The CBX control
itself is not visible on the form when the CeFO client is run. Rather, it works
behind the scenes to manage and coordinate the functions of other controls
used for the query.

The following list gives a brief description of each of the controls associated
with the Select CBX:
• A “Find” button to initiate a query
• An “Edit Filter” button for users to create and modify filter sets
• A “Filter” dropdown list box containing the user-specified filters
• A “Select List” grid displaying the results of the query
The Select CBX control itself performs the query and coordinates the
interchange of data among these controls.

Figure 117 shows an example of a form with a Select CBX control, as well as
how the same form appears in the UI Editor.

212 Chapter 9
 The Select CBX Control

Figure 117 Example of a form with a Select CBX control

Form as it appears in the CeFO a pplication

Filter list

Find button

Edit Filter button

Select list

Select CBX control

Same form shown in the UI Editor

The Grid and CBX Controls 213

The Select CBX Control

NOTE: When creating forms that have select functions within tabs, the Select CBX
control must be placed on the parent form.

Creating a Select Form: Example

A select form is a form that uses a Select CBX control to retrieve records from
the database. The following example shows how to create a form and
configure it to use a Select CBX control.

To create a select form using bus_org (example)

1. Choose File > New > Form to create a new form.
2. Create the following contextual objects for the form, as shown in
Figure 118:
• OrgList (Database Object Type bus_org) stores the results of the
query.
• SelectionItem (Database Object Type List) stores the indexes of
the items selected from the list.
• FilterSetList (Database Object Type filterset) stores the filters
from the filter pulldown menu.
• FilterSetSelect (Database Object Type Long) stores the selected
entry in the filter dropdown list.

214 Chapter 9
 The Select CBX Control

Figure 118 Contextual objects for the example select form

3. Create the following controls on the form, as shown in Figure 119:

• A grid control (gridOrgList) to display the query results
• A dropdown list box control (ddlFilterSelect) to display the
available filters
• A command button control (cmdEditFilter) to post the Edit Filter
dialog. Specify Icon ID 1152 to show the pencil icon, and make the
Caption blank.
• A command button control (cmdOrgFind) with a caption of Find, to
initiate a query
These controls will be part of the Select CBX.
4. Create a few additional controls for the sake of making the form more
usable.
• A command button control (DONE) with a caption of Done, to close the
window
• A label for the dropdown list (lblFindOrg) with a caption of Find
Organization:

The Grid and CBX Controls 215

The Select CBX Control

Figure 119 Controls for the example select form

Command button control

Name = cmdEditFilter
Dropdown list box control Command button control
Name = ddlFilterSelect Name = cmdOrgFind

Label control
Name = lblFindOrg
Grid control
Name = gridOrgList

Done button control

Name = DONE

5. Place a select CBX control anywhere on the form and open the Properties
window for the select CBX control.
6. Click the Find property value and select the control that represents the
Find button (cmdOrgFind), as shown in Figure 120.

216 Chapter 9
 The Select CBX Control

Figure 120 Selecting the select CBX control properties

Set the Object, View, Find,

Custom List, Edit Filter, and
Select Filter properties.

7. Select the controls for the other select CBX properties.

Custom List: gridOrgList
Edit Filter: cmdEditFilter
Select Filter: ddlFilterSelect
8. For the Object property, enter the name of the CeFO database object that
the query is to be generated against.
In the example shown in Figure 121, it is bus_org.

The Grid and CBX Controls 217

The Select CBX Control

Figure 121 Database object and view for select form example

Schema object and view are

bus_org in this example.

9. For the View property, enter the view/object to be displayed in the grid.
In this example it is the same as the Object property. This can be a
different view as long as the base table of the view is the same as the
Object property.
10. Right-click the grid control and select Grid Wizard.
The Grid Wizard window appears.
11. Select OrgList from the list and click OK.
The grid columns are filled with fields from the OrgList contextual object,
as shown in Figure 122.

218 Chapter 9
 The Select CBX Control

Figure 122 Grid wizard, generating columns in the grid control

12. Open the Properties window for the dropdown list and set the Object
Column and Long Value properties to Yes.

IMPORTANT: The Object Column and Long Value properties of the

dropdown list box must both be set to Yes in order for the Select CBX to work
properly.

13. Make the following associations between the form’s contextual objects
and the controls you created by setting the properties of the grid and
dropdown list controls:
• Grid destination contextual object: SelectionItem
• Dropdown list:
Source contextual object: FilterSetList
Destination contextual object: FilterSetSelect
14. If desired, preview the form, as shown in Figure 123.

The Grid and CBX Controls 219

The Select CBX Control

Figure 123 Previewing the example Select CBX form

15. Set up the remaining Select CBX properties as desired. See Select CBX
Properties on page 222 for more information.

For any new form, you need to create a minimal amount of code to run that
form. You must use ClearBasic to create a Form_Load procedure and to add
any event handlers needed by your form. However, the operation of the
filter list, Edit button, and Find button is automated by the Select CBX
control—you do not need to write ClearBasic code for these controls.

Editing Filter Properties

At run time, when a user clicks the Edit Filter button, the Select CBX control
displays the Filter Set dialog box. Using this dialog box, the user can create
new filters using the list of available fields. You must specify the list of
available fields by modifying the Filter Properties of the Select CBX control.

To add fields to the Filter Properties

1. Open the Property sheet of the Select CBX control.
2. Click Filter Properties to display the Item Properties window, as shown
in Figure 124.

220 Chapter 9
 The Select CBX Control

Figure 124 Item Properties window

3. Enter an item name and path for each field you want to add.
The item name is a placeholder used to identify the name in the Filter
Set dialog box. The path contains the name of a field or a qualified path
(a relation in the CeFO database schema) to a field starting from the
object in the Object property of the Select CBX control.
4. Click OK to save the filter properties.

After creating a set of filter properties, you can reorganize them from the
Item Properties window. To move an item up or down, select the row
containing that item and click the Up or Down button, respectively. To delete
an item, select the item and click the Delete button.

Supporting Ad Hoc Queries

Ad hoc queries give the user the ability to create a query directly from the
grid associated with a Select CBX. If the Select CBX control supports ad hoc
queries, the grid control reserves its first row for user-entered query
parameters. To initiate an ad hoc query, the user types values in one or more
columns and does one of the following: presses the Enter key, clicks the Find
button, or clicks the button on the adhoc row.

Ad hoc querying is enabled by default when you create a new Select CBX
control. The Select CBX control defines three properties related to ad hoc
querying that you can modify to suit your needs. See Select CBX Properties on
page 222 for a complete list of properties.

The Grid and CBX Controls 221

The Select CBX Control

MultiCBX Controls
If the grid control associated with a CBX control is a multigrid (supports
multiple contextual objects), then you must also make the CBX a multiCBX
control. You do this by setting the multiCobj property to Yes.

A multiCBX control is a Select CBX control that is associated with a

multigrid instead of a simple grid. A multiCBX control works exactly like a
Select CBX, except that the CBX can query and display multiple contextual
objects in the same grid.

Place the grid, dropdown list, Find button, Filter button, and CBX controls
on the form.

Set the MultiCobj property to Yes for both the grid and the CBX.

Select CBX Properties

Table 30 lists the special properties of the select CBX control. (For a list of the
common properties supported by all controls, see Common Properties of
Controls on page 99.)

222 Chapter 9
 The Select CBX Control

Figure 125 Properties of the select CBX control

Property Type Property Name Description

Behavior Auto Find Specifies whether a query is initiated automatically after the user
selects a filter from the Filter dropdown list box. If set to Yes, the
CBX control automatically initiates a query when the user selects
a new filter. If set to No, the user must click the “Find” button to
initiate the query.
Disable adhoc row Enables or disables the ad hoc row of the associated grid control.
Yes disables the row, No enables it.
Disable adhoc sort Enables or disables the sorting mechanism of the associated grid
control. Note that sorting may be inefficient when many rows are
displayed.
• Yes - disables sorting.
• No - enables sorting.
Is readonly adhoc Specifies whether the cells of the adhoc row can be modified. If
set, you must modify the cells programmatically using ClearBasic
code; the user cannot enter values.
MultiCObj If enabled, allows the CBX control to access multiple contextual
objects.
Unconstrained If set, the combination of user and programmed filters may be
search empty; otherwise, the user or your ClearBasic code must specify
at least one filter. Setting this parameter to Yes lets the user return
a list of all records by omitting all search parameters.
Security Rule Enables or disables the use of security rules during queries. If set
to Yes, the CBX control applies the current security rules to any
rows returned from a query. The security rules act as a filter to
restrict undesired records from showing up in the grid. If set to
No, these rules are not applied.

The Grid and CBX Controls 223

The Select CBX Control

Figure 125 Properties of the select CBX control (Continued)

Property Type Property Name Description

Misc Instance Unique name of the control used to identify the control on the
form. ClearBasic refers to the control as CBX_Instance where
Instance is the value specified here.
Object CeFO database object that the query is generated against.
View CeFO database object or view used to display the data in the grid
control. The view must be based on the object, i.e., the unique
field of the view must correspond to the objid of the object.
Find Control name of button to refresh the list.
Custom List Control name of grid used to display the data.
Edit Filter Control name of the button to post the filterset edit form.
Select Filter Control name of the dropdown list box used for selecting
filtersets.
Filter Properties Opens the Item Properties window, used to create or modify the
filter properties. See Editing Filter Properties on page 220 for more
information.

224 Chapter 9
Chapter 10

Understanding Contextual Objects

In This Chapter
About Contextual Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Adding Contextual Objects to a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Contextual Objects and Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
Propagating Contextual Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238

225
About Contextual Objects

About Contextual Objects

When users work with forms in a CeFO application, they enter and view
data from the CeFO database from their local client machines. To
temporarily hold the data on the client, CeFO applications use areas in local
memory called contextual objects.

Contextual objects act as a buffer to the database and improve performance.

The CeFO application maintains the links between the database fields and
their associated contextual objects. Controls on a form are linked to
contextual objects associated with that form, and are used to display and
update the data in local memory.

CeFO baseline forms already contain a set of links to the contextual objects
needed by the form. If you add controls to the form, you can link them to
existing contextual objects associated with the form, or you can add
contextual objects as necessary. You can also add contextual objects to store
any additional values you calculate in the form’s ClearBasic code.

Source and Destination Contextual Objects

The interface between a control and its contextual objects are the Source
Contextual Object and Destination Contextual Object properties. This
interface allows data to be entered and displayed in a form.

A source contextual object provides the initial data for a control. When the
control’s form is posted, data is transferred from the contextual object to the
control. The various controls use source contextual objects in different ways:
• List boxes, dropdown list boxes, combo boxes, and grids all support
source contextual objects, and can have an associated source contextual
object which represents the list of data to display.
• Check boxes, command buttons, labels, and option buttons do not
require a source contextual object but support them for dynamic labeling
of the control.

A destination contextual object stores the current value of the control. For
example, the destination contextual object for a dropdown list box contains
the string that the user selects; the destination contextual object for a text box
contains the string the user enters.

Figure 126 shows an example of the use of both source and destination
contextual objects on a form.

226 Chapter 10
 About Contextual Objects

Figure 126 Contextual objects in the Edit Case window

A destination
contextual object
stores the case title.

These menus
use source
contextual objects
to display the menu
choices, and
destination contextual
objects to store your
selection.

Designing Contextual Objects

One of the most important aspects of creating a form is linking contextual
objects to the form. Controls can access only the contextual objects
associated with the form. Thus, when designing the form you must specify
all of the contextual objects that will be used by the form.

Understanding Contextual Objects 227

About Contextual Objects

When you design your form, make sure you analyze your storage needs
thoroughly.
• If the form accesses the CeFO database, you must know which database
objects (tables) or views the form is going to access and provide
contextual objects for them. You need to have ClearBasic installed in
order to add a new contextual object that refers to a database object or
view.
• If your form and controls display or store calculated data, you need
contextual objects to store the calculated values. For example, the
number of subcases associated with a case is calculated when the Edit
Case window is displayed. This number is stored in a contextual object,
not in the database. You need to have ClearBasic installed in order to add
certain types of these values. Figure 127 shows the calculated value in the
Edit Case window.

More Information: For more information about the CeFO database schema, see the
Data Dictionary Guide.

Figure 127 Calculated value in the Edit Case window

This contextual object

displays the number of
subcases associated
with a case. This value is
calculated and is not
stored in the database.

228 Chapter 10
 Adding Contextual Objects to a Form

Adding Contextual Objects to a Form

The Edit Form Contextual Objects window (as shown in Figure 128) defines
the contextual objects associated with a form. You can add, rename, or delete
contextual objects.

To view the list of contextual objects for a form

You can view the list of contextual objects for a form in any of the
following ways:
• Choose Edit > Contextual Objects from the menu at the top of the UI
Editor window.
• Press F3.
• Choose Edit Contextual Objects from the Properties window of any
control in the form.

Figure 128 Edit Form Contextual Objects window

Contextual objects
associated with a
form are listed here.
Controls on this form
can access only the
contextual objects
for the form.

NOTE: If you start the User Interface Editor without the -cb option, you can
select only primitive types (string, long, date, and single) from the Edit Form
Contextual Objects window.

Understanding Contextual Objects 229

Adding Contextual Objects to a Form

To add contextual objects to a form

1. Open the form in the User Interface Editor.
2. Right-click the form, any control on the form, or press F3 to open the
Properties window, as shown in Figure 129.

Figure 129 Properties associated with a form

Click the ellipsis (...) next

to the Edit Contextual
Object property to add
contextual objects to the
form.

More Information: For more information about the Properties window, see
Viewing the Properties Window on page 93.

3. In the Data section, select the Edit Contextual Objects property.

The Edit Form Contextual Objects window appears, as shown in
Figure 130.

230 Chapter 10
 Adding Contextual Objects to a Form

Figure 130 Adding a new contextual object

4. Specify the contextual object information, in the order described below

(see Figure 131).
• Name is the contextual object identifier that is used to reference the
contextual object both in ClearBasic code and in the listings in the
Extended Contextual Objects window.
• Database Object Type specifies whether the contextual object refers to
a database object or view. If not, it specifies what type of “Primitive”
data type it is.
• Caption shows the identifier to display in a treeview on a multipane
form. You may use your own discretion in how to display it. The
property is also available through ClearBasic.
• Sub Type is applicable only for certain Database Object Types, either
database objects (tables or views) or Primitive types. See Table 31 on
page 236.

NOTE: Refer to the ClearBasic Customization Guide for a description of the

naming conventions suggested by CeFO for contextual objects.

Understanding Contextual Objects 231

Adding Contextual Objects to a Form

Figure 131 Defining the contextual object data type

Name
Database Object Type

NOTE: If you are running the User Interface Editor with the -cb option,
different object types are displayed in the list.

5. Click Add.
6. Repeat for each contextual object to be linked to this form.

If you forget to add a particular contextual object to a form, or discover that

you need another contextual object, you can go back and add contextual
objects to the form at any time. If your form is a parent for any child forms,
make sure to propagate your changes to the child forms. Do not add
contextual objects directly to the child forms.

See Propagating Contextual Objects on page 238 for more information.

232 Chapter 10
 Adding Contextual Objects to a Form

Contextual Object Names

When you define a new contextual object, you must assign it a name. Forms
identify contextual objects by name at run time. The contextual objects
associated with a form must have unique names.

Refer to the ClearBasic Customization Guide for naming conventions

suggested by CeFO.

Database Object Types and Sub Types

After you assign a name to the contextual object, click the Database Object
Type button and select a data type for the contextual object. You can select
primitive data types such as strings and long integers, or you can select
record data type (a database object or view) such as contract or case. The
contextual object can only store data of the type you select.
Table 31 Contextual object types

Data Type Database Description Sub Types

Object Type Available
Primitive Date Use for dates. -
(ClearBasic not Elapsed Time Use for time. -
required) List Use to display a list of Long, Integer,
values in a list box, or String, Decimal,
as the destination or Record
contextual object of a
grid control. Requires
ClearBasic.
Long Integer. -
Single -
String Receives user input -
from a text box.
Database Table Select by The name refers to an Record or Record
(ClearBasic required) database object object or view from the List
or view name CeFO database.

Understanding Contextual Objects 233

Adding Contextual Objects to a Form

Be sure to select a data type that is appropriate for the contextual object’s
usage. If you associate the contextual object with a control, make sure the
data type is appropriate for that control. The contextual object data types
required for each control are listed in Contextual Objects and Controls on
page 235.

Long vs. List/Long: The difference between a Database Object Type of Long
and a Database Object Type of List with a Sub Type of Long is that the List/
Long type is used to store the indexes for a list of records, whereas Long
stores a single integer value.

Sub Type
The Sub Type dropdown list is activated only if you have selected a
Database Object Type of a database object or view, or a Database Object Type
of List. It is not used for the other primitive data types.

If you select a Database Object Type of List, the Sub Type choices are:
• Long (destination contextual object for grids)
• Integer
• String
• Decimal
• Record
• None
For Database Object Types that are database tables or views, the Sub Types
are:
• Record
• Record List (source contextual object for grid control)
• None

234 Chapter 10
 Contextual Objects and Controls

User-Defined Contextual Object Types

If you have purchased ClearBasic, you have the ability to create new
contextual objects of User Defined Types.

If you link a form to a contextual object that has a user-defined type and then
link one or more controls to that contextual object, you must remove all
references to the contextual object before you can remove the definition of
the user-defined type. Removing the definition first can prevent you from
reposting that form in the User Interface Editor.

More Information: For more information about database objects, views and fields,
see the Data Dictionary Guide. For more information about contextual objects and
placing data into a form’s contextual objects, see the ClearBasic Programmer’s
Guide. For more information on User Defined Types, see the ClearBasic
Customization Guide.

Contextual Objects and Controls

After you link contextual objects to the form, you have the containers for all
of the data that your form makes available to the user. To display the data
contained in those contextual objects, or to enable users to interact with that
data, you must create controls and link them to the appropriate contextual
object using the various control properties for contextual objects.

You link a control to a contextual object through the control’s Properties

windows, as shown in Figure 132.

Understanding Contextual Objects 235

Contextual Objects and Controls

Figure 132 Source and destination contextual object properties

These properties define the

destination contextual object and field. Click the Source Contextual
Object or Destination
Contextual Object property to
These properties define the select from a list of all
source contextual object and field.
contextual objects associated
with the form.

More Information: For more information about the Property window, see Viewing
the Properties Window on page 93.

Table 31 lists each control type and indicates whether source and destination
contextual objects are supported and their data type.

Figure 133 Controls and contextual objects

Control Source Source Contextual Destination Destination

Contextual Object Data Type Contextual Contextual Object
Object Object Data Type
ActiveX No - No -
Animation No - No -
Button Yes String (optional) No -
Check box Yes String (optional) Yes Long
Dropdown combo box Yes List (optional) Yes String
Dropdown list box Yes List (optional) Yes String/Long
Graph Yes * Varies No -
Grid Yes Varies for each field No -
in the custom list
Group box Yes String (optional) No -
* For controls where the source contextual object is optional, you can leave that property blank to allow data to be
programmatically entered.

236 Chapter 10
 Contextual Objects and Controls

Figure 133 Controls and contextual objects (Continued)

Control Source Source Contextual Destination Destination

Contextual Object Data Type Contextual Contextual Object
Object Object Data Type
Label Yes String (optional) No -
Line No - No -
List box Yes List Yes List
Multiline text box No - Yes String
Option button Yes String (optional) Yes String
Progress bar No - Yes Long
Select CBX No - No -
Slider No - Yes Long
Tab Yes String (optional) No -
Text box No - Yes String/Long
Treeview No - No -
UpDown No - No -
* For controls where the source contextual object is optional, you can leave that property blank to allow data to be
programmatically entered.

To select the source or destination contextual objects

1. Open the Properties window for the control.
2. Click the Source Contextual Object or Destination Contextual Object
property and select the contextual object from the list.
3. Click the Source Contextual Field or Destination Contextual Field
property and select the contextual object field from the list.

Understanding Contextual Objects 237

Propagating Contextual Objects

Propagating Contextual Objects

At run time, child forms (both tabs and frames) communicate with their
parent form through a set of shared contextual objects. The child forms must
all have the same set of contextual objects as their parent form.

If you create a child form using the File > New > Child Form command, the
User Interface Editor automatically links the parent’s existing contextual
objects to the child form. However, if you add new contextual objects to a
parent form after creating the child forms, you must manually link the new
contextual objects to the child forms.

The User Interface Editor helps you quickly propagate the contextual objects
of a parent form to a corresponding child form. The Propagate Contextual
Objects command links the contextual objects of the parent to the designated
child forms. This command works only with forms that are already linked
through a tab or a frame command button.

When you propagate contextual objects from a parent form to a child form,
any contextual objects currently associated with the child form are deleted.
The contextual objects of the parent are then linked to the child form and the
child form is saved.

If a form has no associated child forms, then the Propagate Contextual

Objects command is disabled.

IMPORTANT: Do not add contextual objects directly to a child form. Add them to
the parent instead, and then use the Propagate Contextual Objects command to
make the contextual objects available to the child form.

238 Chapter 10
 Propagating Contextual Objects

Child Forms and Extended Contextual

Objects
Note that propagating contextual objects from the parent to the child forms
does not propagate extended contextual object information. You must
manually copy and paste the extended contextual object key/value pairs
from the parent to the child form.

Do not allow a child form to have additional extended contextual object

information that is not on the parent form. If you propagate from the parent,
and the parent does not have the same contextual objects as the child, then
the propagation will delete all extended contextual object information
associated with the child form.

Propagating Contextual Objects

To propagate contextual objects
1. Open the parent form.
2. Open the Propagate Contextual Objects window.
You can open the window in any of these ways:
• From the top menu bar, choose File > Open > Propagate Contextual
Objects.
• Right-click the form or tab control and choose Propagate Contextual
Objects from the shortcut menu.
• If the Edit Contextual Objects window is open, you can click the
Propagate button.
If the parent form has only one child form, and there is only one version
of that form associated with any resource configuration, the dialog box in
Figure 134 appears.
If the parent form has only one child form, but that child form has
multiple user versions associated with different resource configurations,
the dialog box in Figure 135 appears.
If there is more than one child form associated with the parent form, the
dialog box shown in Figure 136 appears.

Understanding Contextual Objects 239

Propagating Contextual Objects

Figure 134 Propagate: One child, one version.

Figure 135 Propagate: Multiple versions of one child.

Figure 136 Propagate: Multiple children, multiple resource configs

Filter using the Resource

Configuration dropdown
selection list.

240 Chapter 10
 Propagating Contextual Objects

3. If needed, select a user-defined resource configuration from the list.

In the window shown in Figure 136, a list of child forms associated with
the parent form appears in the bottom list box. These forms are in the
selected resource configuration.
Note that if you select the baseline resource configuration no forms will
be listed. This is because you cannot propagate or make any changes to
baseline forms.
4. Select the child form to which you wish to propagate.
In the window shown in Figure 135, you can only select one child form.
You cannot select multiple forms. In the In the window shown in
Figure 136, you can use Shift-Click to select a range of child forms, or use
Control-Click to select multiple, individual forms.
5. How you continue the propagation depends on which window you are
in:
• Figure 134: click Propagate Contextual Objects to complete the
propagation. Only one child form is updated.
• Figure 135: Clicking Propagate displays the Propagate Contextual
Objects window, as shown in Figure 134. From that window, click
Propagate Contextual Objects to complete the propagation.
• Figure 136: Click Propagate. If you did not select all the child forms, a
dialog box reminds you that your child forms may become
incompatible. Click Yes to complete the propagation, or No to cancel.

Understanding Contextual Objects 241

Propagating Contextual Objects

242 Chapter 10
Chapter 11

Using the Extended Contextual

Object Editor

In This Chapter
About Extended Contextual Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
The Extended Contextual Objects Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
Configuring Extended Contextual Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
Using Method Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254

243
About Extended Contextual Objects

About Extended Contextual Objects

The new multigrid and multiCBX controls are key components in multipane
forms. These controls are extensions of the existing grid and Select CBX
controls, except that they have the ability to switch contextual objects based
on user selections at run time. This allows the CeFO application forms to
display information from different database objects and views using a single
grid control.

The multigrid and multiCBX controls use extended contextual objects to

store control-related data. In addition to serving as a runtime storage
mechanism for information related to a particular form, extended contextual
objects now let you associate additional information on an object or a field
level.

Every contextual object on a form automatically has a corresponding

extended contextual object. At creation time, the new extended contextual
object does not contain any data. You add data by assigning key/value pairs
to the properties and methods of the extended contextual object. At runtime,
your code uses the information in these key/value pairs to perform specific
tasks.

The multigrid and multiCBX controls use specific Property key/value pairs
to determine the data to read and display.

The Extended Contextual Objects Window

The extended contextual objects have their own window. To view the
extended contextual objects, select a form and press F4 or choose Edit >
Extended Contextual Objects. A window appears similar to that shown in
Figure 137.

244 Chapter 11
 The Extended Contextual Objects Window

Figure 137 The Extended Contextual Objects window

Treeview pane Detail pane

Extended Contextual Objects and

Contextual Objects
The extended contextual objects are extensions of the existing contextual
object functionality; there is a one-to-one correspondence between each
contextual object and its associated extended contextual object. Figure 138
shows how the extended contextual objects for a form map to the contextual
objects.

Using the Extended Contextual Object Editor 245

The Extended Contextual Objects Window

Figure 138 Contextual objects vs. extended contextual objects

246 Chapter 11
 The Extended Contextual Objects Window

Listing Methods and Properties

Expanding a particular extended contextual object displays the Property and
Method listings for that object, as shown in Figure 139.

Figure 139 Property and method listings

For all contextual objects, the Property folder lists object-level properties.
This folder additionally lists field-level properties for contextual objects that
represent tables or views in the CeFO database.

The Method folder contains a listing of user-defined properties that apply to

this extended contextual object.

Displaying Key/Value Pairs

Selecting a particular property or method displays all the key/value pairs
associated with the selected item. As shown in Figure 140, when the user
clicks the eNote item in the treeview on the left, the detail pane on the right
shows the corresponding key/value pairs.

Using the Extended Contextual Object Editor 247

The Extended Contextual Objects Window

Figure 140 Key/value pairs

Selected item Key/value pairs

Navigating the Extended Contextual Object

Treeview
All the listings in a treeview are called nodes. Clicking on a node will either
expand it or display more information about it in the right-hand detail pane.
Table 32 lists the extended contextual object treeview icons.
Table 32 Extended contextual object treeview icons

Icon Description Meaning

Node with Indicates an extended contextual object listing with
sublistings additional listings.
Expanded node Indicates an extended contextual object listing that is
expanded to show all methods and properties.

248 Chapter 11
 The Extended Contextual Objects Window

Table 32 Extended contextual object treeview icons (Continued)

Icon Description Meaning

Extended Extended contextual object node.
contextual
object
Property folder Property node.

Method folder Method node.

Property An attribute of the extended contextual object. For

database tables, these list each column in the table (field
in a CeFO database object or view). Each field in turn
can have its own set of key/value pairs.
The grid Column Properties are shown here for
multigrids, instead of in the grid Properties window as
for simple grids.
General Properties are user-defined properties.
Object-level Indicates the properties of the extended contextual
properties object itself.
Property with K Indicates that the properties for the selected node
include some user-defined properties.
Property with Indicates that this field (table column) will appear on
grid the grid control and be visible to the end user.
Method Indicates user-defined properties that are supported by
ClearBasic code.

Using the Extended Contextual Object Editor 249

The Extended Contextual Objects Window

Context Menus in the Extended Contextual

Object Window
A context-sensitive menu appears if you right-click over any list item in the
treeview. The selected node determines whether individual menu items are
enabled or disabled. Table 33 lists the context menu items for extended
contextual objects.
Table 33 Context menu items for Extended Contextual Object window

Menu Item Description

Add Method Adds new method to selected Methods folder. Right-click on the
Method folder to activate.
Delete Method Deletes selected method. Right-click on the method to delete.
Rename Method Renames selected method. Right-click on the method to rename.
Copy Special Copies the key/value pairs for the selected method or property
as follows:
• Properties - only General Properties are copied
• Methods - all key/value pairs are copied
Paste Special Pastes key/value pairs from another list item into selected list
item, as follows:
• Properties - only General Properties are pasted
• Methods - all key/value pairs are pasted
Add Method Adds a new method using key/value pairs from a specified
from Template method template. You must enter values in order to save the
information.
Append from Appends key/value pairs from a method template onto the end
Template of the existing list of key/value pairs for a selected method.
Update from Replaces existing key/value pairs for a selected method with the
Template key/value pairs from a method template.
Edit Template Opens a method template for editing.

Copy Special and Paste Special

In the Extended Contextual Objects window, you can copy and paste
properties and methods using the Copy Special and Paste Special options on
the context menu. You can also paste key/value pairs from a spreadsheet or
from a tab-delimited text file.

250 Chapter 11
 Configuring Extended Contextual Objects

To copy and paste the key/value pairs from one property to another
1. Right-click on the property to copy.
2. Select Copy Special from the context menu.
3. Right-click on the property to paste and select Paste Special.
4. Specify values for each key.

You can also copy and paste from one method to another.

To copy and paste key/value pairs from the Windows clipboard

1. Open the file from which to copy.
Make sure the key/value pairs are separated by tab characters.
2. Use a regular Copy command such as Control-C to copy to the clipboard.
3. In the UI Editor, select the property or method to paste into.
4. Use Control-V to paste the values into the UI Editor window. Note that
you can only copy General properties.
5. Specify values for each key.

Configuring Extended Contextual Objects

The extended contextual object configuration is important mostly for the
multigrid and multiCBX controls. See Creating a Multigrid/MultiCBX Form on
page 329 for an example of this procedure.

To create a multigrid control

1. Place the grid control on the form.
2. Set the multiCOBJ Property for the grid control to “Yes”.
This action converts the grid control into a multigrid.

Using the Extended Contextual Object Editor 251

Configuring Extended Contextual Objects

3. For each database object to show in the multigrid, add two contextual
objects: one to reference the database table, and one to hold the resulting
list of records.
Press F3 to open the Edit Contextual Objects window. Add the following
for each database table or view you want to display in this grid control:
• A Source contextual object for the database table, selecting the CeFO
database object name as the Database Object Type and with a Sub Type
of “Record List.” This contextual object is typically named lorObject
where Object is usually the database object name.
• A Destination contextual object of Database Object Type List to contain
the selected records with a Sub Type of “Long.” This contextual object
is typically named losObject where Object is again the database object
name.

NOTE: You are not required to use the CeFO naming conventions described
above.

4. Open the Extended Contextual Objects window by pressing F4.

Extended contextual object listings appear for every contextual object
you added in Step 3.
The next series of steps should be repeated for every database object that
you wish to display in the multigrid.
5. Select the intended source contextual object (the lorObject).
a. Expand the Property folder for the source contextual object.
b. Select the key field.
c. Select the Grid check box.
d. Under Grid Properties, specify the multigrid control name that you
added in Step 1 as the Grid Name.
e. Under Grid Properties, specify the List contextual object name
(losObject) as the Destination Contextual Object Name.
f. Select the database object field names to display in the grid.
To display a particular field from the database table, click the field
listing and then select the Grid check box for that field. The icon next
to that field name becomes filled.

252 Chapter 11
 Configuring Extended Contextual Objects

6. Determine how the grid will display each contextual object.

You must write ClearBasic code to control the selection and loading of
each contextual object associated with the multigrid. See the ClearBasic
Control Reference for more information.

You can add a multiCBX control to allow custom filtering. See the example
Creating a Multigrid/MultiCBX Form on page 329.

Adding Methods
Methods created in the UI Editor are references to custom, user-defined
ClearBasic code functions. They are associated with extended contextual
objects on a form. Therefore, in order to add a method, you must first add
the contextual object to the form. See Adding Contextual Objects to a Form on
page 229.

Adding Methods to Extended Contextual Objects

To add a method to an extended contextual object
1. Open the form to which the method will be added.
2. Press F4 to open the Extended Contextual Objects window for the form.
3. Expand the extended contextual object to which the method will be
added.
The Property and Method folders appear.

Using the Extended Contextual Object Editor 253

Using Method Templates

Figure 141 Adding a method

Right-click the Method folder

and choose Add Method.

4. Right-click the Method folder and choose Add Method from the shortcut
menu, as shown in Figure 141.
Because this is a new method, the key/value listing in the detail pane on
the right is empty.
5. Modify the method name and properties as needed.
6. Modify the ClearBasic code for the form to read the method’s key/value
pairs.

Using Method Templates

Method templates are used to group predefined set of key/value pairs into
reusable configurations. You can use the templates to create new methods,
or to paste predefined key/value pairs into existing methods or General
properties. You do not need ClearBasic in order to create or modify
templates. However, you cannot edit or delete any CeFO-defined templates.
• Add method from template: Adds all key/value pairs from the template
you select.
• Append from Template: Adds new key/value pairs from template to end
of current values for method. If there is already a key with the same
name, the new key/value pair will not be inserted.
• Update from Template: Overwrites old key/value pairs with current
values from template.
• Edit template: Opens the selected template for editing.

254 Chapter 11
 Using Method Templates

Templates are stored in a binary file called cleobj.tpl which is stored

locally in the UI Editor home directory. Bear the following items in mind
when working with method templates:
• Do not use duplicate key/value pairs within the same template, or even
across different templates.
• Because the templates are stored locally in a file and not in the CeFO
database, you must copy your cleobj.tpl file to each new location if you
run the UI Editor from different machines.

Types of Method Templates

The two types of templates are recognizable by their icon:
CeFO templates are stored as baseline templates. You can use
these, but not modify them.
User-defined templates can be created, modified, or deleted.

Steps to Add and Use Templates

To add a new template
1. Choose Edit > Edit Template File.
The Extended Contextual Object Templates window appears as shown in
Figure 142.

Using the Extended Contextual Object Editor 255

Using Method Templates

Figure 142 Extended Contextual Object Templates window

2. Click New Template.

The new template appears as an icon in the main window area with a
default title of “New Template.”
3. Enter a new name for the template.
4. With the new template selected, click the Edit Template tab.
The Edit Template window appears, as shown in Figure 143.

256 Chapter 11
 Using Method Templates

Figure 143 Edit Template window

5. Select the template to edit and click the Edit tab.

6. Add your key/value pairs and click Close.
KeyUser-defined key name
ValueUser-defined value
Control Type(Optional) Choose text box, dropdown list, contextual object
list, or contextual object field list.
Popup Name(Optional) If you choose dropdown list as the Control Type,
this column is activated as a dropdown list with the names of all the
dropdown lists in the system.

Using the Extended Contextual Object Editor 257

Using Method Templates

Note the following:

• The method template values are saved in a file stored locally in your UI
Editor home directory. They are not stored in the CeFO database.
• This file is not updated until you exit the UI Editor. Until that point, these
values are stored only in memory.

To add a method from a template

1. Open the form to edit.
2. Open the Extended Contextual Objects window.
Choose either Edit > Extended Contextual Objects or use the F4 key.
3. Expand the extended contextual object to which the method will be
added.
4. Right-click on the Method folder and select Add Method From Template.
The Extended Contextual Object Templates window appears.
5. To add, do one of the following:
• Double-click the template.
• Select the template and click OK.
• Select the template and press Enter.
6. Supply values for each key, before closing the window.

258 Chapter 11
Chapter 12

Using the Action Editor

In This Chapter
About Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
Action Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
How Actions Work with CeFO Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
How Actions Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
Defining an Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
Adding a Button to Invoke an Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271

259
About Actions

About Actions
The Action Editor gives you the ability to use a command button in a CeFO
application to invoke an operating system command, a predefined script, a
program, or a stored procedure. You can use the command button to invoke
these directly, or you can use the button to have those actions started when
the form is posted (the Form Init option).

NOTE: You can also define the actions for buttons using ClearBasic.

Action Types
The actions that can be invoked depend on the client platform. The
following types of actions are available:
• For X Window System/Motif clients, shell scripts, UNIX commands, or
stored procedures.
• For PC clients, batch scripts, programs, or stored procedures.
After you create the action for your client platform, use the Button Actions
window to specify the name of the action to be invoked, the input
arguments, and the return values.

How Actions Work with CeFO Applications

Actions can be used to pass commands from the CeFO application to the
native operating system of the client. Actions can also pass input and output
arguments from CeFO applications to a command. Contextual objects
specify these arguments. Two files, one for the input arguments and one for
the output arguments, are generated in the temp directory of your hard disk
(for UNIX systems, /usr/temp; for Windows systems, the directory
specified by the TEMP variable).

260 Chapter 12
 How Actions Work with CeFO Applications

Using Actions to Invoke Stored Procedures

You can use actions to invoke stored procedures in the database.

Actions can pass input and output arguments between the CeFO application
and stored procedures. Unlike the arguments used by command-line
actions, these arguments are not stored in an intermediate file. The values
are passed directly between the CeFO application and the stored procedure
in the database.

If you use a stored procedure, make sure that all users have the correct
permissions to execute the procedure. For example, if you create an action to
invoke a stored procedure in a SYBASE database, make sure to run the isql
command on the stored procedure:
grant execute
on stored_procedure_name
to public

Asynchronous Actions
An asynchronous action is a process spawned in the background. The user
can still work with the CeFO application while the asynchronous action is
running.

The Open button in the Attachments dialog box is an example of a button

that invokes an asynchronous action. In this case, the action invokes a
specified text editor used to view the attachment. While the text editor is
running, the user can still use the CeFO application. The CeFO application
does not wait for the user to exit the text editor.

An asynchronous action can use only input arguments. Because the CeFO
application does not track the invoked process, the application cannot
receive output arguments from the action.

Synchronous Actions
A synchronous action is like a process running in the foreground. While a
synchronous action is running, the CeFO application waits for the
completion of the action. The process must finish before you can use the
CeFO application again.

Using the Action Editor 261

How Actions Work

The Calculate button in the Close Case form is an example of a button that
invokes a synchronous action. In this case, the action is the recalculation of
time and expenses for a case. While calculation is being performed, a busy
cursor is displayed and the user cannot use the CeFO application.

A synchronous action can use both input and output arguments. Since the
CeFO application waits for the completion of the action, the results (the
output arguments) of the action can be returned to the application.

NOTE: If an action includes an error that causes it to go into an infinite loop,

CeFO applications do not return until the action process is interrupted and
terminated.

Actions on Button Controls

You can associate new actions with existing button controls on CeFO forms.
You can specify whether the new action takes place before or after the CeFO
action performed by the button.

For example, the Save button saves data from a form to the database and
you might write an action to perform data validation. When you associate
this new action with the Save button, you can specify that the new action
(data validation) is executed before the existing action (save data to the
database). This checks the data before it is saved to the database. Thus, the
action can raise an error to abort the Save operation.

How Actions Work

Actions are stored as objects in the CeFO database. When users run the
CeFO application, these actions are read into local memory. When a user
clicks a button associated with an action, the CeFO application interprets the
action in the command line or stored procedure and executes the action.

262 Chapter 12
 How Actions Work

Interpretation of Command-Line Syntax

When a user clicks a button, the application reads the contextual object fields
specified by the input arguments. The application writes the values of these
fields to a temporary file. On UNIX systems, this file is generated in the /
usr/tmp directory. On a Windows system, the file is generated in the
directory specified by the TEMP system variable.

The names of the input and output argument files are randomly generated.

The command line is also generated by replacing any additional contextual

object fields with values from local memory. The format used to generate the
command line is:
command [input_argument] input_file output_file [&]
where:
• command is the command, script, or program that the action executes.

NOTE: Any literals not enclosed by brackets, [ ], are passed as command-line

arguments. Thus, [cobj.fieldname] or [cobj] for a non-object cobj, will be
substituted with the in-memory cobj value.

• input_argument is one or more values from a contextual object field

that is automatically passed from the button to the command line.
• input_file is the name of the input argument file generated by the
application. If output arguments are specified, the name of the input
argument file is always the second to the last argument on the command
line. If no output arguments are specified, the name of the input
argument file is the last argument.
• output_file is the name of the output argument file generated by the
application. If output arguments are specified, the name of the output
argument file is always the last argument on the command line. If no
output arguments are specified, the output argument file is not generated
and the argument does not appear on the command line.
• & (UNIX only) is appended to the end of the command for asynchronous
actions, indicating that the invoked process runs in the background and
does not force the application to wait for its completion. Asynchronous
actions in Windows do not require the & symbol.

Using the Action Editor 263

How Actions Work

After this command line is generated, the application passes the command
to the operating system for execution.

NOTE: If an action is defined as a stored procedure, this interpretation of the

command line does not occur. The CeFO application simply invokes the stored
procedure by name and passes the input values to the procedure. Output values are
passed back from the procedure to the CeFO application. No input or output
argument files are created.

Execution of the Action

The action is executed by the operating system as a child process invoked by
the CeFO application. If the action is asynchronous, control returns to the
CeFO application and the user can continue working. If the action is
synchronous, the CeFO application waits for the process to complete. Fields
in the contextual object are updated with values from the output arguments
of the action.

Any error messages should be written to the output file after the output
arguments are written. If the return status is nonzero (which indicates that
an error occurred), the application displays an error message dialog box
with any error messages found in the output file.

If the execution was successful (return status is zero) and if an additional

message is found in the output file, the application displays this message in
a standard note dialog.

264 Chapter 12
 Defining an Action

Defining an Action
When you define an action, take into account the different client platforms
on which the CeFO application runs. You also must decide how to specify
the input and output arguments for the action.

Platform Differences
For each client platform, define the action in terms of that client’s native
operating system:
• On UNIX platforms, use shell scripts or applications to define actions.
• On the PC/Windows platform, use batch files or applications to define
actions.

Because the application automatically appends the input argument file

name as an argument to the action, commands that require exact syntax do
not work as actions.

For example, the UNIX command xterm must be used with the correct
syntax. When the application appends the name of the input file to this
command, the command fails because the input file name is not a supported
argument for the command.

If you need to specify a UNIX command as an action, create a shell script

containing the command. The script must always have at least one
additional argument, the name of the input file.

Input and Output Arguments

Input arguments for an action are read from fields in contextual objects that
exist in local memory. When you define the input arguments for an action,
you can use any field from any contextual object for the form.

Output arguments for the action are written to fields in contextual objects
that exist in local memory. As with input arguments, when you define the
output arguments for an action, you can use any field from any contextual
object for the form. (See Figure 144.)

Using the Action Editor 265

Defining an Action

Figure 144 Defining input and output arguments

List of contextual
object fields Input
available from arguments
the form

Output
arguments

Stored procedure
name

If the action is defined as a command line, the input arguments that you
specify are written to the input argument file and are separated by carriage
returns (newline characters). Similarly, when the CeFO application reads
output arguments from the output argument file, the application reads each
line as an output argument. The only exceptions are strings which are
enclosed by single quotes, because the strings may contain newline
characters.

Please note the following rules that apply to input and output arguments:
• You cannot specify a collection of objects (such as a list of the entries
displayed in a custom list) as an input or output argument. An input or
output argument must contain a single value.
• If you define an action as a stored procedure (rather than as a command
line), input and output arguments are passed directly between the CeFO
application and the stored procedure. No input or output argument files
are generated.
• If a button action is set to synchronous and another application
(executable) is invoked successfully, any content after the values
corresponding to output arguments are retrieved and displayed in a note
dialog. If the application execution is not successful, the output file is
retrieved and displayed in an error dialog.

266 Chapter 12
 Defining an Action

You can also directly specify input arguments as part of the action’s
command line. The syntax for a command-line input argument is:
[contextual_obj_name:field_name]
where:
• contextual_obj_name is the name of the contextual object in the
form.
• field_name is the name of the field in the contextual object.
The argument must be enclosed by brackets, [ ].

For example, the following action invokes the script named svc_check
with the serial_no field of the PRT_INSTALL_OBJ contextual object as an
input argument:
svc_check [PRT_INSTALL_OBJ:serial_no]

NOTE: You cannot specify output arguments directly on the command line. If you
want output values from the action to write to contextual object fields in the CeFO
application, you need to use the output argument file.

Even if you specify all input arguments as part of the action’s command line,
the name of the input file is still passed as an argument. Keep this in mind
when you identify arguments by number in your script or interface.

Writing the Script or Interface

When you write a script or interface for use with an action, consider the
manner in which the input and output arguments are handled.

If you are using an input argument file, the script needs to parse through the
input file to get the input arguments. If you are using an output argument
file, the script needs to use newline characters as field separators when
writing output values.

Although the names of the input and output argument files are randomly
generated, the names are passed as arguments to your script or interface.

Using the Action Editor 267

Defining an Action

What Are Form Init Actions?

Form Init actions allow you to define actions to be executed as a form is
posted. Form Init actions are typically used for pre-filling form fields that are
not stored in the standard data model. For example, you might want to fill a
default value into a field based on some other data (such as a date field), or
change a pop-up list to some value other than the default.

The Actions section is used to display existing Form Init actions that have
been defined for your CeFO application, as well as to define new Form Init
actions.

Form Init actions are always permitted to modify contextual objects.

If you modify the standard data model by adding a new relation, and the
object at the other end of the relation uses a field that must be displayed on a
given form when a specific record is displayed, a stored procedure can be
specified as a Form Init action to retrieve the record and display the
necessary fields in the form.

Form Init actions are defined using a hidden command button in the desired
form. The hidden command button is labeled Form Init by the Action Editor
when the Form Init action is created and saved. The control name for the
Form Init action is init_event. The Form Init button appears in the form
when you view it using the User Interface Editor. It does not appear when
the form is opened from within the CeFO application.

A Form Init action can be specified as either a command-line statement

defined in the Action Editor form, or as a stored procedure created for your
database. Only one Form Init action per form for each client platform is
permitted.

More Information: See the Data Dictionary Guide for information about objects
and relations.

268 Chapter 12
 Adding a Button to Invoke an Action

How Form Init Actions Are Defined

Form Init actions are defined as follows:
• Create the action for the client platform. For example, for
X Windows System/Motif clients, you might create a shell script or
choose to launch a UNIX application that performs the action.
• Use the Command Button form to specify a Form Init action.
• Use the Action Editor form to indicate the following:
• The action to be invoked (such as a shell script or a command)
• The input arguments to be used (selected fields for that Form Init
action)
• The return values to be used (selected fields for that Form Init action)

Adding a Button to Invoke an Action

To add a button that invokes an action
1. Place the button on the form.
2. Double-click the button control to open the Properties window, as shown
in Figure 145.

Figure 145 Button Properties window

3. Enter a label for the button in the Caption property.

Using the Action Editor 269

Adding a Button to Invoke an Action

4. Select Command or Form Init for the Button Type property.

5. Click the Button Action tool in the Format toolbar.
Alternatively, you can right-click the button and select Button Actions
from the context menu.
The Button Actions window appears, as shown in Figure 146.

Figure 146 Button Actions window

Upper Copy
button copies to
Input Arguments

Lower Copy
button copies to
Output Arguments

6. In the Action Name text box, type a name for the action.
7. Choose Command Line or Stored Procedure to specify the type of action
executed.
For more information about action types, see Using Actions to Invoke
Stored Procedures on page 261.
8. From the Platform menu, choose the appropriate client platform for the
action (use DOS for Windows).

270 Chapter 12
 Example

9. From the Mode menu, choose Asynchronous if the action is performed

without synchronization with the CeFO applications or Synchronous if
the CeFO application must wait for the action to complete before
continuing.
If you want output values returned from the action, you must choose
Synchronous.
10. From the Order menu, choose Before to indicate that the action occurs
before the default action of the button or After to indicate that the action
occurs after the default action of the button.
If you are defining an action for a new button control (a control that has
no standard action associated with it) the order is irrelevant.
11. If the action requires input arguments, select the arguments from the
Contextual Object Fields list box and click the upper Copy button.
12. If the action requires output arguments, select the arguments from the
Contextual Object Fields list box and click the lower Copy button.
13. In the Command Line text box, type the syntax of the command or the
name of the stored procedure.
For more information about action types, see Using Actions to Invoke
Stored Procedures on page 261.
14. Click the Add button to add the action to the button.
15. Click OK.
16. Repeat to define actions for other client platforms.

Example
In the Expense form, you can record expenses for a case. One of the expenses
that you can log is labor. Suppose your employees charge different rates.
You can store these rates with the employee information in the database and
access this information when recording expenses in the Expense form.

You can access this information from ClearSupport by defining an action.

Use the Action Editor to associate a new command button with a stored
procedure that finds the rate information for the selected employee.

Using the Action Editor 271

Example

Defining the Stored Procedure

The stored procedure in this example uses the login name of an employee to
return the rate charged by the employee. Since no field in the employee
object currently stores a floating point number that specifies the rate for an
employee, you can use the Data Dictionary Editor to add a field. This
example assumes that this new field has already been added to the
employee database object and is named x_labor_rate. This example also
assumes that you have already customized the Employee form to enable
users to enter information to this field.

Since the login name of an employee is actually stored in the related user
object, the relation employee2user is used to access the user object. The
stored procedure, which is called find_rate, is described as follows for a
SYBASE database:
create proc find_rate @name varchar(30), \
@rate float output
as
select @rate = table_employee.x_labor_rate from
table_employee, table_user
where login_name = @name
and employee2user = table_user.objid

To ensure that all users can execute this stored procedure, you need to grant
public permission to access the procedure. For a SYBASE database, you can
do this through isql by typing:
grant execute
on find_rate
to public

Before you create the action in the User Interface Editor, verify that this
stored procedure works. For a SYBASE database, you can do this through
isql by typing the following commands:
declare @rate float
exec find_rate login_name, @rate outputl

where login_name is the login name of a user in your database with rate
information already entered.

272 Chapter 12
 Example

Adding the Command Button Action

After you have verified that the stored procedure works correctly, you can
add the command button control to the Expenses form and associate the
stored procedure with the button. The following procedure assumes that
you have already found and opened the Expenses form.

To add a button control

1. Add a command button to the Expenses form.
2. Double-click the command button control to display the Properties
window.
3. In the Caption property, type Get Employee Rate, as shown in
Figure 147.

Figure 147 Naming the new button

Type the name

of the
button here.

4. Make sure the Get Employee Rate button is still selected; then click the
Button Action tool in the layout toolbar.
The Button Actions window appears, as shown in Figure 148.

Using the Action Editor 273

Example

Figure 148 Viewing the Button Actions window

5. In the Action Name text box, type Get Hourly Rate.

6. From the Action Type menu, choose Stored Procedure.
7. From the Platform menu, choose the appropriate client.
8. From the Mode menu, choose Synchronous, since an output value is
returned from the stored procedure to ClearSupport.
9. In the Contextual Object Fields list box, select ONSITE_OBJ:perf_by.
This field represents the login name of the employee who performed the
work for the expense log.
10. Click the upper Copy button to copy the field as an input argument from
ClearSupport to the stored procedure.
11. Scroll down the Contextual Object Fields list box, and select
EXP_OBJ:rate.
This field represents the rate for the expense log.
12. Click the lower Copy button to copy the field as a return value from the
stored procedure to ClearSupport.
13. In the text box at the bottom of the window, type find_rate, as shown
in Figure 149.

274 Chapter 12
 Example

Figure 149 Creating a button action

14. Click Add to create this new action.

A unique name for the button action appears in the Button Action
Objects dropdown menu. In this example, the name
Get Hourly Rate:-1:DOS appears.
15. Click OK.
16. Choose File > Save As to save the custom version of the Expense Log
form.

You can now associate this custom form with users through a resource
configuration.

Using the Action Editor 275

Example

276 Chapter 12
Chapter 13

Using the Code Editor

In This Chapter
About the Code Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278
Code Editor Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278
Creating Form Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
Creating Global Code Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283

277
About the Code Editor

About the Code Editor

The Code Editor is for use by sites that purchased ClearBasic along with the
CeFO application suite. To view code, you must start the User Interface
Editor with the -cb option. If your site does not have ClearBasic installed,
you can use the Action Editor to customize the behavior of controls.

Code Editor Features

The User Interface Editor includes an integrated Code Editor for writing
global and form-specific code. The Code Editor incorporates several features
to make writing ClearBasic code easier, including the following:
• Text coloring and formatting for keywords, identifiers, and comments
• Auto-indenting
• Automatic statement completion for known objects
• Syntax tips for known object methods
• Dropdown list box containing all of the controls on the form
• Dropdown list box containing all of the event handlers available for the
current control

The Code Editor Window

You use the Code Editor window to edit the ClearBasic code associated with
a form or a global module. When you work with global modules, the Code
Editor window consists of an editable text area and a status bar. When you
work with forms, the Code Editor window displays two additional
dropdown list boxes near the top of the window. (See Figure 150.)

The control dropdown list box contains the name of each control currently
on the form. When you select a control from this list, the event-handler list
displays the event handlers available for that control. When you select an
event handler, the Code Editor adds a stub for the event handler to the edit
area of the window. You can then add your code to the stub to complete the
event handler.

278 Chapter 13
 Code Editor Features

Figure 150 Code Editor window for forms

Control list Event-handler list

Editing area

In addition to the stubs created by the Code Editor, you can define
additional ClearBasic functions and subroutines by typing the routine in the
form. In this case, you must type the entire routine declaration.

You can place routines anywhere in the Code Editor window. At run time,
the ClearBasic engine reads the code for the form and provides the
appropriate linkage before executing the code.

Text Formatting
As you type, the Code Editor applies text formatting to your code. By
default, the Code Editor simply adds coloring to different portions of your
code. The Code Editor differentiates keywords, identifiers, and comments
by applying a default set of colors to them.

You can change the colors applied to each type of element. You can also
apply different font types and sizes to elements. To specify these settings,
you must use the Settings dialog box, as shown in Figure 151. To open this
dialog box, open a Code Editor window and choose Format > Code Editor
Settings from the menu bar.

Using the Code Editor 279

Code Editor Features

Figure 151 Settings dialog box

To change the setting of a particular element, you must first select it from the
list. You can apply different foreground and background colors for each
element. You can also use the Font and Size dropdown list boxes to apply
different font styles.

Auto-Indenting
In addition to text formatting, the Code Editor automatically moves the
cursor to the appropriate indentation level when you press the Return key.
The Code Editor does not enforce indentation levels, so you can reformat the
code to suit your style after you press Return.

Automatic Statement Completion

As you type your code, the Code Editor looks for identifiers representing
known objects associated with your form. When you type the name of a
control or other known object and follow it with a period (.), the Code Editor
displays a list of the object’s methods and properties. Select the appropriate
method or property by scrolling through the list or typing the first character
of its name. Press the Enter key to close the list and enters the item you
chose.

In a similar manner to controls, the Code Editor also recognizes the

contextual objects associated with a form. If you type the string “CObj”
followed by the underscore character (_), the Code Editor displays a list of
the form’s contextual objects. Select the contextual object you want to
complete the identifier name.

280 Chapter 13
 Creating Form Modules

Automatic statement completion is enabled by default when you first launch

the User Interface Editor. You can disable it at any time by modifying the
Code Editor settings.

To disable automatic statement completion

1. Choose Code Editor Settings from the Format menu.
2. Click the Options tab, as shown in Figure 152.

Figure 152 Disabling automatic statement completion

3. Select the Disable Syntax helper check box.

Creating Form Modules

Each form can have its own unique code module. You use form code
modules to store form-specific routines, such as the Form_Load routine and
any event handlers for the form controls. You use the Code Editor window
to modify the routines associated with a form.

NOTE: The Code Editor does not let you assign code to a form that does not belong
to a valid resource configuration. You can create the code at any time, but you must
save the form and assign it to a resource configuration before you can save the code.

To add a code module to a form

1. Open a form or create a new form.
2. Choose Code from the View menu to display the Code Editor window
for the form, as shown in Figure 153.

Using the Code Editor 281

Creating Form Modules

Figure 153 The Code Editor window

3. Add your code to the window.

The Code Editor window displays any routines already defined for the
form. You can modify the existing routines or write new ones.
Selecting an event handler from the event-handler list either generates
a prototype at the bottom of the Code Editor window, or jumps to an
existing definition of the event handler.
4. Make sure your form belongs to a resource configuration.
The User Interface Editor can only save the code associated with forms
belonging to a resource configuration. If you try to save code for a
form that is not in a resource configuration, you will get a compile
error in the UI Editor. For more information on associating a form with
a resource configuration, see Adding Forms to a Resource Configuration
on page 63.
5. Choose Compile from the File menu to check your code for errors.
If there are any errors compiling the code, the UI Editor displays a
message and positions the cursor at the error line. Correct the error
and recompile.
A successful compilation is not a guarantee that your code will run as
expected. It is merely an acknowledgment that the syntax of your code
is correct. You may still encounter run-time errors when you test your
form.

282 Chapter 13
 Creating Global Code Modules

6. With the Code Editor window active, choose Save Code from the File
menu to save your changes.
Before saving, UI Editor compiles the code, so you do not need to choose
Compile first. If there are any errors, the code is not saved.

You can view the code for any form that is a member of a resource
configuration. If the form does not have any code associated with it, the User
Interface Editor creates a new form module.

To edit a form module

1. Open the form.
2. Choose Code from the View menu.
3. Enter your changes.
4. Choose Save Code from the File menu to save your changes.

Creating Global Code Modules

In addition to writing code for forms, you can create global code modules to
store commonly used routines. With the UI Editor, you can create any
number of global code modules.

Each global code module can have three identifying strings:

• An application name (always “clarify”)
• A subsystem name
• A user label
The database uses these strings to differentiate one code module from
another, so you should never specify the exact same set of strings for two
separate code modules. However, only one string needs to be different in
order to differentiate two code modules. So if you have two or more related
code modules, you can group them by assigning different user labels but the
same application and subsystem names.

For example, suppose you are customizing the ClearSales application and
you have two global code modules you want to store in the database. You
can assign the strings “clarify” and “clearsales” for the application and
subsystem names of both code modules. For the user labels, you can then
assign “module1” to the first module and “module2” to the second.

Using the Code Editor 283

Creating Global Code Modules

To create or open a global code module

1. Choose File > Open > Global Code Module.
2. In the Open From Database window, shown in Figure 154, specify the
application name, subsystem name, and label of the global code module.

Figure 154 Opening a global code module

If the specified module exists in the database, the UI Editor opens that
module and displays the existing code. If the specified module does
not exist, the UI Editor opens an empty window.
3. Add your code to the Code Editor window.
The Code Editor window displays any routines already defined for the
form. You can modify the existing routines or write new ones.
4. Choose File > Compile to check your code for errors.
A successful compilation is not a guarantee that your code will run as
expected. It is merely an acknowledgment that the syntax of your code
is correct. You may still encounter run-time errors when you test your
form.
5. With the Code Editor window active, choose File > Save Code to save
your changes.

284 Chapter 13
Chapter 14

Merging Different Form Versions

In This Chapter
Specifying the Forms to Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
Generating a Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
Merging the Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

285
Specifying the Forms to Merge

In certain situations, you might need to combine the layout and properties of
two different versions of a form. The forms must have the same Form ID.

For example, suppose you customized the New Case form, and CeFO
shipped a new version of the New Case form. You must update your custom
version of the form with the latest changes in the baseline CeFO form.

Ideally, you want a form that combines the new features from the baseline
version with your custom controls from the customized version.

One of the features of the User Interface Editor is the capability to merge two
different versions of a form into a new form.

When you merge two different versions of a form, the User Interface Editor
compares each version. Using the above New Case form as an example, a
new version of the New Case form is generated. It contains CeFO’s latest
updates and your custom changes.

Specifying the Forms to Merge

To merge forms, you need to know the form ID and version numbers. Form
ID and version information can be found in the Form Select window or in
the banner of the form when opened in the edit form mode, as shown in
Figure 155.

286 Chapter 14
 Specifying the Forms to Merge

Figure 155 Form ID and user versions

Form ID and version

numbers

Form ID and
version numbers

You can merge a custom version of a form with a CeFO baseline, or you can
merge two versions of a custom form. (See Figure 156.)

Merging Different Form Versions 287

Generating a Report

Figure 156 Identifying the forms to merge in the Form Merge window

Enter the custom Merge the form

form identification with a CeFO
and version numbers baseline or
here. another custom
version of the
form.

Use these options

to define your
preferences for
merging forms.

After specifying the form version, you can set your preferences for the
merge operation.

Each of the preferences options lets you specify which version to use if the
two forms do not match. If you choose Both, the new form contains a
superset of all the properties and data from each of the two merged forms.

Generating a Report
When you merge two versions of a form, a report lists the differences
between the two versions.

288 Chapter 14
 Generating a Report

By default, the following differences are listed:

• Control properties
• Form titles
• Control labels
• Labels
• Format for text boxes
• Columns in custom lists
• Contextual objects
• Source and destination links
• Frames of the form
• Maximum length of text box
• Pop-up lists for dropdown list boxes
• Groupings of option buttons
To change the report parameters, click Preview Options in the Form Merge
window.

To change any of the reports (for example, if differences in static text position
are not important), select the appropriate options in the Preview Differences
Options window, as shown in Figure 157.

Merging Different Form Versions 289

Generating a Report

Figure 157 Changing the report contents

Previewing the Difference Report

Before you run the merge operation, you can view the report of differences
between the form versions. Click Preview on the Form Merge window. The
Form Differences Report window appears, as shown in Figure 158.

Figure 158 Form Differences Report window

To narrow or broaden the list of differences reported, make different

selections in the Preview Differences Options window.

290 Chapter 14
 Merging the Versions

Merging the Versions

To merge two versions of a form
1. Choose File > Merge Forms...
The Form Merge window appears, as shown in Figure 159.

Figure 159 Merging forms

Enter a version
number for the merged
form here.

2. In the Form ID field, type the identification number of the (custom) form
to merge.
For information about form ID numbers, see Specifying the Forms to Merge
on page 286.
3. Type the CeFO version number and user version number of the form in
the First Version CeFO Version and User Version fields.
For information about finding the version numbers, see Specifying the
Forms to Merge on page 286.
4. Select Baseline or Custom as the second form to merge.
Select Baseline to merge your custom version with a baseline CeFO
version of the form.
Select Custom to merge your custom version with a different custom
version of the same form.

Merging Different Form Versions 291

Merging the Versions

5. (optional) If you selected Custom as the second version, type the CeFO
version and user version number of the second form in the CeFO Version
and User Version fields.
6. Enter the (user) version of the new form in the new version field.
7. Select the merge preference options.
For information about merge preference options, see Specifying the Forms
to Merge on page 286.
8. (optional) Click Preview Options or Preview to specify the contents of the
report or to preview a merge report.
For more information about specifying the contents of the report or to
preview a report, see Generating a Report on page 288.
9. Click Merge.
A report of differences between the two versions is automatically
generated as is a new version of the form.

After the merge operation has completed, open the resulting version of the
form in the User Interface Editor. You may need to adjust the layout of the
form or check the tab order if additional controls were added during the
merge process.

Resolving Merge Conflicts

If there are any conflicts in the forms, the conflicting controls from the
second form are placed in special conflict version of the form. The version is
the merge version plus “_x”. For example, if the merge version is “2.0”, the
conflict version is “2.0_x”.

You need to open the conflict version of the form, and manually copy and
paste the controls onto the merge version.

Deleting a Form
If for some reason you want to delete a form, select it in the Form Select
window and click Delete, as shown in Figure 160.

NOTE: You cannot delete the baseline version of a form.

292 Chapter 14
 Merging the Versions

Figure 160 Deleting a form

Select a form and click Delete to

remove it from the database.

If the form is in a resource configuration, it is removed and the resource

configuration will use the baseline version of the form instead.

Merging Different Form Versions 293

Merging the Versions

294 Chapter 14
 Appendix A

Examples

In This Chapter
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
Customizing the WIPbin and Queue Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
Find Caller Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300
Adding Multi-Field Filtering to a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Changing the Method of Part Selection for Cases . . . . . . . . . . . . . . . . . . . . . . . . . .310
Adding SQL Controls to the Query Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
Adding KeyPhrases to Part Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324
Passing Login Information to Shell Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
Creating a Multigrid/MultiCBX Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329

295
Overview

Overview
This appendix presents examples for customizing various CeFO forms. Most
of the examples concern alternative CeFO functionality that is available for
existing forms.

Customizing the WIPbin and Queue Windows

CeFO provides a way to fully customize the information that appears in the
WIPbin and Queue windows. Customizing these windows poses a unique
problem because the information shown is generally the combined result of
several queries, one query for each type of queuable object: Case, Subcase,
Solution, Part Request, Change Request, Opportunity, Quote, Action Item,
and Contract.

Customizing the information displayed is therefore more complex.

Nevertheless, the methodology described here is fully supported by CeFO.

You can add additional fields to the grids without adding additional joins to
the view. As long as you can find a field of the same data type in an object
that is already part of the view, you can add custom fields, using that unused
field as a placeholder.

For example, you want to add a new column that shows a string value in the
grid. To extend the wip_element or que_element view, you could use
the alt_first_name field, which has a data type of string. Add an
additional column to the wip_element or que_element view with
case.alt_first_name as the source. You have now fulfilled the
requirement of providing a placeholder of the same data type for the grid
column to link to.

Definitions
Definitions related to the procedure are as listed in Table 34.

296 Appendix A
 Customizing the WIPbin and Queue Windows

Table 34 WIPbin and Queue definitions

Name Definition
WIPbin window The WIPbin window is selected by title “WIPbin wipname”,
name “cswip” or ID 375 in the User Interface Editor.
Queue window The Queue window can be selected by title “Queue,” name
“csqueue” or ID 376 in the User Interface Editor.
Specific field ID A number associated with an object field in the CeFO data
dictionary. It identifies the index of the field in the object, starting
at 0. Object fields always have a specific field ID.
Generic field ID A number associated with a CeFO database object or view field.
It describes the generic purpose of that field. For example, CeFO
uses generic field ID 2 to identify the title field of objects and
generic field ID 4 to identify the ID number. The specific and
generic field ids for a field are generally different.
Object fields do not necessarily have a generic field ID. However,
all fields that are shown as columns in the WIPbin or Queue
window must have a generic field ID in the appropriate views.
Generic field ids in the range 50 to 149 (inclusive) are reserved
strictly for use by CeFO customers. CeFO never uses generic field
ids in this range. You should use ids in this range.
Generic WIPbin The “wip_element” view is used to bind specific wipbin view
view fields to columns in the WIPbin window. These fields must be
identified by generic field ID. The generic WIPbin view is never
actually read by the application.
Generic Queue The que_element view is used to bind object field to columns in
view the Queue window. Object fields must be identified by generic
field ID. The generic Queue view is never actually used to
perform database queries. It represents a superset of all the object
fields that can be shown as columns in the Queue dialog.

Examples 297
Customizing the WIPbin and Queue Windows

Table 34 WIPbin and Queue definitions (Continued)

Name Definition
Specific WIPbin Any one of the views that is used in a database query for the
view WIPbin contents:
wipelm_case is a query for Cases
wipelm_subcase is a query for Subcases
wipelm_dtl is a query for Part Requests
wipelm_fnl is a query for Solutions
wipelm_bug is a query for Change Requests
View fields just be identified by generic field ID which maps the
fields onto the generic WIPbin view fields in the definitions of the
columns of the WIPbin form.
Specific Queue Any of the views which is used in a database query fro the Queue
view contents:
queelm_case is a query for Cases
queelm_subcase is a query for Subcases
queelm_dtl is a query for Part Requests
queelm_fnl is a query for Solutions
queelm_bug is a query for Change Requests
View fields must be identified by generic field ID.

Procedure
The following procedure demonstrates how to show a new field as a column
in the WIPbin window. The same procedure can be used to customize the
Queue window.

The tool required for each step is given in parentheses. You are expected to
be familiar with these tools.

More Information: For more information about the Data Dictionary Editor, see the
ClearCustomize Guide to the Data Dictionary Editor.

298 Appendix A
 Customizing the WIPbin and Queue Windows

To show a new field as a column in the WIPbin window

1. Add a new field to an object, using the Data Dictionary Editor.
If the field you want to display already exists, this step is unnecessary.
2. Update the generic WIPbin view (Data Dictionary Editor).
Add any new field to the generic WIPbin view. It can be any field from
any object in the view, because this view is never read—the field is just a
placeholder for the real field from the specific view.
Assign a generic field ID in the range 50 to 149 inclusive. If more than one
field is added, make sure to assign different generic field IDs. Make sure
it does not conflict with existing generic field IDs for other fields.
3. Update the specific WIPbin view (Data Dictionary Editor).
Add the new field to the specific WIPbin view, using the same generic
field ID as in the generic WIPbin view. If necessary, add a join to the
specific WIPbin view.

NOTE: It is not necessary to update all the specific WIPbin views if the new field is
to be shown for only one type of object. When other types of objects are shown, the
column for the new field is simply left blank. If the new field is to be shown for all
objects, then all specific WIPbin views should be updated.

4. Update the WIPbin window (User Interface Editor).

Add a new column to the grid in the WIPbin window. Select the
appropriate field from the contextual object Save the window to the
database.
If you customize your WIPbin or Queue lists for subcases to return any
data that relates to the Case (such as Site name or Contact name), add a
relation to the two subcase views that will join the case and the subcase.
If you do not do so, the CeFO application scans all cases for each subcase
in the query. This can result in extremely slow performance.
For example, to table_wipelm_subcase and
table_queelm_subcase, add the following relation:
case.case2subcase = subcase.subcase2case

Examples 299
Find Caller Customization

Find Caller Customization

The New Case window (Form ID 411 or 775) includes a Find Caller feature
that allows users to quickly locate the site and contact information for a
caller who may already exist in the CeFO database. By default, the Find
Caller search information includes the Site ID, Site Name, Contact Name,
and/or the contact phone number.

You may want to add a new filtering field to speed up and simplify the Find
Caller flow so that it is better customized to your site’s business processes.
For example, you can add an employee ID number or a postal code field to
help your users find a particular contact or site more quickly.

Adding Custom Find Caller Fields to the

Database
You can add custom fields to your CeFO database using a CeFO tool such as
the Data Dictionary Editor, and use those fields as part of the Find Caller
filter. This custom field provides additional filtering for your call handling
process. The following general limitations apply:
• The field must be a character string (alphanumeric characters only)
• The field must be of datatype varchar.

NOTE: This feature can be a powerful tool for simplifying your system’s workflow.
However, to ensure adequate database performance, it is recommended that any
new custom fields be appropriately indexed.

To add a new custom filtering field for Find Caller functionality

1. In the Data Dictionary Editor, add the new field to the desired CeFO
database object.
You can add the field to one of the following objects: contact, site,
address, bus_org or contact_role.
2. Add the new field to the rol_contct view.

300 Appendix A
 Find Caller Customization

Adding Find Caller Filters to the New Case

Window
The next step in using this feature is to add a text box control to the New
Case window that corresponds to the custom database field you want to use
as a Find Caller filter.

The contextual object you will be using is called CONTACT_VIEW, and it is

associated with the rol_contct view.

To add a new filtering control to the New Case window

1. In the UI Editor, open the New Case window.
Use Form ID 411 if you do not have a CeFO license for Service manager,
or Form ID 775 if you do have Service Manager licensed.
2. Place a text box control in the desired location on the form.
3. Edit the properties of the text box.
Double-click on the text box control to bring up the Properties window,
and edit the properties as follows:
• Enter a Name that starts with FIND_CALLER. For example, you could
call it FIND_CALLER_ID.
• For the Destination Contextual Object property, select CONTACT_VIEW.
• For the Destination Field Name property, select the custom field you
previously added to the rol_contct view.
4. Add a label control to identify this filter field for your users.
5. Save the form and add it to a resource configuration.

IMPORTANT: The control Name for new Find Caller fields must start with
FIND_CALLER in order for this control to work. However, existing filtering fields
do not need to be renamed.

Examples 301
Adding Multi-Field Filtering to a Form

Using the Find Caller Customize Feature

This should not change the existing Find Caller work flow. The only
difference in behavior is that the additional filter fields will be “ANDed” to
the other filtering criteria.

You may want to add a filter field to the Select Contacts form that
corresponds to the new Find Caller filter field. See Adding Multi-Field
Filtering to a Form on page 302 for more information.

Adding Multi-Field Filtering to a Form

The multi-field filtering feature provides multiple filtering fields for some,
but not all, CeFO baseline forms. In addition, this feature provides a
resource of additional filtering fields that can be added to these windows
through customization.

Overview
The basis for this feature is a contextual object called NEW_FILTER, which is
included with the CeFO baseline forms listed in Table 35 on page 303. The
NEW_FILTER contextual object provides fields that you can use for custom
multi-field filtering on the the CeFO forms that contain it.

With the NEW_FILTER contextual object, you can do the following:

• Add to or replace existing filtering fields in forms such as the Select Sites
and Select Contacts windows.
• Replace the standard searching properties on the select Contracts
window with the fields in NEW_FILTER.
• Add custom fields to the database object or view referenced by the
NEW_FILTER contextual object in a particular form, and then use
NEW_FILTER to add those custom fields to the “Sort by” dropdown list
on that form.

302 Appendix A
 Adding Multi-Field Filtering to a Form

Most of the forms listed in Table 35 that contain the NEW_FILTER contextual
object already use the NEW_FILTER fields as part of their filter. However, the
baseline version of the Select Contracts window does not use the
NEW_FILTER fields, although the contextual object is included with the
form. This makes a small difference in how you would add custom filtering
to the Select Contracts window, as opposed to the other forms.

Only Some Forms Can Use Multi-Field Filtering

Not all forms use multi-field filtering. You cannot add the NEW_FILTER
contextual object to a form that does not already have it.

Multi-Field Filtering vs. Select CBX

Baseline forms thatalready have Select CBX controls can also have custom
filter fields, but that is done using a process different from the one described
in this section. Also, you cannot add a Select CBX control to a CeFO baseline
form that already has a filter in order to add custom fields to that filter, as
this may conflict with underlying CeFO logic behind the form.

Database Objects Used by NEW_FILTER

Note that the NEW_FILTER contextual object points to a different database
object or view in each of the forms where it is used, even though it has the
same name in all of the forms.
Table 35 Database objects used by NEW_FILTER

Form Form Title NEW_FILTER database

ID object/view
500 Select Part Requests demand_hdr
515 Select GL Accounts and Locations locatn_view
519 Select Inventory Parts parts_view
524 Select GL Accounts and Locations locatn_view
555 Inventory Part Search parts_view
610 Select Part Number partnum_view
683 Site Configuration Manager scm_view
689 Select Installed Parts addrsitepmhpml
711 Select Contacts rol_contact
716 Select Sites site_view

Examples 303
Adding Multi-Field Filtering to a Form

Table 35 Database objects used by NEW_FILTER

Form Form Title NEW_FILTER database

ID object/view
730 Select Contracts contract
899 Schedule Tracker appt_empl_user

Limitations on Multi-Field Filtering

The following considerations apply to multi-field filtering:
• The multi-field filtering uses the “Starts With” operator. The “Sounds
Like” operator is not available.
• The “Ends With” and “Contains” operators will require the end user to
specify a wildcard character (a percent “%” sign).
• Only string data types can be used as filtering criteria. Dates and
numbers cannot be used. Because contracts are typically searched for by
date values (such as end dates), the Select Contracts window does not
automatically have the additional filtering fields preinstalled.

How Multi-Field Select Operates

Multi-field filtering operates in the following ways:
• Each field with filtering value is ANDed together with the other filter
fields.
For example, entering a “J” in the First Name field, an “S” in the Last
Name field, and “Micro” in the Site Name field of the Select Contacts
window selects all contacts whose first name starts with “J,” whose
last name starts with “S,” AND whose site name starts with “Micro.”
• You can use the wildcard character (%) as part of the selection criteria.
• If the Select Contacts window is posted as a result of the Find Caller
command in the Case window, the data entered for that case (such as the
site ID and site name) will be propagated to the Select Contacts window’s
filtering fields.

304 Appendix A
 Adding Multi-Field Filtering to a Form

Adding Fields to the NEW_FILTER

Contextual Object
If you want to create custom fields in your database and use them as filter
fields on the Select Contacts, Select Contracts, or Select Sites windows, you
must first add them to the appropriate database object using a CeFO tool
such as the Data Dictionary Editor.

The contextual object will automatically detect the added fields, but you
must still use the Destination Field selection list on the Properties window to
specify that new field for a particular control on the appropriate form.

To add a new field to the NEW_FILTER contextual object

1. Add the new field to the appropriate database object using the Data
Dictionary Editor.
2. Add the new field to the appropriate view.
3. Add the new field as a filtering field to the appropriate window.
Refer to one of the following sections
• Adding Filters to a Select Window on page 305
• Adding Filters to the Select Contracts Window on page 306
4. If desired, add the field to a “sort by” dropdown selection list.

Adding Filters to a Select Window

With the exception of the Select Contracts window, all of the windows listed
in Table 35 already have filtering fields that use the NEW_FILTER contextual
object. The following instructions therefore refer generically to any window
using NEW_FILTER other than Select Contracts.

To add a new filtering field

1. In the UI Editor, open the form to customize.
Table 35 on page 303 lists the forms and ID numbers for which these
instructions apply. Although there are many other select forms, none of
them use the NEW_FILTER contextual object which is necessary for the
multi-field filtering feature.

Examples 305
Adding Multi-Field Filtering to a Form

2. Place a text box on the window and give it an appropriate name.

Double-click on the text box to open the Properties window and edit the
Name property. For example, use the name phone_filter for a phone
filtering field.
3. On the Properties window, click the right-hand column next to the
Destination Contextual Object property and select NEW_FILTER.
When you first place the text box, the Destination Contextual Object
property should say “none.” When you click it, a drop-down selection
list appears showing all the contextual objects currently associated with
the form. Select NEW_FILTER.
4. On the Properties window, click the column next to Destination Field
Name and select any field with a String data type.
When you select a field from the dropdown list for the Destination Field
Name property, the Destination Data Type property displays the data
type.
5. Add a label for the text box control, so that the user knows what the new
filter does.
6. Add the field to the Sort by list for the form, if desired.
See Adding Fields to a “Sort by” List on page 309.
7. Save the form and add it to a resource configuration.

Adding Filters to the Select Contracts

Window
Unlike the other windows listed in Table 35, the Select Contracts window
does not have any filtering fields that use the NEW_FILTER contextual
object. Before adding any filtering fields, you must first prepare the window
by hiding and changing the existing search controls. Then add the new
filtering fields.

NOTE: If you perform this customization to the Select Contracts window, you will
lose the ability to filter by end date, filter/sort by site name, or filter/sort by site ID.

To prepare the Select Contracts window for new filtering fields

1. In the UI Editor, open the Select Contracts window (Form ID 730).

306 Appendix A
 Adding Multi-Field Filtering to a Form

2. Make a note of the current size attributes (under Properties) for this
window.
One of the steps below requires that you temporarily resize the window
and then restore it to its original dimensions.
3. Expand the Select Contracts window and make it larger.
4. Hide the old filter controls by moving them out to the edge of the resized
window.
The controls you want to move are named “WILDCARD,” “FILTER_BY,”
and “SET” (Date/Time button), as shown in Figure 161.

Figure 161 Controls to move on Select Contracts window

SORT_BY_MBT Move these controls off the visible portion of

dropdown menu: move to the Select Contracts window.
upper right

ASC_DESC
dropdown menu

5. Resize the Select Contracts window back to its original size, so that all the
controls you just moved are now hidden.
6. Move the dropdown menu named “SORT_BY_MBT” to the upper right
of the window.
Place it just above the dropdown menu named “ASC_DESC.”
7. Place a label control next to the SORT_BY_MBT dropdown menu.
Enter “Sort by” as the label text.

Examples 307
Adding Multi-Field Filtering to a Form

8. Open the SORT_BY_MBT menu’s List Items window.

Double-click the control to open the Properties window and click the
ellipsis (...) next to the List Items property.
9. Remove “Site Name” and “Site ID” from the list.
10. Add a field to this list for sorting that will correspond to any text box
filter fields you want to add to the Select Contracts window.
In the “Item” field, enter the text to display in the menu. In the “User
Data” field, enter the exact name of the field prefixed by its object name
using the syntax object_name.field_name. For example, use
contract.po_number to specify the P.O. number of a contract.
Each field added to the sorting list must correspond directly to a field
used as an edit control field (a text box control that is a filtering field).
11. Click Add.
12. Add other desired sort by attributes.
13. Add a text box control for each of the sort by attributes, as described in
the section following, titled To add a new filtering field to the Select Contracts
window.

To add a new filtering field to the Select Contracts window

1. In the UI Editor, open the Select Contracts window (ID 730) , if it is not
already open.
2. Add a new text box control to the window.
3. Set the text box properties.
Double-click the text box to open the Properties window.
• Change the name to something appropriate.
• Click the column next to the Destination Contextual Object, and select
NEW_FILTER.
• Click the column next to the Destination Field and select any available
field with a Destination Data Type of “String”.
4. Add a label for this text box control, so the users know what it is for.
5. Save the form and add it to a resource configuration.

308 Appendix A
 Adding Multi-Field Filtering to a Form

Adding Fields to a “Sort by” List

If you have added filtering fields to one of your Select windows, you may
want to add it to the “Sort by” list. The Select Sites and Select Contacts
windows have “Sort by” lists already; you can add a “Sort by” list to the
Select Contracts window as described in Adding Filters to the Select Contracts
Window on page 306.

To add a new field to a “Sort by” list for Select Contacts or Select Sites
1. In the UI Editor, open the appropriate Select window.
2. Open the dropdown list box named “SORT”.
It should have a label next to it that says “Sort by.”
3. Open the List Items window.
Double-click the control to open the Properties window and click the
ellipsis (...) next to the List Items property.
4. Add a field to this list for sorting that will correspond to any text box
filter fields you want to add to the form.
In the “Item” field, enter the text to display in the menu. In the “User
Data” field, enter the exact name of the field prefixed by its view name
using the syntax view_name.field_name.
Each field added to the sorting list must correspond directly to a field
used as an edit control field.
5. Click Add.
6. Add other desired sort by attributes.
7. Add a text box control for each of the sort by attributes, as described in
the section titled To add a new filtering field on page 305.

Examples 309
Changing the Method of Part Selection for Cases

Changing the Method of Part Selection for Cases

In the standard version of ClearSupport, cases are associated with installed
parts. When you associate a part with a case, you must select the part from a
list of installed parts at the site reporting the case, as shown in Figure 162.

Figure 162 Selecting the problem part for a case

When selecting a part for a case,

you choose from a list of
parts installed at the site that
reported the case.

310 Appendix A
 Changing the Method of Part Selection for Cases

To make this list of installed parts available in ClearSupport, you must use
the Site Configuration Manager to configure each site with the parts
purchased by the customer.

This process not be efficient for your company. Your support organization
might require that case information include only the related part number,
not the specific instance of the installed part at the site.

For example, suppose your support organization receives a large number of

brief calls (such as usage questions) from customers. When responding to
this type of call, the support employee does not need to gather data on the
configuration of parts at the customer site. The employee only needs to
identify the part number.

With the User Interface Editor, you can change the way in which parts are
associated with cases. Rather than restrict the user to selecting instances of
parts installed at the site, you can allow the user to select from a global list of
all part numbers. Users can associate any part with a case, regardless of
whether the part is installed or not.

To provide for this wider selection, you can allow users to choose a part for
the case from the Select Part Numbers form, rather than from the Site
Configuration Manager form. (See Figure 163.)

Examples 311
Changing the Method of Part Selection for Cases

Figure 163 Listing parts installed at a site versus listing all parts

Site Configuration Manager

lists part instances
installed at the site.

Select Part Number

lists all parts.

You can change the method for selecting the part for a case to:
• Select from a list of all part numbers.
• Select from a list of installed parts or all part numbers.

312 Appendix A
 Changing the Method of Part Selection for Cases

Additional forms for the New Case and Case Edit forms contain the controls
for implementing these methods. These forms are never visible to the user.
They are intended to be a palette for use with the UI Editor. The sole purpose
of the forms is to hold controls that can be copied to the New Case and Case
Edit forms. (See Figure 164.)

Figure 164 Additional Feature Options window for New Case

The controls on this form include a set of option buttons with which users
can select from either installed parts or a list of all part numbers. It also
includes text boxes in which users can specify search criteria and view
information about part numbers.

Also, there are additional buttons that can be added to the form.

Customizing the New Case Window

To allow users to select from a list of all part numbers, you need to
customize the New Case and Case Edit forms. The following procedure uses
the New Case form as an example.

To select from a list of parts in the New Case form

1. Open the New Case form.
2. Open the Additional Feature Options form (ID=415).
3. In the New Case form, select the Serial Number text box and press
Delete.
You can remove other controls that are not relevant to your support
organization.
4. In the Additional Feature Options form, select the part number controls
that you want to copy to the New Case form and choose Edit > Copy.
You can copy some or all of the controls.
5. Bring the New Case form to the front, and choose Edit > Paste.

Examples 313
Changing the Method of Part Selection for Cases

6. Move the new controls to an appropriate position on the form.

You may have to move other controls in order to make room for the new
controls. Figure 165 shows an example of a New Case form with
additional controls.

Figure 165 Example New Case form with additional controls

7. Click the Serial No button and open the Properties window.

8. Change the Caption property to a more accurate description (for
example, Part No, as shown in Figure 166).
Users click this button to display the list of all part numbers that match
the criteria entered in the text box.

314 Appendix A
 Changing the Method of Part Selection for Cases

Figure 166 Changing the Serial Number button text

9. Choose DEFAULT_PART_SELECTION from the pop-up list in the

Properties window, as shown in Figure 167.

Figure 167 Selecting the DEFAULT_PART_SELECTION control

Examples 315
Changing the Method of Part Selection for Cases

10. Change the Caption property to PART_LIST.

ClearSupport uses the label of this control to determine whether to
display the Site Configuration Manager (SITE_CONFIG) or the Select
Part Numbers form (PART_LIST).
11. Choose File > Save Form to save the New Case form as your own
version.

Repeat the same procedure to customize the Case Edit form. Rather than
opening the Additional Feature Options form with ID=415, use ID=422.

Specifying Required Filters for Part

Selection
In some situations, you may want to require users to enter data in one or
more filter fields before they click the List button on a Parts Selection
window. This will force the users to narrow the query that's being sent to the
database.

This can be accomplished by adding a non-visible Label control to the

window. This query restriction will work with parts selection forms like 610
(Select Part Number) and 689 (Select Installed Parts), but does not work with
other types of selection forms, like 711 (Select Contacts) or 716 (Select Sites).

To set a minimum number of required filters for part selection

1. Open the form with the UIEditor.
2. Add a filter threshold label.
If a filter limit already exists for the window, you will see
'FILTER_THRESHOLD (Label)' in the property list that comes up when
you double-click on the background of the window. Select this property
and change the Caption value to give the window a different threshold
limit.
If there is no FILTER_THRESHOLD property on the window, select and
draw a new Label control. Name the label FILTER_THRESHOLD and
give it a numerical Caption value like 0, 1, 2 or 3.
3. Set the value for the visible property to '0 - No'. Save the window and
add to a resource config.

The users will now have to enter some data in at least the number of filters
you specified in the Caption field above.

316 Appendix A
 Adding SQL Controls to the Query Windows

Adding SQL Controls to the Query Windows

Query windows in CeFO can be customized so that the SQL statements
generated by the query can be previewed and then modified if desired. This
allows your CeFO users to evaluate their queries to the database before they
are executed. Your CeFO users can then modify their queries, providing
them with better results and ultimately improving the performance of your
CeFO database.

How the SQL Feature Works

After the new controls have been added to your Query windows, your CeFO
users will have an additional querying method.
• A user can click the Find button to execute a query as usual.
Or
• Before executing the query, a user can click a Show SQL button to
preview the SQL statement in a multiline text box. They can then modify
the SQL statement to change their query.
• The user can then click an Execute SQL button to run their modified
query.

Please note, however, that there is an important functional difference

between using the Find button, and modifying the SQL statement for a
query and then using the Execute SQL button.
• The Find button executes a SQL statement as it is stored in the query
object of the CeFO database.
• The Execute SQL button executes a SQL statement as it is listed in the
SQL display text box (whether it has been modified or not). However, a
modified SQL statement in the text box will not be saved to the query
object in the CeFO database.

Examples 317
Adding SQL Controls to the Query Windows

Implementing the SQL Feature

This feature can be implemented by adding the following new controls to
the Query Edit and Query Prompt forms:
• A new multiline text box linked to the contextual object named
sql_statement of database object type query
• A new command button named SHOWSQL_CBTN (Show SQL) that will
get the SQL statement from the current active query object and display it
in the multiline text box
• A new command button named EXECSQL_CBTN (Execute SQL) that
will execute the SQL statement listed in the multiline text box.

NOTE: See Adding SQL Controls to Query Windows on page 319 for specific
instructions on implementing this feature.

Forms That Use the SQL Feature

All Query Edit and Query Prompt forms in CeFO have had the
sql_statement contextual object added to them, so the feature can be
added to any or all of these forms according to your needs. To aid you in
form selection, the Form IDs and Titles for Query Edit forms are listed in
Table 36 and the Form IDs and Titles for Query Prompt forms are listed in
Table 37.

Table 36 Query Edit forms

Form ID Form Title

806 Case Query Edit
805 CR Query Edit
810 Subcase Query Edit
812 Solution Query Edit
580 Transaction Query Edit
581 Part Request Query Edit
582 Shipments Query Edit
583 Receipts Query Edit
9128 Contracts Query Edit

318 Appendix A
 Adding SQL Controls to the Query Windows

Table 37 Query Prompt forms

Form ID Form Title

814 Case Query Prompt
815 CR Query Prompt
816 Subcase Query Prompt
817 Solution Query Prompt
818 Request Query Prompt
819 Shipments Query Prompt
820 Receipts Query Prompt
821 Transactions Query Prompt
9130 Contract Query Prompt

Adding SQL Controls to Query Windows

The following procedure describes the adding of SQL preview and
modification controls, using the Case Query Prompt window as an example.

To add SQL preview and modification controls to a Query window

1. Open a Query window. (For these instructions, the Case Query Prompt
window will be used as an example.)
Use the Form Select window with the following filtering criteria:

• Title: Case Query Prompt

• Name: qrycaspt
• ID: 814
2. Resize the window to make room for the new multiline text box and the
two command buttons.
Figure 168 shows the Case Query Prompt window with additional space
for the new controls.

Examples 319
Adding SQL Controls to the Query Windows

Figure 168 The Resized Case Query Prompt Window

Baseline Case Query

Prompt window

Resized Case Query

Prompt window

Additional space for

new controls

3. Add a multiline text box to an open area of the Case Query Prompt
window.
Figure 169 shows the Case Query Prompt window with all three new
controls.

320 Appendix A
 Adding SQL Controls to the Query Windows

Figure 169 The Case Query Prompt Window With New Controls

New command
buttons

New multiline
text box

4. Open the Properties window for the multiline text box and enter the
following information:

• Name: SQL_STATEMENT_EDT
• Destination Contextual Object Name: sql_statement
• Destination Field Name: sql_statement

IMPORTANT: In order for this feature to work, the information must be

entered exactly as specified.

Figure 170 shows the proper information for the properties of the new
multiline text box.

Examples 321
Adding SQL Controls to the Query Windows

Figure 170 Properties for the Show SQL multiline text box

5. Add two command buttons to an open area on the form. Figure 169
shows the Case Query Prompt window with two new command buttons
added to it.
6. Label the first command button “Show SQL” or something similar.
This button will show CeFO users the SQL statements for the current
query.
7. Label the second command button “Exec SQL” or something similar.
This button will execute a query according to the SQL statements
displayed in the new multiline text box.
8. Open the Properties window for the “Show SQL” command button and
enter SHOWSQL_BTN in the Name field, as shown in
Figure 171.

IMPORTANT: In order for this feature to work, the name of the command
button must be entered with the name exactly as specified.

322 Appendix A
 Adding SQL Controls to the Query Windows

Figure 171 The Show SQL command button properties

9. Open the Properties window for the “Exec SQL” command button and
enter EXECSQL_BTN in the Name field, as shown in
Figure 172.

IMPORTANT: In order for this feature to work, the name of the command
button must be entered with the exact same name listed in the step above.

Figure 172 The Execute SQL command button properties

Examples 323
Adding KeyPhrases to Part Classes

10. If necessary, adjust the location and sizes for the command buttons. (You
may have to adjust the size of the buttons to make the labels appear
correctly.)
11. Close the Properties window and save the form.

NOTE: You may want to further refine this customization by limiting this form
version to a specific Resource Configuration.

Adding KeyPhrases to Part Classes

KeyPhrases in part classes now apply down to the part number level and
part revision level. Using the Product Manager, a KeyPhrase added to a part
class also applies to the part number(s) and part revision(s) for that part
class. Adding KeyPhrases to this higher level eliminates some of the
redundancy in setting up your Problem Resolution System.

To activate this feature, you need to add new command buttons to the Part
Class window and the KeyPhrase Selection window.

Adding The KeyPhrase Button to the

Part Class Window
Use the button named CLASSSKP in the Part Class window to add
KeyPhrases to a part class. These KeyPhrases then apply to all the part
numbers and revisions associated with that part class.

To add the KeyPhrase button to the Part Class window

1. Open the Part Class window.
Use the Form Select window with the following filtering criteria:

• Title: Part Class

• Name: prtcled
• ID: 613
2. Add a new button just under the Next button, as shown in Figure 173.

324 Appendix A
 Adding KeyPhrases to Part Classes

Figure 173 Adding a KeyPhrase button to the Part Class window

Add a new button here.

Examples 325
Adding KeyPhrases to Part Classes

3. Open the Properties window for the new button and enter the following
information, as shown in Figure 174:

• Name: CLASSKP
• Text: KeyPhrase
• Button type: Command

NOTE: In order for this feature to work, the name of the button must be typed with
exactly the text specified.

Figure 174 CLASSKP Properties

Type “KeyPhrase” as the button label.

Type “CLASSKP” as the button name.

Make sure that the Button Type is Command.

4. If necessary, adjust the button location and size.

5. Close the Properties window and save the form.

326 Appendix A
 Adding KeyPhrases to Part Classes

Adding the KeyPhrase Button to the

KeyPhrase Selection Window
The KeyPhrase Selection window gives a user the ability to link a KeyPhrase
to a solution. When this window is posted from the Case window, the part
number associated with that case is automatically displayed. At this point,
the user can then search through the KeyPhrases associated with that part
number.

With the addition of the Class KeyPhrases button in the KeyPhrase Selection
window, a user can search for all KeyPhrases associated with that part
number’s part class.

To add the Class KeyPhrases button to the KeyPhrase Selection

window
1. Open the KeyPhrase Selection window.
Use the Form Select window with the following filtering criteria:

• Title: KeyPhrase Selection

• Name: slnpath3
• ID: 8102
2. Add a new button to the form, as shown in Figure 175.

Figure 175 Adding a Class KeyPhrase button

Add a new button in an

open area in the form.

Examples 327
Adding KeyPhrases to Part Classes

3. Open the Properties window for the button and enter the following
information as shown in Figure 176:

• Name: CLS_KP_BTN
• Text: Class KeyPhrases
• Button Type: Command

NOTE: In order for this feature to work, the name of the button must be shown
with exactly the text specified.

Figure 176 CLS_KP_BTN Properties

Type “Class KeyPhrases” as the button label.

Type “CLS_KP_BTN” as the button name.

Make sure that the Button Type is Command.

4. If necessary, adjust the button location and size.

5. Close the Properties window and save the form.

328 Appendix A
 Passing Login Information to Shell Scripts

Passing Login Information to Shell Scripts

The following keywords have been implemented. However, they do not
appear in the Action Editor window.
• login_name
• db_password
• db_server
• db_name
• encrypted_pw
These keywords work only for shell scripts. If you want to get this
information for a stored procedure, the information can be obtained by
executing the proper database command (for example, select
suser_name() in SYBASE).

These variables can be accessed on the command line of the button action as
arguments to the script or executable. The variable names must be enclosed
in braces {}. The following is an example command line:
scriptname -u {login_name} -p {db_password}
-db {db_name} -s {db_server}

Creating a Multigrid/MultiCBX Form

This example walks you through the creation of a new form that uses
extended contextual objects with both multigrid and multiCBX controls. The
sample form will have a grid control that can show either Employee or Site
data in the same grid.

Examples 329
Creating a Multigrid/MultiCBX Form

This example contains the following steps:

• Step 1: Create the Form and Add the Controls
• Step 2: Define a Resource Configuration
• Step 3: Define Contextual Objects
• Step 4: Define Control Properties
• Step 5: Define extended contextual object properties
• Step 6: Add ClearBasic Code to the Form
• Step 7: Test the Form

Step 1: Create the Form and Add the

Controls
To create the sample multigrid form
1. Start the UI Editor in ClearBasic mode.
Run the uiedit32.exe application with the -cb command-line option.
You must have a valid ClearBasic license to do this.
2. From the menu, choose File > New > Form, or click the New Form icon in
the toolbar.
A new form window appears as shown in Figure 177.

Figure 177 New Form window

3. Note the Form ID.

330 Appendix A
 Creating a Multigrid/MultiCBX Form

4. Add controls to the form.

Add the following controls:
• A grid control.
• Two dropdown list boxes. For now the list boxes are referred to
“Dropdown 1” and “Dropdown 2.”
• Three buttons. Call the buttons “Button 1,” “Button 2,” and “Button 3”
for now.
• A Select CBX control.
Your example will look similar to Figure 178. It does not matter where on
the form you place the CBX control, because CBX controls are not visible
in the CeFO application. (For the purposes of this illustration, the sample
form has been resized slightly.)

Figure 178 New form window with controls added

Button 1 Button 2
Dropdown 1 Dropdown 2

CBX

Grid

Button 3

5. Save the form.

In the next section, we will add the form to a new resource configuration,
and make sure the resource configuration has a user as a member.

Examples 331
Creating a Multigrid/MultiCBX Form

Step 2: Define a Resource Configuration

To define a resource configuration for the sample multigrid form
1. Add a resource configuration, and add a user to it.
Choose the menu option File > New > Resource Config... to create the
resource configuration, and use the Membership button on the Resource
Config window to add users.
For the purposes of this example, the resource configuration is called
“Resource 1.” Resource 1 has a user named Gamma Ray.
2. Add the form to the resource configuration.

Step 3: Define Contextual Objects

In this section we will add the contextual objects for the Employee and Site
data. For each of these data objects, we need one contextual object for
specifying grid properties and storing records, and one contextual object for
storing the grid selection.

To define the contextual objects for the sample multigrid form

1. Press F3 to bring up the Edit Form Contextual Objects window.
2. Add the Employee object.
Specify or select following values:
Name lor_employee
Database Object Typeemployee
Caption Employees
Sub Type Record List

332 Appendix A
 Creating a Multigrid/MultiCBX Form

Figure 179 Contextual objects for sample multigrid form

3. Add the Site object.

Specify or select following values and click Add:
Name lor_site
Database Object Typesite
Caption Sites
Sub Type Record List
4. Add a list to contain the Employee records.
Specify or select following values and click Add:
Name los_employee
Database Object TypeList (Primitive type)
Caption (No caption)
Sub Type Long
5. Add a list to contain the Site records.
Specify or select following values and click Add:
Name los_site
Database Object TypeList
Caption (No caption)
Sub Type Long

Examples 333
Creating a Multigrid/MultiCBX Form

6. Add three more objects as follows:

A string to store the current contextual object name. This is the
destination contextual object for Dropdown List 1, used to store the
user’s selection.
Name strSelObject
Database Object TypeString
Caption (No caption)
Sub Type n/a
A filter list to store the current list of available filters. This is the source
contextual object for Dropdown List 2, used as a source for the filter list
for the CBX.
Name lorFilterSet
Database Object Typefilterset
Caption (No caption)
Sub Type Record List
A list to store the currently selected filter. This is the destination
contextual object for Dropdown List 2, used to store the user’s selected
filter for the CBX.
Name losFilterSet
Database Object TypeLong
Caption (No caption)
Sub Type n/a
7. Click Done to exit the Edit Contextual Objects window.
In the next section, we will define the properties for each of the controls.
This includes assigning contextual objects to the controls that need them.

334 Appendix A
 Creating a Multigrid/MultiCBX Form

Step 4: Define Control Properties

Figure 180 shows how the controls will be named.

Figure 180 New form window showing control names

ddl_Object_select btn_Edit btn_Find ddl_Filter_List

mCBX7

mGrid1

CLOSE

To set the control properties for the sample multigrid form

1. Set the properties for the Grid control.
On the form, right-click the Grid control and open the Grid Properties
window. Change the Grid properties as follows:
Name mGrid1
multiCOBJ Yes
Note that when you select Yes for multiCOBJ, many of the list items
disappear from the Grid Properties window. Later in this example, you
will access those properties through the Extended Contextual Objects
window.

Examples 335
Creating a Multigrid/MultiCBX Form

2. Set the properties for the CBX control.

Change the CBX properties as follows:
Name mCBX7
multiCOBJ Yes
Instance Use_This
The instance is used to refer to the control in ClearBasic code. Note that
some properties also disappear from the CBX Properties when
multiCOBJ is set to Yes.
3. Set the properties for the first dropdown list box.
This is the list labeled “Dropdown 1” in Figure 178 to select the type of
object to display in the grid.
Change the properties as follows:
Name ddl_Object_Select
List Type Static List
Dest CObj strSelObject
Under the List Items property, click the ellipsis (...) to open the Item
Properties dialog box for the static list.
4. Enter the contents of the static list for the first dropdown list, as shown in
Figure 181.
Enter items as follows:
Item User DataDefault
Employee 0Yes
Site 1No
None 2No

336 Appendix A
 Creating a Multigrid/MultiCBX Form

Figure 181 Static dropdown list for sample multigrid/multiCBX form

This dropdown list will select which contextual object to display in the
grid. You will need to write a ClearBasic event handler to change the
contextual object based on user selection, using the “User Data” value.
5. Set the properties for the second dropdown list box.
This is the list labeled “Dropdown 2” in Figure 178 to select the filterset
for the CBX.
Change properties as follows:
Name ddl_Filter_List
List Type Clarify List
Dest CObj losFilterSet
Src CObj lorFilterSet
Src Field title (Title field from the list of filterset records
read by the CBX)
Long Value Yes
Object Column Yes

Examples 337
Creating a Multigrid/MultiCBX Form

6. Set properties for the first command button.

This is the button labeled “Button 1” in Figure 178 to edit the filter
criteria. This button will not have a caption; instead, it will display the
pencil icon that in CeFO signifies a user-editable filter.
Change the properties as follows:
Name btn_Edit
Icon Id 1152
Caption (Delete caption and leave blank)
7. Set the properties for the second command button.
We will use the button labeled “Button 2” in Figure 178 to execute the
Find command, after the user has specified filter criteria.
Change the properties as follows:
Name btn_Find
Caption Find
8. Set the properties for the third command button.
We will use the button labeled “Button 3” in Figure 178 as the Close
button for this window. Note that the button Name property is
pre-defined as a reserved name within CeFO.
Change the properties as follows:
Name CLOSE
Caption Done
9. Link the CBX control to the grid, the filter list, the Edit button, and the
Find button.
We will specify the filter list and grid as the locations to specify filter
criteria and then store/display the results of a filter operation. Change
the CBX Misc properties as follows:
Find btn_Find
Custom List mGrid1
Edit Filter btn_Edit
Select Filter ddl_Filter_List
Note that the first dropdown list (ddl_Object_Select) and the Done
button are not part of the CBX. You must code these controls separately
in ClearBasic.

338 Appendix A
 Creating a Multigrid/MultiCBX Form

10. Continue to set up extended contextual objects.

In the next section, we will add the extended contextual object properties.

Step 5: Define extended contextual object

properties
In this section we will define the extended contextual object properties.

To define extended contextual object properties for the sample

multigrid form
1. Press F4 to open the extended contextual objects window.
The Extended Contextual Objects window appears, as shown in
Figure 182. There are listings for each of the contextual objects we
defined in Step 3: Define Contextual Objects on page 332.

Figure 182 Extended Contextual Objects window

Examples 339
Creating a Multigrid/MultiCBX Form

2. Expand lor_employee and select the key property.

You will have to expand the lor_employee list item first, and then
expand the Properties list item (see Figure 183).
The first item under the Properties listings is an item with a key symbol
next to it, that bears the same name as the contextual object to which it
belongs. In this case, select the Properties list item called
lor_employee.
When you do this, a series of key/value pairs appears to the right.

Figure 183 Extended contextual objects: Enabling grid and CBX

Select the Grid and CBX check boxes to activate the Value columns.

3. Select the Grid and CBX check boxes for lor_employee.

The Grid and CBX values under the key/value section become editable.

340 Appendix A
 Creating a Multigrid/MultiCBX Form

4. Enter key/value pairs for lor_employee.

Enter only the most essential values. Normally, you would specify more
of them, but for now specify only the essential values.
Under Grid Properties:
Grid NamemGrid1
Destination Contextual Object Namelos_employee
Under CBX Properties:
CBX NamemCBX7
Objectemployee
Viewemployee
For the purposes of this example, we will ignore the CBX Filter
Properties... key/value item. Normally, you would use this to specify
which fields a user could create queries for. We are leaving this field
blank, which will prevent the user from creating custom queries. The
control will always return all records.
5. Select which fields from the employee object to display in the grid.
For each of the fields to display, select the list item on the left and select
the Grid check box. This causes a small grid icon to appear next to the list
item, as shown in Figure 184.
For the purposes of this example, select the following fields:
first_name
last_name
phone
e_mail

Examples 341
Creating a Multigrid/MultiCBX Form

Figure 184 Extended contextual objects: Select display fields

Select field and enable the Grid check box.

6. Enable the Grid and CBX check boxes and enter key/value pairs for
lor_site.
Under Grid Properties:
Grid NamemGrid1
Destination Contextual Object Namelos_site
Under CBX Properties:
CBX NamemCBX7
Objectsite
Viewsite
As before, ignore the CBX Filter Properties... key/value item. Select fields
from the lor_site object to display in the grid.

342 Appendix A
 Creating a Multigrid/MultiCBX Form

7. Select which fields from lor_site object to display in the grid.

For each field to display, select the list item on the left and select the Grid
check box. For the purposes of this example, select the following fields:
site_id
name
status
phone
8. Close the Extended Contextual Objects window.
9. Save the form.

In the next section, we will add the ClearBasic code necessary to operate the
form.

Step 6: Add ClearBasic Code to the Form

To add code to the sample multigrid form
1. With the form open, choose View > Code.
The View Code window appears, shown in Figure 185.
Select Form from the dropdown list on the upper left, if it is not already
selected. You should see text prompting you to enter your code:
Sub Form_Load()
End Sub

NOTE: If you had any controls on the form selected, the window will show the
code prompts for the control item instead of the form. Select Form from the
dropdown list to display the sub Form_Load() text.

Examples 343
Creating a Multigrid/MultiCBX Form

Figure 185 View Code for sample multigrid form

2. Specify a default contextual object to load with the form.

Add the following ClearBasic code:
Sub Form_Load()
Dim tempRec As New Record
tempRec.RecordType = "employee"
CObj_lor_employee.Fill tempRec
tempRec.RecordType = "site"
CObj_lor_site.Fill tempRec
ddl_Object_Select.SetSelected "Employee"
CBX_Use_this.SetCobj "lor_employee"
End Sub

344 Appendix A
 Creating a Multigrid/MultiCBX Form

This selects the Employee list item from the dropdown list control we
specified earlier in Step 3 on page 336.
This dropdown list had the Name ddl_Object_Select. In Step 4 of
that same series, we had specified this dropdown list as a Static List type;
in Step 5, we entered three list items: Employee, Site, and None.
3. Add code for the Close button.
Sub CLOSE_Click()
Me.Close
End Sub
4. Add code for the first dropdown selection list.
This code links the entries from the Static List (“Employee,” “Site,” and
“None”) to user selections and specifies which contextual object is set by
each user selection. The CBX control is referred to by its Instance Name
property (in this case, Use_This) rather than its name (mCBX7).
Sub ddl_Object_Select_Click()
Dim selItem As String
selItem = ddl_Object_Select.Selected
Select Case selItem
Case "Employee"
CBX_Use_This.SetCobj "lor_employee"
Case "Site"
CBX_Use_This.SetCobj "lor_site"
Case Else
CBX_Use_This.SetCobj ""
End Select
End Sub
5. Save the code and close the View Code window.
Next we will add a global code module.
6. Open a code window that is not associated with the form by choosing
File > New > Code Editor.
Here you should create ClearBasic code as part of the InitializeApp
routine. This should add a menu item to the CeFO application, which
will display this form. Replace the Form ID referenced below (1007) with
the Form ID from Step 3 on page 330.

Examples 345
Creating a Multigrid/MultiCBX Form

Sub Initialize_App
Dim CSMenu As New AppMenu
CSMenu.MenuBarId=1002
CSMenu.AddItem “Select”, “Employee/Site”,
“menuEmplSite”
App.ShowDefaultMenu
End Sub
Sub menuEmplSite_Click
Dim MyForm as New Form
MyForm.Show 1007, cbFrontIfUp
End Sub

Step 7: Test the Form

After you have created and coded the form, you can test the form in the
CeFO application.

To test the new form

1. Log in as a user belonging to the resource configuration to which you
added this form.
2. Use the Update Desktop command to ensure that the new form is cached
properly
3. Select the form from the application menu where you added it,
4. Test all functionality on the form.

346 Appendix A
 Appendix B

Customization Guidelines

In This Chapter
Adjusting the Form Size for Smaller Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
User Version Numbering for Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
Guidelines for CeFO Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
Default Control Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .353

347
Adjusting the Form Size for Smaller Monitors

Adjusting the Form Size for Smaller Monitors

Users with small monitors might not be able to work efficiently with CeFO
applications because of the size of the forms. You can adjust this size in the
User Interface Editor and provide a custom set of forms that are smaller and
easier to work with on small monitors.

Saving the New Form Size

If you are making a form smaller, move the form’s controls closer to the
upper-left section of the form. You can also delete controls to make space.

To resize a form, click on the lower-right corner of the form with your mouse
and drag the form to its new shape. After the form is the correct size, save
the form under a different version name.

User Preferences and Form Size

When a user resizes a form in CeFO applications, the size and position of the
form are kept in local memory as part of the user’s display preferences. If the
CeFO application was started with the “-save_geom” option, these
preferences are saved to the database when the user logs out of the CeFO
application.

The user’s display preferences always override any size and position
changes made in the User Interface Editor.

User Version Numbering for Forms

You assign a user version number each time you modify a form. You should
take great care when modifying a form so that you retain control of these
version numbers. The following methodology is recommended:
• When starting a new set of edits in the Development database, save the
form using a new user version number.
• During development, save updates under the same user version number.
• After development is complete and before exporting to any other
database, freeze the user version number. New edits should be applied to
a new user version number.

348 Appendix B
 User Version Numbering for Forms

If you use this methodology, the same version number is always the same
revision of the form in all databases in which that form/version is stored.
For example, suppose you want to customize the baseline New Case form.
You would complete the steps described in the following example.

To customize the baseline New Case form (example)

1. In the Development database, open the New Case form, and save the
form under user version 1.0.
2. Make or update a resource configuration to include the new user version.
3. Make yourself a member of that configuration.
4. Make the required modifications to the form and resave.
5. Test the edits using the CeFO application, and make more modifications
to the form if required.
6. Export the form.
7. Import the form into the Test database.
8. If the testing team is not satisfied with the form, open the Development
database, modify the form, and save it as version 1.1. (Saving it as a new
version even though it hasn’t gone through production is a good idea.
The users may change their minds and want the original 1.0 version. This
way you have preserved the 1.0 changes and won’t have to back out the
1.1 changes.)
9. When all parties are satisfied with the form, import the form into the
Production database.

Customization Guidelines 349

Guidelines for CeFO Forms

Guidelines for CeFO Forms

The following sections outline the guidelines for creating CeFO application
forms.

Grid Settings
• In the User Interface Editor application, choose View > Grid Settings and
select Snap to Grid and Display Grid. Set Grid Width and Grid Height to
8.

Form Size
• Form size should be 500 x 400 to allow for translation of the form into
other languages. The maximum form size is 748 x 471, assuming a screen
resolution of 800 x 600.
• When designing forms to be used on smaller displays (for example, 640 x
480 VGA), form size should be 400 x 300 to allow for translation of the
form into other languages. The maximum form size is 588 x 351.
• Smaller forms should be centered in the display when posted, not in the
upper-left corner of the CeFO application window.
• To ensure readability, set the margins to:
Top: 8 pixels
Bottom: 8 pixels
Left: 8 pixels
Right: 8 pixels
• For tabbed forms only: if a form is larger than needed for controls, leave
the excess space on the right and bottom sides.

Label Controls
• Text used to label other controls should be appended with a
colon (:). For example, Main Phone:
• Labels placed to the left of edit fields or combo boxes should be middle
aligned with the control, with the control being the reference.

350 Appendix B
 Guidelines for CeFO Forms

Text Box and Multiline Text Box Controls

• Text box controls should have the following dimensions:
Height: 20 pixels
Width: 8 pixels times the number of characters to be displayed
• Text boxes that contains date/time values should be at least 112 pixels in
width to ensure that 4-digit year values are displayed properly.
• Multiline text boxes should be at least 48 pixels in height so that a
minimum of three lines of text can be displayed.
• For multiline text boxes, add 24 pixels to the calculated width to allow for
space for the scroll bar without reducing space for the text.

List Box Controls

• List boxes should have the following dimensions:
Height: 48 pixels minimum, 72 pixels recommended
Width: 8 pixels times the number of characters to display. Add an
additional 24 pixels o allow room for the scroll bar.
A height of 48 pixels allows for three lines of text. A height of 72 pixels
allows for five lines of text.

Command Button Controls

• Command button controls should have the following dimensions:
Height: 20 pixels
Width: 80 pixels minimum
A height of 20 pixels ensures that the button label is displayed
properly.
• Picture button controls should have the following dimensions:
Height: 20 pixels
Width: 24 pixels minimum

Customization Guidelines 351

Guidelines for CeFO Forms

• When buttons are aligned in a column, the width of all buttons should be
the same.
• Buttons aligned in a column or in a row should be distributed with equal
distance between them.
• When command button controls post a form, a keystroke mnemonic
should be assigned to the button.
• All commands that post forms should be appended with
three dots (...). For example, Request Details...

Tab Controls
• Tab controls should be sized to show the largest child frame they contain.
• To account for the automatic addition of borders in the tab panel area, tab
controls should be at least 32 pixels wider and 40 pixels taller than the
largest child frame they contain.

NOTE: When laying out a form that contains a tab control, determine the size
of the tab control first. Then subtract 32 and 40 from the tab’s width and
height to determine the child frame dimensions.

• Child frames appearing in the same tab control should be the same size.

Tab Ordering
• Tab navigation should proceed from left to right and top to bottom
through the controls.
• When a form is posted, the cursor should be initially placed in the top left
corner of a form.

352 Appendix B
 Default Control Dimensions

Default Control Dimensions

Table 38 lists the default width and height for each control.

Table 38 Default control dimensions

Control Width Height

Label 80 16
Text box 80 20
Multiline text box 80 32
Group box 80 16
Command button 80 20
Check box 80 16
Option button 80 16
ComboBox 80 20
List box 80 32
Line 80 16
Grid 160 80
Tab 80 16
Dropdown combo box 80 20
Select CBX 100 100
ActiveX 50 50

Customization Guidelines 353

Default Control Dimensions

354 Appendix B
 Appendix C

User Interface Editor Commands and

Windows

In This Chapter
User Interface Editor Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
User Interface Editor Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361

355
User Interface Editor Commands

This appendix describes the commands and windows that appear in the
User Interface Editor.

User Interface Editor Commands

This section is a reference guide to the commands available in the User
Interface Editor.

File Menu
The following commands are available on the File menu.

New > Form (ClearBasic mode only) Creates a new form.

New > Child Form Creates a child form.

New > Code Editor (ClearBasic mode only) Creates an empty

global code module.

New > Resource Config Creates a new resource configuration (resource

configurations are used to assign different
versions of forms to users).

Open > Form Use to select a form to open.

Open > Child Form Opens a child form or displays a list of child
forms associated with the parent form.

Open > Global Code Module(ClearBasic mode only) Opens an existing

global code module.

Open > Resource Config Opens an existing resource configuration.

Open > Propagate Contextual Objects

Propagates contextual objects from a parent
form to a child form.

Merge Forms Combines two different versions of a form.

Save Form Saves changes to the current version of the

form. You cannot overwrite a baseline version
of a form.

356 Appendix C
 User Interface Editor Commands

Save Form As Saves changes to a different version of the

form.

Save Code (ClearBasic mode only) Saves changes to the

current code window to the database.
(Displayed only when a code window is
active.)

Save Code As (ClearBasic mode only) Saves the text in the

current code window to a file. (Displayed only
when a code window is active.)

Print Prints the form in the active window to the

selected printer.

Print Preview Shows how a document will look when you

print it.

Print Setup Lets you change margin, paper size, and

orientation.

Print List Prints the list of forms displayed in the Form

Select window.

Save List Saves the list of forms displayed in the Form

Select window.

Import Imports a form (in dat format) to the database

using dataex.

Export Exports a form in dat format using dataex.

Exit Quits the User Interface Editor application.

Edit Menu
The following commands are available on the Edit menu.

Undo Cancels the previous command.

Redo Repeats the last command.

Cut Copies selected controls or code to the

Clipboard and deletes them from the form.

Copy Copies the selected controls or code to the

Clipboard.

User Interface Editor Commands and Windows 357

User Interface Editor Commands

Paste Places objects in the clipboard onto the form.

Paste Special Available only when Copy Special was used

previously.

Delete Deletes selected controls from the form

without copying them to the Clipboard.

Select All Selects all controls in the fronted form.

Tab Order Displays the tab ordering between controls.

Button Actions Use a command button in a CeFO application

to invoke an operating system command, a
predefined script, a program, or a stored
procedure.

Contextual Objects Use to add, select, update, or remove

contextual objects associated with this form.

Extended Contextual ObjectsUse to edit the extended contextual objects

associated with a form.

Edit Template File Use to u add or edit method templates.

Associate Controls Use to associate or group option buttons.

Associate option buttons when a group
specifies one set of options.

Grid Wizard Use to select the source contextual object for a

grid and automatically define columns.

Verify Form Checks for duplicate mnemonics in the form.

Play Form Displays a form as it would appear on the

CeFO desktop.

View Menu
The following commands are available on the View menu.

Code (ClearBasic mode only) Displays the code for

the selected form.

Properties Window Displays the property window for the selected

control or form.

358 Appendix C
 User Interface Editor Commands

Control Inspector Displays the tab ordering between controls

and opens the Control Inspector window, from
which you can change the order of the
controls.

Grid Settings Displays the Grid Settings window, used to set

grid spacing.

Status Bar Displays or hides the status bar.

ToolBox Displays or hides the Toolbox toolbar.

Toolbars > Standard Displays or hides the Standard toolbar.

Toolbars > Form Editor Displays or hides the Form Editor (also called
the layout) toolbar.

Format Menu
The following commands are available on the Format menu.

Align > Tops Aligns selected controls along their top edges.

Align > Middles Aligns selected controls along the vertical

center (between top and bottom).

Align > Bottoms Aligns selected controls along their bottom

edges.

Align > Lefts Aligns selected controls along their left edges.

Align > Centers Aligns selected controls along their horizontal

centers (between left and right).

Align > Rights Aligns selected controls along their right

edges.

Align > Snap to Grid Moves selected controls to the nearest grid
unit.

Space Evenly > Across Spaces selected controls with equal distance
horizontally.

Space Evenly > Down Spaces selected controls with equal distance
vertically.

User Interface Editor Commands and Windows 359

User Interface Editor Commands

Center in Window > Vertical

Centers selected controls vertically within the
form.

Center in Window > Horizontal

Centers selected controls horizontally within
the form.

Size > Same Width Resizes selected controls to have the same
width.

Size > Same Height Resizes selected controls to have the same
height.

Size > Both Resizes selected controls to have the same

width and height.

Size > Default Resizes controls to their default size.

Size > Fit to Text Resizes controls, based on the length of the text
or number of lines of text in the control.

Code Editor Settings (ClearBasic mode only) Available only when

Code Editor window is open. Displays the
formatting and behavior options for the Code
Editor window.

Window Menu
The following commands are available on the Window menu.

Tile Resizes the opened forms within the User

Interface Editor so that all can be seen
simultaneously.

Cascade Stacks open forms on top of each other. The

last opened form is placed on top of the stack.

Fit to Window Resizes the active window to fit the

application window.

360 Appendix C
 User Interface Editor Windows

Help Menu
The following commands are available on the Help menu.

Clarify Help Not available.

About UI Editor Displays the version number of the User

Interface Editor and the name of the database
that is opened.

User Interface Editor Windows

This section is a reference guide to the windows that are specific to the User
Interface Editor. For each window, a screen capture shows the window
layout and fields, followed by field descriptions.

The windows are listed in alphabetic order.

Button Actions Window

Use the Button Actions window to “program” a button to invoke an
operating system command, a predefined script, a program, or a stored
procedure when the button is clicked.

The Button Actions window appears when you click the Button Actions tool
in the Layout toolbox, or choose Edit > Button Actions. Figure 186 shows
the Button Actions window.

More Information: For more information about assigning button actions, see
Chapter 12, Using the Action Editor.

Figure 186 Button Actions window

User Interface Editor Commands and Windows 361

User Interface Editor Windows

Command line

Field Definitions
Button Action Objects Displays the button action name when it is
saved. You can have more than one action
assigned to a button.

Action Name Name for the action. You can type up to 20

characters in this field.

Action Type Specifies the type of action: command (for

operating system commands, executables, and
script) or stored procedure (for stored
procedures in the database).

Platform Specifies the platform for which the action is

defined.

Mode Specifies the mode in which the action

executes: asynchronous (CeFO applications
can continue operating without waiting for the
completion of the action) or synchronous
(CeFO applications must wait for the action to
complete).

362 Appendix C
 User Interface Editor Windows

Order Specifies the order in which the action is

performed. You can define actions that are
performed before or after the standard action
of the button.

Contextual Object Fields Displays a list of the contextual object fields

available from this form. You can select fields
from this list as input arguments to the
command. You can also select fields from this
list as return values to store the results of the
action.

Copy Copies the field selected in the Contextual

Objects Field list to the Input Arguments or
Output Arguments list.

Remove Removes the selected field from the Input

Arguments or Output Arguments list.

Up Moves the selected field up in the list.

Down Moves the selected field down in the list.

Input Arguments Lists the contextual object fields that serve as

input arguments to the command or stored
procedure.

Output Arguments Lists the contextual object fields that serve as

return values from the command or stored
procedure.

Append Appends the selected fields in the Contextual

Objects Fields list to the end of the command
line specified in the Command Line text box.

Command Line Enter the syntax for this action. You can type
up to 256 characters in this field.

If the action is a command line, enter the

syntax for the command, including any
arguments.

If the action is a stored procedure, enter the

name of the procedure. You do not need to
append arguments for the stored procedure in
this text box. Use the list boxes to specify these
arguments.

User Interface Editor Commands and Windows 363

User Interface Editor Windows

Delete Removes the action from the button.

Add Adds the new action to the database, linking it

to the selected button.

Replace Replaces the button action definition with the

current edits.

OK Closes the Button Action window and saves

the edits made in the window.

Cancel Closes the Button Action window and discards

any edits made in the window.

Code Editor Window

Use the Code Editor window to edit the ClearBasic code associated with
your forms. The Code Editor window appears when you open the form
whose code you want to edit and choose View > Code. Figure 187 shows the
Code Editor window.

Figure 187 Code Editor window

Control list Event-handler list

Editing area

364 Appendix C
 User Interface Editor Windows

Field Definitions
Control list Use to select a control associated with the
form.

Event-handler list Use to select an event handler for the selected

control. A new stub is created in the editing
area.

Editing area Enter your ClearBasic code in this space.

Code Editor Settings Window

You can change the colors and text formatting for various code elements
using the Settings window. To display this window, open a form, open the
Code Editor window, and then choose Format > Code Settings. Figure 188
shows the Code Editor Settings window.

This window has two tabs.

Figure 188 Code Editor Settings Window (2 Tabs)

Format Tab Field Definitions

Color Lists each code element.

Foreground Specify font color.

User Interface Editor Commands and Windows 365

User Interface Editor Windows

Background Specify font background.

Font Specify font type.

Size Specify font size.

Reset All Click this button to reset everything to the

defaults.

Options Tab Field Definitions

Disable Syntax Helper Check this box to disable the automatic
statement completion that is applied when
certain code syntax is entered.

Control Inspector Window

Use the Inspector window to arrange the tab order of controls. This window
appears when you choose View > Control Inspector or when you click the
Control Inspector icon on the standard toolbar. Figure 189 shows the Control
Inspector window.

More Information: For more information about the arranging tab order between
controls, see Working with Controls.

Figure 189 Control Inspector (Tab Order) window

Control list

366 Appendix C
 User Interface Editor Windows

Field Definitions
Control list The first time you open the Control Inspector
after Saving a form, the control list displays all
controls in the form, arranged from the lowest
control ID number to the highest. (Except for
label controls, which display at the end of the
list)

OK Closes the Control Inspector (Tab Order)

window and applies any changes you made.

Cancel Closes the Control Inspector (Tab Order)

window and discards any changes you made.

Up Moves the selected entry up one in the list.

Down Moves the selected entry down one in the list.

Delete Removes the selected control from the form.

Edit Form Contextual Objects Window

Use the Edit Form Contextual Objects window to define the contextual
objects associated with a form. Controls can only access the contextual
objects associated with the form. Figure 190 shows the Edit Form Contextual
Objects window.

The Edit Form Contextual Objects window appears when you choose Edit >
Contextual Objects or click the Edit Contextual Objects property in the
Properties window.

More Information: For more information about contextual objects, see Chapter 10,
Understanding Contextual Objects.

User Interface Editor Commands and Windows 367

User Interface Editor Windows

Figure 190 Edit Form Contextual Objects window

Field Definitions
Contextual Object Name Enter a name for the contextual object in this
field. You can type up to 20 characters.

Database Object Type Opens the Object Type Selection window, used
to select the database type for the contextual
object. For more information about the
window, see Object Type Selection Window on
page 383.

Caption Caption of contextual object

Sub Type Used for some Database Object Types

(database objects and List data); disabled for
other types.

Contextual Objects list Lists the contextual objects linked to this form.

Propagate... Propagates contextual objects to child forms.

Add Adds the contextual object (specified by the

Contextual Object Name and Database Object
Type fields) to the list.

368 Appendix C
 User Interface Editor Windows

Replace Replaces the selected contextual object with

the information in the Contextual Object Name
and Database Object Type fields.

Do not edit standard CeFO contextual objects.

CeFO applications rely on links between
controls and these objects. Changing the
contextual objects may cause unexpected
application errors.

Delete Removes the selected contextual object from

the list.

Do not remove standard CeFO contextual

objects. CeFO applications rely on links
between controls and these objects. Changing
the contextual objects may cause unexpected
application errors.

Done Closes the Edit Form Contextual Object

window.

Edit Form Extended Contextual Objects

Window
Use this form to edit the key/value pairs associated with the extended
contextual objects of a particular form. To open this window, first open a
form, then either press F4 or choose Edit > Extended Contextual Objects
from the menu. Figure 191 shows the Edit Form Extended Contxtual Objects
window.

User Interface Editor Commands and Windows 369

User Interface Editor Windows

Figure 191 Edit Form Extended Contextual Objects window

Left Pane
Left pane shows an expandable treeview. Every contextual object associated
with the form has an associated extended contextual object listing in this
treeview.
Table 39
Extended contextual object

Property folder contains key/value pairs associated

with the extended contextual object.
Method folder contains key/value pairs associated
with methods.
Individual property listings, associated with
individual fields within a contextual object.

370 Appendix C
 User Interface Editor Windows

Table 39
Indicates key properties associated with the extended
contextual object.
Indicates that this node contains some user-defined
General properties.
Indicates a field to be displayed in a grid control.

Methods are user-defined key/value pairs.

Right Pane Field Definitions

Each node in the treeview has its own set of key/value pairs. The key/value
pairs displayed on the right changes as you select different Property or
Method listings from the treeview.

Key Lists key names for key/value pairs.

Value Lists values for key/value pairs.

Grid Enable this check box if the associated

extended contextual object is to be displaed in
a multigrid control.

CBX Enable this check box if the associated

extended contextual object is usee in a
multiCBX control.

Export to File Window

Use the Export to File window to save your customized form to a file on
your hard disk. The file can then be imported into another database. Files are
saved in the directory specified. Figure 192 shows the Export to File
window.

The Export to File window appears when you click the Export button in the
Form Select window, choose File > Export, or click Export in the Resource
Config window.

More Information: For more information about the Form Select window, see Form
Select Window on page 377.

User Interface Editor Commands and Windows 371

User Interface Editor Windows

Figure 192 Export to File window

Field Definitions
Save in Use to specify the directory to which the file is
to be saved.

File name Name of file to save the form.

Save as type Use to specify the file type. You can only select
dat files as the export file type.

Save Closes this window and saves the file to your

hard disk. A dialog prompts whether to export
privilege class information (Y/N).

Cancel Closes this window and discards any edits or

actions.

Extended Contextual Object Template

Window
In this window, you can add or modify any user-defined set of key/value
pairs used for adding key/value pairs to extended contextual object
properties (general properties only) or methods. You can view, but not
modify, any CeFO-defined templates.

To open this window, choose Edit > Edit Template File from the main menu
bar. If you have the Extended Contextual Objects window open, you can
right-click on a method or property in the treeview and select Edit Template
from the context menu that appears.

372 Appendix C
 User Interface Editor Windows

Tabs
This window has two tabs: Template and Edit Template. Figure 193 shows
the Templates tab on the Extended Contextual Object template window.
Figure 194 shows the Edit template tab.

Templates tab Shows all existing templates with icons.

Edit template tab Edit a selected template.

Figure 193 Extended Contextual Object Template: Templates tab

User Interface Editor Commands and Windows 373

User Interface Editor Windows

Field Definitions, Templates Tab

New Template Create a new template.

Delete Template Delete selected template.

Close Save changes and close window.

Cancel Cancel changes and close window.

Figure 194 ECobj Template window, Edit Template tab

Field Definitions, Edit Template Tab

Dropdown selection list Select template to edit

Key Name of the key for the key/value pair

Value Value to use for the key/value pair

374 Appendix C
 User Interface Editor Windows

Control Type Dropdown selection list has selections for text

box, dropdown list, contextual object list, and
contextual object field list.

Popup Name Dropdown selection list shows names of all

popup lists in all forms.

Form Merge Window

Use the Form Merge window to combine the layout and properties of two
different versions of a form. Figure 195 shows the Form Merge window.

The Form Merge window appears when you choose File > Merge Form.

More Information: For more information about merging forms, see Chapter 14,
Merging Different Form Versions.

Figure 195 Form Merge window

User Interface Editor Commands and Windows 375

User Interface Editor Windows

Field Definitions
1st Version Form ID Enter the identification number of the form to
merge.

1st Version CeFO Version Enter the name of the form to merge.

1st Version User Version Enter the user version number of the form to
merge.

2nd Version Baseline Merge against a baseline version of the form.

2nd Version Custom Merge against a custom version of the form.

2nd Version CeFO Version If merging against a baseline version, enter the
baseline version.

2nd Version User Version If merging against a custom version, enter the
user version.

Place results in version Enter the user version number of the merged
form.

Base merged form on Determines which version to use as the

foundation of the merged form.

Use drop down list data from

Determines which version to use if the items in
the dropdown list box control do not match.

If Both is selected, a superset of items from

both versions is used.

Use listbox data from Determines the version to use if the items in
the list box controls do not match.

If Both is selected, a superset of items from

both versions is used.

Use grid column data from Determines the version to use if the items in
the grid controls do not match.

If Both is selected, a superset of items from

both versions is used.

376 Appendix C
 User Interface Editor Windows

Use cbx data from Determines the version to use if the items in
the Select CBX controls do not match.

If Both is selected, a superset of items from

both versions is used.

Use activex data from Determines the version to use if the items in
the ActiveX controls do not match.

Preview Options Displays the Preview Options window, used to

define the merge report contents.

Preview Generates a report of differences between the

versions before merging the forms.

Merge Merges the form versions and generates a

report of differences between the versions.

Done Closes the Form Merge window.

Form Select Window

Use the Form Select window to open an existing form for viewing or editing
purposes. Figure 196 shows the Form Select window.

The Form Select window appears automatically when you start the User
Interface Editor or when you choose File > Open Form.

User Interface Editor Commands and Windows 377

User Interface Editor Windows

Figure 196 Form Select window

Form properties Comparison operators Property value

Form list

Field Definitions
Form properties Use to define the search criteria.

Comparison operators Select Starts With, Ends With, or Contains; for

Form ID, select =, >, <, >=, <=, or !=.

Property value Enter the value you want to search for.

Find Starts the query with your query criteria.

List Displays the forms that meet the search criteria

you entered in the filter fields at the top of the
window.

Description (read-only) Displays a description of the

selected form.

Items (read-only) Displays the number of forms that

meet your search criteria.

Export Exports the selected the form to a data file. For

more information, see Exporting and Importing
Forms on page 75 and Export to File Window on
page 371.

378 Appendix C
 User Interface Editor Windows

New Creates a new form.

Open Opens the selected form for editing.

Delete Removes the selected form from this database.

You cannot delete a baseline version of a form.

Done Closes the Form Select window.

Grid Settings Window

Use the Grid Settings window to set grid spacing when your form is in the
Edit mode. Figure 197 shows the Grid Settings window.

This window appears when you choose View > Grid Settings. You can also
click the Toggle Grid tool on the Layout toolbox to display or hide grid dots.

Figure 197 Grid Settings window

Field Definitions
Show Grid Displays or hides the grid marks in the form
edit window.

Snap to Grid Moves selected controls to the nearest grid

mark.

Width Horizontal distance between grid units (in

pixels).

Height Vertical distance between grid units (in pixels).

Guidelines Positions from the sides of the window at

which to place guidelines (in pixels).

User Interface Editor Commands and Windows 379

User Interface Editor Windows

OK Closes the window and applies the changes

you made.

Cancel Closes the window and discards any changes

you made.

Import Dat File Window

Use the Import Dat File window to import forms into your database.
Figure 198 shows the Import Dat File window.

The Import Dat File window appears when you choose File > Import.

Figure 198 Import Dat File window

File list

Field Definitions
Look in Use to select the directory where the data file is
located.

File list Displays files in the current directory with the

extension defined by the “Files of type”
dropdown menu.

File name Name of file to import.

Files of type Use to select which type of files to display in

the list. You can only import .dat files created
by dataex.

380 Appendix C
 User Interface Editor Windows

Open Imports the selected data file and closes the

Import Dat File window.

Cancel Closes the Import Dat File window without

importing any file.

Insert OLE Control Window

Use the Insert OLE Control window to select an ActiveX applet to place on
your form. Figure 199 shows the Insert OLE Control window.

This window appears when you click the ActiveX tool on the Object toolbox.

Figure 199 Insert OLE Control window

Field Definitions
Object Type list Lists the ActiveX controls found on your hard
disk.

OK Select an entry from the Object Type list and

click OK to insert that ActiveX control onto
your form.

Cancel Closes this window without inserting an

ActiveX control onto your form.

User Interface Editor Commands and Windows 381

User Interface Editor Windows

Membership Window
Use the Membership window to specify the CeFO users that belong to a
resource configuration. Figure 200 shows the Membership window.

The Membership window appears when you click Membership in the

Resource Config window.

More Information: For more information about the Resource Config window, see
Resource Config <title> Window on page 389.

Figure 200 Membership window

List users Wildcard matching List value

List criteria

Database
user list
Resource
user
list

Field Definitions
List users Use to define what type of users to search.

List criteria Use to define the search criteria.

Wildcard matching Select from this dropdown list to determine if

the query should match records that start with,
contain, or end with the other specified search
criteria.

List value Enter the value you want to search for.

Database user list Lists all CeFO users in the database who match
the search criteria.

382 Appendix C
 User Interface Editor Windows

List Starts the query with your search criteria.

Copy Copies the selected user(s) from the Database

user list to the Resource user list.

Remove Removes the selected user(s) from the

Resource user list.

Resource user list Displays the users assigned to the selected

resource configuration.

Done Closes the Membership window and assigns

the users in the Resource user list to the
resource configuration.

Object Type Selection Window

Use the Object Type Selection window to select the database object type for a
contextual object. Figure 201 shows the Object Type Selection window.

The Object Type Selection window appears when you click Database Object
Type in the Edit Form Contextual Objects window.

More Information: For more information about the Edit Form Contextual Object
window, see Edit Form Contextual Objects Window on page 367.

Figure 201 Object Type Selection window

Object criteria Object value

User Interface Editor Commands and Windows 383

User Interface Editor Windows

Field Definitions
Object criteria Use to define the search criteria.

Object value Enter the value you want to search for.

List Starts the query with your search criteria.

Database Type Lists the available object types for contextual

objects.

Starting the User Interface Editor with the -cb

option adds more entries to this list.

Use/Done Uses the selected database object type for the

contextual object and closes the Object Type
Selection window.

Done Closes the Object Type Selection window.

Preview Differences Options Window

Use the Form Merge Preview Differences Options window to define the
report contents when merging forms. Figure 202 shows the Preview
Differences Options window.

The Form Merge Preview Differences Options window appears when you
click Preview Options in the Form Merge window.

More Information: For more information about the Form Merge window, see Form
Merge Window on page 375. For more information about merging forms, see
Chapter 14, Merging Different Form Versions.

384 Appendix C
 User Interface Editor Windows

Figure 202 Preview Differences Options window

ID check boxes Determines whether differences in the control

ID numbers are listed in the merge report.

X,Y,W,H check boxes Determines whether differences between form

or control sizes and positions are listed in the
merge report.

Options check boxes Determines whether differences between the

form or control properties are listed in the
merge report.

Title check box Determines whether differences between the

form titles are listed in the merge report.

Text check box Determines whether differences between the

text for label controls are listed in the merge
report.

Format check box Determines whether differences between the

format of text boxes are listed in the merge
report.

Data check boxes Determines whether differences in the

available choices for dropdown list boxes, list
boxes, or dropdown combo boxes are listed in
the merge report.

Label check boxes Determines whether differences between the

control labels are listed in the merge report.

User Interface Editor Commands and Windows 385

User Interface Editor Windows

Columns check box Determines whether differences between

custom list columns are listed in the merge
report.

Ctx Objects check box Determines whether differences between

contextual objects for the forms are listed in the
merge report.

Source check boxes Determines whether differences between

source links for controls are listed in the merge
report.

Destination check box Determines whether differences between

destination links for controls are listed in the
merge report.

Src/Dest check boxes Determines whether differences between

source and destination links for controls are
listed in the merge report.

Max Len check box Determines whether differences between the

maximum length property for text boxes are
listed in the merge report.

Popup List check box Determines whether differences between the

pop-up lists selected for dropdown list box
controls are listed in the merge report.

Group check box Determines whether differences in the

grouping of option button controls are listed in
the merge report.

Frame check box Determines whether differences between the

command buttons used to display frames are
listed in the merge report.

Done Closes the Form Merge Preview Differences

Options and saves the edits you made.

Propagate Contextual Objects Window

Use the Propagate Contextual Objects window to update the contextual
objects associated with a child form or tab.

386 Appendix C
 User Interface Editor Windows

Figure 203 Propagate Contextual Objects window

Field Definitions
Form ID Displays the ID of the parent form.

To ID Displays the ID of the child form.

CeFO Version Displays the CeFO version number associated

with either the parent form or child form.

User Version Displays the User version number associated

with either the parent form or child form.

Propagate Contextual Objects Window

(Multi)
Use the Propagate Contextual Objects window to update the contextual
objects associated with a child form or tab. This window appears when you:
• Right-click a form and select Propagate Contextual Objects
• Choose File > Open > Propagate Contextual Objects
This window appears when you select Propagate Contextual Objects from a
form which has multiple child forms, and when no control is selected that is
connected with a particular child form.

Figure 204 shows the Propagate Contextual Objects window.

User Interface Editor Commands and Windows 387

User Interface Editor Windows

Figure 204 Propagate Contextual Objects (multiple)

Field Definitions
Form ID ID of the parent form from which to propagate.

Base Version CeFO baseline version; refers to the version of

the CeFO product from which this form was
originally derived.

User Version User-defined version of this form. You cannot

propagate from a baseline form, because
baseline forms are non-editable.

Filter Using Resource Config

Dropdown selection list lets you filter to show
child forms from different resource
configurations.

Child Forms Lists all child forms that are part of this
resource configuration.

388 Appendix C
 User Interface Editor Windows

Properties Window
Use the Properties window to view or define control and form properties. To
view this window, right-click on a form or a control, or choose View >
Properties Window. Figure 205 shows the Properties window.

Figure 205 Properties window

Field Definitions
The properties displayed depend on which control is selected. For more
information about properties, see Viewing the Properties Window on page 93
and Chapter 5, Working with Controls.

Resource Config <title> Window

Use the Resource Config window to assign versions of the application forms
to users. Figure 206 shows the Resource Config window.

The Resource Config window appears when you click the Open button in
the Select Resource Config window.

User Interface Editor Commands and Windows 389

User Interface Editor Windows

More Information: For more information about the Select Resource Config
window, see Select Resource Config Window on page 392. For more information
about using resource configurations, see Defining a Resource Configuration on
page 62.

Figure 206 Resource Config window

Field Definitions
Configuration Title Enter a name for the resource configuration.
You can type up to 20 characters in this field.

Description Enter a description for this resource

configuration. You can type up to 255
characters in this field.

Resource criteria Use to define the search criteria.

Resource value Use to define the value to search for.

390 Appendix C
 User Interface Editor Windows

Database Displays a list of forms that match the

specified criteria.

The last column in this list indicates whether

the form is the CeFO baseline version
(indicated by a B) or a custom version
(indicated by an empty field).

List Lists database forms that match the specified

filtering criteria.

Copy Copies a selected form from the Database list

to the Resource Config list.

Remove Removes the selected form from the Resource

Config list.

Pre-Load Writes the selected form to the cache file

during login.

On Demand Indicates that the selected form version will be

read by the CeFO application only when
invoked by the user.

Resource Config Determines whether all forms or just

customized forms are displayed in the
Database list.

Membership Use to specify the CeFO users who belong to

this resource configuration.

Add Adds the resource configuration to the

database.

Replace Replaces the definition of the resource

configuration with the changes made in this
window.

Discard Closes the Resource Config <Title> window

and discards any edits. If this is a new resource
configuration, it is not saved to the database.

Done Closes the Resource Config <Title> window

and saves the edits.

User Interface Editor Commands and Windows 391

User Interface Editor Windows

Save Form As Window

Use the Save Form As window to save a form to your hard disk. Select File >
Save Form As to view this window. Figure 207 shows the Save Form As.

Figure 207 Save Form As window

Field Definitions
Name/ID (read-only) Displays the CeFO name and ID
number of this form.

User Version Enter a unique user version for this form to

identify your customized form.

CeFO Version (read-only) Displays the CeFO version number

of this form.

Description Enter a brief description of the form here.

Cancel Closes the Save Form As window without

saving the form to the file.

Save Closes the Save Form As window and saves

the form to the selected file.

Select Resource Config Window

Use the Select Resource Config window to select which resource
configuration to view or modify. Figure 208 shows the Select Resource
Config window.

392 Appendix C
 User Interface Editor Windows

The Select Resource Config window appears when you choose File > Open >
Resource Configuration.

More Information: For more information about using resource configurations, see
Defining a Resource Configuration on page 62.

Figure 208 Select Resource Config window

Configuration

Configuration value

Field Definitions
Configuration Use to define the search criteria.

Configuration value Enter the value to search for.

List Starts the query based on the search criteria.

Configuration list Displays a list of resource configurations that

meet your query criteria

Description (read-only) Displays a description of the

resource configuration.

Export Export the selected resource configuration to a

dat file. For more information about exporting
resource configurations, see Exporting Resource
Configurations on page 71.

User Interface Editor Commands and Windows 393

User Interface Editor Windows

New Creates a new resource configuration. For

more information about resource
configurations, see Defining a Resource
Configuration on page 62 and Resource Config
<title> Window on page 389.

Open Opens the selected resource configuration. For

more information about the Resource
Configuration window, see Resource Config
<title> Window on page 389.

Delete Removes the selected resource configuration

from the database.

Done Closes the Resource Config window.

394 Appendix C
Index
A controls to a form 98
About command 50 fields to filter properties 220
action controls 98, 127–152 forms to a resource configuration 63–67
Action Editor 259–275 grids to forms 197–199
Form Init actions 268 items to menus 80–81
actions KeyPhrases to part classes 324
adding buttons to invoke 269–271 method templates 255
adding command buttons 273 methods, extended contextual objects 253
asynchronous 261 multi-field filtering 302–309
button control 262 option button groups 157
command-line syntax 263 tabs 142
defining 265–269 users to a resource configuration 70
example 271–275 additional documentation 16
execution 264 adjusting tab order 146
Form Init 268 alignment
function with CeFO applications 260 commands 51
how they work 262–264 controls 90
infinite loops 262 Animation command 53
input/output arguments 265–267 animation control 113
invoking stored procedures 261 properties 113
platform differences 265 appearance, graphs 116
synchronous 261 applications, user interface 22
types 260 arguments, input and output 265–267
ActiveX command 54 arranging controls 83–96
ActiveX controls 110–112 asynchronous actions 261
properties 112 attributes of controls 93
sharing 111 auto-indenting 280
ad hoc queries 221 automatic statement completion 280
adding AVI clips 113
buttons to invoke actions 269–271
B
code modules to forms 281
baseline forms 24, 61, 73
command button actions 273
Bitmap command 52
context-sensitive menus for controls 106–108
bitmap control 114
contextual objects to forms 230–232
bounding boxes 84
buddy controls 190

395
Button Actions code
command 51 adding to a form 281
window 361–364 adding to forms 343
button control 128–139 creating global modules 283
actions 262 customizing CeFO 34
command buttons 129–132 editing 283
form init button 133 saving 283
frame buttons 133–137 Code Editor
icons 137 adding code modules to forms 281
mnemonics 129–132 auto-indenting 280
multiline text boxes 167 automatic statement completion 280
picture buttons 137–138 colors 279
properties 138 features 278–281
reserved names 138 Settings window 365
types of buttons 128 using 277–284
window 278, 364
C colors, Code Editor 279
cb option 39 columns
CBX controls 98 adding to grids 200
CeFO application links 196
customizing 35 modifying 203
defined 15 Command button command 53
CeFO Web client, customizing 33 command buttons 129–132
centering commands 51 assigning mnemonics 129–132
centering controls 86 controls 351
changing command-line syntax, actions 263
property values 95 commands
tab order 103–105 Edit menu 357
Check box command 53 File menu 356
check box control 154–155 Format menu 359
child forms 60, 133 Help menu 361
adding contextual objects 238 UI Editor 356–361
Close/Done buttons 135–137 View menu 358
creating 75, 142 Window menu 360
dismissing 134 Compile command 50
extended contextual objects 239 concatenation 164
ClearBasic, See code configuration, resource 61
client-server architecture 24 configuring
Close/Done buttons, child forms 135–137 baseline resources 61
extended contextual objects 251–254

396 Index
conflicts, resolving for mergers 292 bitmap 114
context-sensitive menus 56, 106–108 buddy 190
adding items 80–81, 106 CBX 98
extended contextual objects 250 centering 86
handling events 108 changing tab order 103–105
modifying 107 check box 154–155
contextual objects 24, 195, 225–241 command button 351
adding to child forms 238 control ID numbers 103
adding to forms 230–232 copying and pasting 89
compared to extended contextual objects 245 default dimensions 353
Contextual objects command 51 deleting 88
data types 233 deselecting 85
defining 332 display 98, 109–125
definition 226 distributing 91
designing 227 dropdown combo box 185–188
destination 226 dropdown list box 175–179
extended, See extended contextual objects examples 55
how they work 25 forms 350
linking controls to 235–237 graph 116–118
linking to a form 229–232 grid 98, 194–211
names 233 group box 118–119
propagating 238–241 input 98, 153–192
simple grids 195 label 120–124
source 226 layout and arranging 83–96
sub types 234 line 124
types 196 linking to contextual objects 235–237
user-defined types 235 list box 171–174, 351
control ID property 103 moving 86
Control Inspector command 50, 104 multiCBX 222
Control Inspector window 366 multiline text box 167–170
control properties 99–103 naming conventions 102
defining 335 navigation 98, 127–152
viewing 46 option button 155–158
controls pop-up list dropdown list box 180–184
action 98, 127–152 progress bar 125
adding 98 reserved names 102
adding context-sensitive menus 106–108 resizing 86
aligning 90 select CBX 212–224
animation 113 selecting 84
attributes 93 selection order 85

Index 397
 slider 188 recommended flow 35
spacing 91 using Data Dictionary Editor 33
SQL, adding to queries 317–324 WIPbin window ??–299
tab 103–105, 139–149, 352 Cut command 49, 89
text box 159–166
treeview 150–152
D
types 98, 236 Data Dictionary Editor
updown 190–192 using 33
user interface 24 data types
working with 97–108 definition 233
conventions used in this guide 18 specifying 233
Copy command 49, 89 data, user interface 22
copying extended contextual objects 250 database customization 32
correcting mistakes 57 date/time text boxes 161
creating ddcomp utility 34
child forms 75 default
form modules 281 control dimensions 353
forms 350 tabs, setting 147
global code modules 283 text, entering 162, 168
multiCBX forms 329–346 defining
multigrid controls 251 actions 265–269
multigrids 205–208, 329–346 Form Init actions 268
parent forms 77 input/output arguments 265–267
resource configurations 62–71 resource configurations 62–71
slider controls 188 stored procedures 272
currency text boxes 161 deleting
custom lists 194 controls 88
customizing forms 292
CeFO database 32 deselecting controls 85
CeFO Web client 33 designing
ClearBasic 34 contextual objects 227
ddcomp utility 34 tab layout 142
Find Caller 300, 302 destination contextual objects 226
forms 24, 74 difference reports
guidelines 347–352 merging forms 288
mobile implementation 34 previewing 290
opening forms 40 dimensions of controls 353
Policies and Customers application 34 disabling automatic statement completion 280
Queue window ??–299 dismissing child forms 134

398 Index
displaying Extended Contextual Object Template window
display controls 98, 109–125 372–375
display grid layout 57 extended contextual objects 29, 239
key/value pairs 247 adding methods 253
pictures in buttons 137 compared to contextual objects 245
user interface 31 configuring 251–254
distributing controls 91 context menus 250
DOS prompt, starting UI Editor 39 Copy Special 250
Dropdown Combo box command 53 defining properties 339
dropdown combo box control 185–188 editor, using 243–258
list items property 187 nodes 248
properties 186 overview 244
Dropdown List box command 53 Paste Special 250
dropdown list box control 175–179 properties and methods 247
labeling 175 treeview navigation 248
limit per form 175 window 244
properties 184
F
static lists 177
field arrays 194
types 176
File menu commands 356
duplicate mnemonics 132
filters
E adding custom filters 302–303
Edit Form Contextual Objects window 367–369 Find Caller customizations 300
Edit Form Extended Contextual Objects window properties 220
369 required 316
Edit menu commands 357 find and replace, using 168
editing Find Caller feature, customizing 300–302
code 283 fixed toolbars 48
controls 89 flags 81
edit fields 159 focus objects 23
filter properties 220 Form Editor toolbar 50
forms 43 form ID ranges 42
grids 203 Form Init actions 268
entering default text 162, 168 form init button 133
examples of customizing 295–329 form license dependencies 81
executing actions 264 Form Merge window 375–377
Export to File window 371 form modules, creating 281
exporting Form Select
forms 75 filter criteria 41
resource configurations 71 window 377–379

Index 399
Format menu commands 359 on-demand 68
formatting opening 40
characters, input masks 165–166 overview 60
format property 164 parent 60, 77, 133
text, Code Editor 279 previewing 45
forms 23 previewing difference reports 290
adding code 281 properties 79
adding contextual objects 230–232 query 172
adding controls 98 recommended sizing 93
adding grids 197–199 reconciling different versions 285–293
adding to a resource configuration 63–67 removing from a resource configuration 69
adjusting size 348 resizing 92
baseline 24, 61 resolving merging conflicts 292
changing names 101 saving 47, 74
child 60, 75, 133, 134–137, 142 searching by ID 42
code, adding 343 select, creating 214–220
command button controls 351 simple 25, 26, 29
comparison of simple and multipane 29 single-table 25
contextual objects 24 size 350
creating 350 specifying as pre-loaded 68
creating multigrid/multiCBX 329–346 SQL feature 318
custom 24 template 82
customizing 347–352 testing 346
deleting 292 text box controls 351
difference reports 288 user version numbering 348
displaying information 31 using Form Select window 41
editing window 43 working with 59–82
examples of customizing 295–329 form-specific code 278
grid settings 350 frame buttons 133–137
importing and exporting 75 frames
label controls 350 tab controls 352
layouts 25 tab ordering 352
linking contextual objects 229–232 free-floating toolbars 48
list box controls 351
making changes available to users 32
G
merging 285–293 global code modules 278
modifying 73 Code Editor window 278
multiCBX 329–346 creating 283
multigrid 329–346 identifying strings 283
multipane 25–29, 147 Graph command 54

400 Index
graph control 116–118 Import Dat File window 380
graph appearance 116 importing forms 75
properties 117–118 input
specifying graph data 116 arguments, actions 265–267
Grid command 53 controls 98, 153–192
grid controls 98, 194–211 masks 165–166
adding columns 200 Insert OLE Control window 381
adding grids to forms 197–199 Inspector command 104
column display 199 Inspector window 366
column links 196 invoking
column properties 209 actions 269–271
creating multigrids 205–208 stored procedures 261
making grids editable 203
modifying columns 203
K
multigrids 194 key/value pairs 30
properties 208–211 copying and pasting 250
simple grids 194 displaying 247
using the grid wizard 200–202 using method templates 254–258
grid markings keyboard
command 51 navigation, treeview control 151
setting up 57 shortcut buttons 129–132
Grid Settings window 379 KeyPhrases, adding to part classes 324
grid settings, forms 350 L
grid wizard 200–202
Label command 52
Group box command 53
label control 120–124
group box control 118–119
forms 350
properties 119
properties 122
grouping option buttons 157
layouts
guide conventions 18
controls 83–96
H forms 25
handles, bounding boxes 84 grid markings 57
handling menu events 108 tab control 142
Help menu commands 361 licensing options 81
hide toolbox command 49 Line command 53
hierarchical pop-up lists 180 line control 124
how to use this guide 16 linking
contextual objects 229–232
I controls to contextual objects 235–237
ID, forms 42 List box command 53
identifying strings, code modules 283

Index 401
list box control 171–174, 351 moving
labeling 171 controls 86
pop-up list 180–184 toolbars 48
properties 174 multiCBX
used in query forms 172 controls 222
listing properties and methods 247 forms, creating 329–346
login dialog box 38 multi-field filtering
login information, shell scripts 329 adding 302–309
Long Value property 183 adding to a Sort By list 309
adding to Select Contracts window 306–308
M database objects 303
mask edit text boxes 162 described 304
Membership window 382–383 windows using 303
menus multigrids 194
context-sensitive, See context-sensitive menus column properties 209
shortcut 56 creating 205–208, 329–346
merging forms 285–293 creating controls 251
generating reports 288 Multiline text box command 53
resolving conflict 292 multiline text box control 167–170, 351
specifying 286–288 entering default text 168
methods find and replace 168
adding, extended contextual objects 253 properties 167, 169
extended contextual objects 30, 247 types 167
part selection, changing 310–316 multipane forms 25–29
templates 254–258 tab control 147
mistakes, correcting 57
mnemonics N
assigning to buttons 129–132 names
duplicates 132 contextual objects 233
limitations 132 name property 101
precedence 132 naming conventions 102
tab control 141 reserved 102
mobile implementation, customizing 34 reserved for buttons 138
modifying navigation
context-sensitive menus 107 controls 98, 127–152
forms 73 extended contextual objects 248
grid columns 203 slider controls 189
monitors, adjusting form size 348 New Case window 313
mouse, using 56 New form command 49

402 Index
NEW_FILTER contextual object Paste Special command 89
adding custom fields 305 pasting extended contextual objects 250
database objects used 303 pathnames 19
list of windows containing 303 picture buttons 137–138
using for custom filtering 302 planning for tabs 142
nodes platform differences, actions 265
extended contextual objects 248 Play form command 49
treeview control 150 Policies and Customers application 34
numbering pop-up list dropdown list boxes 180–184
control ID 103 pre-loaded forms 68
forms 348 Preview Differences Options window 384–386
previewing forms in UI Editor 45
O Print command 50
Object Type Selection window 383–384 Progress bar command 53
objects progress bar control 125
contextual 24 Propagate Contextual Objects command 238
extended contextual 29 Propagate Contextual Objects window 386–388
focus 23 propagating contextual objects 238–241
related 23 properties
workflow 22 ActiveX controls 112
.ocx extension 110 animation control 113
on-demand forms 68 button control 138
opening changing the value of 95
forms 40 control ID, using 101
global code modules 284 control, viewing 46
Open form command 49 controls 99–103
Option button command 53 correcting mistakes 95
option button control 155–158 dropdown combo box 186
adding option buttons 157 dropdown list box control 184
grouping 157 extended contextual objects 30, 247
passing values 156 filter, editing 220
properties 158 forms 79
ordering tabs 146, 352 graph control 117–118
output arguments, actions 265–267 grid controls 208–211
P label control 122
line control 124
parent forms 60, 133
list box control 174
adding tab controls 143–146
multiline text box control 167, 169
creating 77
name, using 101
part selection methods, changing 310–316
option button control 158
Paste command 49, 89

Index 403
 progress bar control 125 defining 332
Properties command 49 definition 60
select CBX control 222 exporting 71
slider control 189 how it works 61
tab control 148 removing forms 69
text box control 159, 163 removing users 70
treeview control 151 users 61
updown control 191 restrictions, tab control 141
Properties window 94, 389
S
Q Same height command 51
queries Same size command 51
ad hoc 221 Same width command 51
adding SQL controls 317–324 Save Form As window 392
forms, using list boxes 172 saving
SQL feature use in forms 318 code 283
Queue window, customizing ??–299 customized baseline forms 74
forms 47
R Save form command 49
radio buttons 155 searching by form ID 42
Redo command 49 See also multi-field filtering
reference Select CBX command 54
additional documentation 16 select CBX control 212–224
controls 85, 87 ad hoc queries 221
related objects 23 adding custom filters 303
removing users from a resource configuration 70 creating select forms 214–220
reports filter properties 220
generating for merged forms 288 properties 222
parameters 289 Select ClearBasic extension, See Select CBX control
previewing 290 select forms, creating 214–220
required Select Resource Config window 392–394
filters, specifying 316 selecting
reserved button names 138 cancelling control selection 85
resizing controls 84
controls 86 Select command 52
forms 92 selection order controls 85
Resource Config window 389–391 setting default tabs 147
resource configuration 32 setting up grids 57
adding forms 63–67 sharing ActiveX controls 111
adding users 70 shell scripts, login information 329
creating 62–71

404 Index
shortcut menus 56, 106–108 sub types, contextual objects 234
shortcuts 129–132 synchronous actions 261
Show/hide toolbox command 49 syntax, command-line 263
shown/hidden tab titles 139
simple forms 25, 26, 29
T
simple grids 194 Tab command 53
column properties 209 tab control 139–149, 352
single-level pop-up lists 180 adding to parent form 143–146
single-table forms 25 adjusting ordering 146
size creating child forms 142
adjusting for forms 348 layout 142
forms 350 multipane forms 147
sizing forms 93 planning 142
tabs 146 properties 148
Slider command 54 restrictions 141
slider control 188 setting the default 147
creating 188 shown/hidden tab titles 139
navigation 189 sizes 146
properties 189 using updown control 191
small monitors, resizing forms for 348 tab order
snap-to-grid option 57 changing 103–105
source contextual objects 226 standard format 352
spacing commands 51 Tab Order command 105
spacing controls 91 templates
specifying forms 82
forms to merge 286–288 method 254–258
graph data 116 testing forms 346
required filters for part selection 316 Text box command 53
SQL controls 317–324 text box control 159–166
standard toolbar 48 entering default text 162
starting the UI Editor 38 format property 164
ClearBasic mode 39 forms 351
static lists 177 input masks 162, 165–166
stored procedures properties 159, 163
defining 272 types 160–162
invoking with actions 261 text concatenation 164
login information 329 text formatting 279
storing values 179 toolbars
fixed 48
Form Editor 50

Index 405
 free-floating 48 controls 24
moving 48 description 21–35
standard 48 extended contextual objects 29
toolbox 52 form layouts 25
UI Editor 48–54 forms 23
Treeview command 54 how it is displayed 31
treeview control 150–152 overview 22
navigation 151 workflow objects 22
properties 151 user version numbering for forms 348
types of controls 98 user-defined contextual objects 235
typographical conventions 19 User-defined Data Types 39
using
U Code Editor 277–284
UDTs 39 command buttons 129–132
UI Editor the mouse 56
commands 48–52, 356–361
controls 55 V
creating global code modules 283 values
customizing guidelines 347–352 passing from options 156
customizing the CeFO database 32 properties 95
examples of customizing 295–329 slider control 188
form editing window 43 storing 179
opening forms 40 versioning
starting 38 difference reports for forms 288
starting from a DOS prompt 39 numbering, forms 348
starting with the cb option 39 View code command 50
toolbars 48–54 View form command 50
windows 361–394 View menu commands 358
uiedit 39 viewing
Undo command 49, 89 contextual object lists 229
undo command 57 control properties 46
UpDown command 53 Properties window 94
updown control 190–192
keyboard navigation 190
W
properties 191 Window menu commands 360
rotating through tabs 191 windows
user data column, static lists 178 Button Actions 361–364
user interface Code Editor 278, 364
applications and data 22 Code Editor Settings 365
contextual objects 24 Control Inspector 366
Edit Form Contextual Objects 367–369

406 Index
 Edit Form Extended Contextual Objects 369
Export to File 371
Extended Contextual Object Template 372–375
extended contextual objects 244
Form Merge 375–377
Form Select 41, 377–379
Grid Settings 379
Import Dat File 380
Insert OLE Control 381
Membership 382–383
New Case, customizing 313
Object Type Selection 383–384
Preview Differences Options 384–386
Propagate Contextual Objects 386–388
Properties 94, 389
Resource Config 389–391
Save Form As 392
Select Resource Config 392–394
UI Editor 361–394
WIPbin window, customizing ??–299
workflow objects 22
writing code 278

Index 407
408 Index