Forms Expert - 
Scripting with the new Runtime Object

Have you ever wanted to add some Controls to a Detail Form, say a push button or check box, without have to create the corresponding fields in the database? Well in Commence RM 3.0 you can now do this! And what's more, you have full control of the properties of those Controls from VBscript.

For some time now Commence has enabled you to add a graphical control like a Push Button or Checkbox. However, very often, these controls have not mapped to any real data fields - they have only been required while the Detail Form is up on the screen, say to assist in data entry and data checking. Until now, the only way to create these Controls was to add them as fields in the Category - although this provided a good solution, it was cumbersome and meant that there were redundant fields created in the database.

In the last CRMtimes, the Forms Expert article "CommenceRM 3.0 Detail Form Designer", explained how to add Controls to a Detail Form. In this article we will focus on how to control the behaviour of these Controls (which do not map to real fields) through VBScript - this is a big subject, and we only have space here for a brief introduction.

Please note that this article assumes you are already familiar with developing VBscripts in detail forms. For more information, refer to the section on VBscripting in detail forms in the Commence User Guide. You will also benefit from developing in a tool such as ScriptEZ.

Unbound Controls

In the Commence RM 3.0 Form Designer, we can distinguish between Bound Controls and Unbound Controls. 

The Bound Controls are essentially the fields we have always used - each user interface control (i.e. text field, selection, etc) maps directly to a field in the database. In fact, if you check the DataField property for the control, you will see that it specifies a valid field in the database.

Unbound Controls are those that do not map to a field in the database. Any values you put into an Unbound Control will exist only while the form is open.

FormRuntime object

To access an Unbound Control, you need to define and set a FormRuntime object. You can think of this object as the collection of all the Controls on the form. 

The code you need is as follows:

Dim oFmRt
Set oFmRt = Form.Runtime

Control Object

Once the FormRuntime object is defined, you can access individual controls through the Control object. The first step is to find out the Control name - this is most easily done by selecting the Control in Form Designer, and noting the name displayed in the bottom left hand corner. Now you can set the properties associated with that control.

For example to hide a textbox (TextBox10), the code would be 

oFmRt.GetControl("TextBox10").visible = False

To make the Control visible again

oFmRt.GetControl("TextBox10").visible = True

To change the background colour to light blue, set the default text, and also change the tooltip

oFmRt.GetControl("TextBox10").BackColor = 
   "16777088"

oFmRt.GetControl("TextBox10").Text = 
   "My value"

oFmRt.GetControl("TextBox10").ToolTipText = 
   "My tooltip"

New Events

With the introduction of the Control architecture, several new events can now be trapped.

Sub Form_OnEnterTab(ByVal TabName)

Sub Form_OnLeaveTab(ByVal TabName)

Sub Form_OnEnterControl(ByVal ControlID)

Sub Form_OnLeaveControl(ByVal ControlID)

Sub Form_OnClick(ByVal ControlID)

Sub Form_OnChange(ByVal ControlID)

Sub Form_OnKeyPress(ByVal ControlID, 
   ByVal KeyAscii)

By combining these events with the powerful Control properties that can be set, you can now develop advanced scripts to simplify data input and help you to build advanced applications.

For example, you can now trigger a fragment of code to examine the characters entered into a field, as they are being entered (Form_OnKeyPress), or be alerted when the contents of a field are changed (Form_OnChange). The Form_OnClick event is used to determine when a button has been clicked.

Learning more about the FormRuntime object

The best way to learn more about the capabilities of scripting with the FormRuntime object is to start building scripts to take advantage of these new capabilities. We have developed a sample database which allows you to easily see the triggering of events and help you to understand how to integrate with your VBscript. If you would like a copy of this sample, please contact us (available to our Commence RM 3.0 customers on current Support or Maintenance contracts only).