Actions, Forms and Form Controls
Contents Hide
Actions allow us to add intelligence to a form. It specifies the responses of forms and form controls to the user input.
Projects developed in BrightBuilder are essentially event driven applications, where users interact with the forms, they can open or close a form, execute an expression by a click of a button or a stroke of the keyboard. Each of these user actions can be thought of as an event.
An event is a specific action that occurs on or with a certain control or form. Bright application designers can define a reaction to any of these events, allowing the application to react to the user actions. BrightBuilder can respond to a variety of events: mouse clicks, changes in data, forms opening or closing and many more.
By using form expressions or the built-in OpenForm object, custom responses can be added to a user action that occurs on form or form control. For example, the Product Details form can be opened when you click on the Product Details button on an Orders form.
BrightBuilder responds to an action by either triggering a form expression or by opening a form. When using the OpenForm object, an expression can be run before opening and closing the child form.
Assigning Actions
To link an expression to an action, click on the action property of the form or form control and select the expression from the drop down list.
The image above is an example of BrightBuilder button properties, whose Action - Click, Action - Got Focus or Action - Lost Focus properties may be used to define an expression to run, or a form to open.
To assign an expression, click on the drop down box to select an expression. The form's expressions, as well as the project's global expressions will be listed for selection.
To open a form, or edit an existing form open definition, click on the ellipsis
button to display the
OpenForm dialog.
Assign Action Dialog
Controls which have not been assigned any actions may have these definitions automatically created via the Assign Action dialog. This dialog may be accessed by double clicking any control, which will then create and open either an expression or open form definition to be set to the control, based on the user selection.
Double clicking a control which has had its default action assigned will open the assigned expression or Form Open dialog for editing.
The action this definition will be assigned to is based on the default action of each control:
Label: Action - Action Click
Edit: Action - Text Change
Button: Action - Click
Listview: Action - Double Click
ComboBox: Action - Selection change
RadioButton: Action - Click
CheckBox: Action Click
DateTime: DateTime Change
If
an expression is created by the Assign Action selection, it will
be named '<control name>_<action name>', for example
'listview1_DoubleClick'.
Open Form Dialog
The OpenForm dialog is a built-in function within BrightBuilder
that allows you to open a child form without any coding. You can access
the OpenForm dialog in any action event of any controls such as the
button action-click or a listview action-double-click by selecting
the ellipsis button,
as shown from the image below:
This image displays a button property list, the focused property is Action-Double Click which opens the "frmQuestionEdit" form.
The following image is a screen shot of the Open Form window for an Action-Click property of a button:
To open a form, simply select the form from the 'Open Form' drop down list. Once selected, the child forms parameters, variables and jump-to-record-primary keys will be populated, where necessary, and may be set to initialise the child form as follows:
The parameters are taken from the child form's Data Binding query, and/or any queries associated with the child form's controls such as list views and combo boxes. These parameters require a data source and must be populated, otherwise, will cause errors on project validation.
Variables are local data storage in a child form, defined under its Form Variables tab. All variables of the form will be displayed under this heading for population, which is optional.
The 'Jump To Record - Primary Keys' values allows the user to open and display a specific child form query record within the form's Data Binding result set, based on the query and primary key values entered. For example, if 50 records are returned by a form's data binding query, the primary key values of a particular record may be assigned under this heading, such that the child form will open with particular record's position navigated or 'jumped' to. Form navigation may be used to traverse the query to other records, if available. The above image shows the 'CASE_ID' primary key in the child form populated by the parent's form's selection within its listview - lvCases. Like the variables of the child form, this is also optionally populated.
Aside from specifying the child form parameters, variables and primary key values, expressions which run before or after the form is displayed may also be assigned via the OpenForm dialog. These are configured with the middle and right dropdowns in the dialog respectively, and are also known as 'Pre-Open' and 'Post-Close' expressions. These are very powerful tools to use when initialising values, obtaining results from the child form, or performing any other application specific logic necessary. They are optional to include, with any form or global expression able to be defined via drop down menus.
The two expressions set may be used specifically in the child-parent context as follows:
A Pre-Open expression may be used to verify the data passed to the child form, and even cancelling the opening via the form property CancelOpen if a certain condition was not met. For example, if the user did not select a record from the customer list in an order-entry application, the application should not allow the user to proceed with the order-entry. The CancelOpen property under Data Sources >Form > Properties in the DST can be used in this instance. Furthermore, Data Sources > Form > Child Properties in the DST may be used to initialise the child form at this step accordingly.
A Post-Close expression may be used to refresh the parent form based on child form changes after it closes. This may be based on the state of the database, global variables, or the child form's result, via the Form > Child Properties > Result data source. It may even be used to retrieve values of the child form's form variables on close, using the GetChildFormVariable() method within the assigned expression.
The GetChildFormVariable() method will only retrieve meaningful
values when called within a Post-Close expression.
In BrightBuilder 7.2.0 and higher, the Open Form dialog also contains a 'Web - Close Current Form Before Opening Child Form' option. When ticked, BrightWeb will close the form's parent form and thus any path back to previous forms after the specified form opens. This method is designed for web mode, whereby free access to any form within the project is implemented via features such as global menus. For more information, please refer to the BrightWeb > Commands and Navigation section of Bright Web.
Another way to open a child form is by using expressions and linking it to an action event as will be discussed in the following section. Please refer to the Objects Definition Reference Manual > Form section for more detail regarding the methods to use in opening a child form using expressions.