Object Events

Many events are triggered by Alpha Five objects, such as buttons, fields, and forms. The object events are generally triggered in response to the cursors movements into and out of the object (i.e., the changing of focus from one place to another).

Events for Button Objects

A button object can have scripts attached to the following events:

Scripts are generally attached to a buttons OnPush event.

The following sequence of events were generated when an operator moved the cursor to a button, clicked it, and moved the cursor off the button.

Sequence of Events for Buttons

Events for Type-In Objects

The following events are triggered by all forms of the type-in object: Type-In, List boxes, Drop-Down lists, Radio buttons, Check boxes, Two-state, and Multi-state buttons:

For type-in fields, the OnChange event fires when the control looses focus. For radio button, two-state button, multi-state button, and list box fields, the OnChange event fires as soon as the fields value changes.

For example, assume that you have a form with an Account_Number field. If the user makes a change to the value in this field, you want to be sure that this change was made intentionally, and not by mistake. If the user confirms that the change was intentional, the changed value is retained. Otherwise, the initial value is restored. To do this, scripts must be attached to the fields OnArrive and OnChange events. A flag variable is used to prevent the OnChange script from playing back a second time when the initial value is restored.

The following script is attached to the Account_Number fields OnArrive event:

The script for the OnChange event is:

The following example shows how the forms tab order can be dynamically controlled. In this example, the script is attached to the OnDepart event for the Same_shipping field:

The following sequence of events were generated when an operator placed the cursor in a type-in field, changed its contents, and moved the cursor to a different field.

Sequence of Events for Type-In Fields

The following sequence of events were generated when an operator placed the cursor on a check box, clicked it, and moved the cursor off it.

Sequence of Events for Check Boxes

The following sequence of events were generated when an operator moved the cursor to a radio button, selected it, clicked one of the buttons, and moved the cursor off it.

Sequence of Events for Radio Buttons

Events for Image Reference Fields

The following events are triggered by image reference fields:

Events for Browse Objects

The browse object triggers the following events:

Note : Placing a browse on a form creates the browse object. There are no events for stand alone browse windows, only browse objects on forms.

In the following example, assume you have a table called Customers. You have a form for this table that shows a browse view of your records. When you double click on a row in the browse, a form called Customer_dlg is opened as a dialog allowing you to edit the record.

In the following example, a script attached to the CanDepart event causes a calculated field in the parent table to update when focus leaves the embedded browse. Consider the sample Invoice application that ships with Alpha Five. Say you wanted to have a summary field in the invoice_header table that summarized the extended totals in the child invoice_items table. Assume that you had a field in the invoice_header table called summary (numeric 12,2), and had defined the following calculated field rule for this field:

While this expression is correct, you would find that the field was not displaying the correct value when you entered new line items into the embedded browse. The reason for this is that calculated fields only evaluate when a record is in change or enter mode, and when you are entering line item records, the invoice_header table is in view mode, not change or enter.

By putting this script on the embedded forms CanDepart event, you can force the calculated fields in the invoice_header table to recalculate:

The following sequence of events were generated when an operator moved the cursor to a embedded browse, selected a row, changed one of the entries, and moved the cursor off the embedded browse.

Sequence of Events for Embedded Browses

Events for Forms

The following events are triggered when you display, leave, or work with a form:

Note : The following example is obsolete in V5 because you can now select Modal/Modeless data entry as a property of each Form or Browse layout. The example is nevertheless still interesting since it describes a use for the OnFetch event.

The following example shows how the OnFetch event can be used to turn off Alpha Fives modeless data entry. Modeless data entry allows the user to just start typing a new value in a field without having to explicitly put the record in change or enter mode. In some applications it may be desirable to turn off modeless data entry, thus requiring the user to press a button before the record can be edited.

Attach this script to the forms OnFetch event:

Note : While the above example should work in most cases, in some cases, it would be possible to get a Maximum Stack Depth Exceeded error message when scrolling through the records very quickly. This is because the OnFetch event is fired a second time before the current instance has finished executing. The current instance is put onto a stack until it can be completed. The stack has a limited capacity. If enough uncompleted instances of the script are pushed onto the stack, the stack will eventually overflow. This situation can be corrected by preventing a second instance of the script from starting until the first instance is complete. The following code shows how to do this:

When the user wants to edit a record, he presses a button with this script attached to the buttons OnPush event:

Notice that the script attached to the OnFetch event uses the this alias to refer to the form, while the script attached to the button uses the alias parent to refer to the form. This is because the button is a child of the form, whereas the OnFetch event occurs at the level of the form. (Both scripts could also use parentform to refer to the form).

AskSaveChange and AskSaveEnter Events

The AskSaveChange and AskSaveEnter events fire when the user attempts to close a form before committing changes to a new or edited record. They allow the user to custom design the dialog that Alpha Five displays asking the user to confirm the action.

RESULT_CODE Variable

RESULT_CODE is a system variable that is used in conjunction with the AskSaveChange and AskSaveEnter events. For example, if the result_code variable is set to UI_YES_SELECTED, then the record is saved, and Alpha Five does not present its dialog asking the user for confirmation. If you do not define a script for either the AskSaveChange, or AskSaveEnter event, or do not set the numeric result_code, then the default Alpha Five dialog appears.

Examples

Change the wording on the dialog to something specific to the application:

Change the meaning of Yes from save to abort:

Automatically save the record (i.e. do not ask for confirmation)

Events for Tab Object on Forms

The following events are triggered when the user changes the active page on a tab control on a form:

You can use the CanTabChange event to prevent the user from moving off the current tab page.

For example, you might have created a dialog form with a tab control on it. You want the user to complete filling in all of the controls on each page of the tab control before advancing to the next tab page. You could attach the following code to the tab controls CanTabChange event:

Events for Reports

The following events are triggered when the user a user does a print or print preview of a report:

To specify scripts for the OnPrintInit and OnPrintExit events, select Report > Actions. This opens the Script Editor. In the Container drop down box, select the report name. Then select the name of the event you wish to define in the Script drop down box.

To specify a script for the OnRecord event, open the script editor as Defined above, select Detail in the Container drop down box.

You can use the OnPrintInit event to prompt the user for variables by opening a form as a dialog, or by using a UI_GET_TEXT() function, or by running an Xdialog box. These variables might then be used in the report's filter and order expression (defined in the report's Detail properties). IMPORTANT: The variables that you prompt for in the OnPrintInit event must be DIMmed as "shared" or "global". For example, the following Xdialog box prompts for the state. The report filter then has the filter expression: "state = var->whatstate".

You can use the OnRecord event to update records after they have printed. For example, in an invoicing application, you might have a Status field in the invoice_header table. After you print out invoices, you might want to update this field to say Printed. Here is how you could do this:

Events for User Defined Controls

The Form Editor in Alpha Five has a control called User Defined Control that allows an Xbasic programmer to make a custom control.

A user puts a User Defined Control (UDC) on a form using the UDC object on the form editors toolbox. You select the tool and draw the object on the form. Once you have defined the UDC on the form, you can then specify the Xbasic code for its various events.

A UDC allows the user to write custom controls entirely within Xbasic using the Windows API (or other external libraries) to draw the contents, handle key and mouse events, and react to timer events. See User Defined Controls for more information.

The A_USER.HWND variable is used for window control and is always defined.

Events and Associated Variables

See Also

CANCEL(), Field Rule Field Events, Field Rule Record Events, Canceling Events, Attaching Scripts to Events