Defining user events

In PocketBuilder, you can define both mapped and unmapped user events for windows, user objects, controls, menus, and the Application object. The access level for events is always public.

When you add a new event, a Prototype window displays above the script area in the Script view. Most of the fields in the Prototype window are the same as when you define a user-defined function. They are in the same order as the event’s signature: access level, return type, name, required parameters, and any exception objects for its THROWS clause. For each parameter, you define how it is passed, its datatype, and the parameter name.

For information about filling in these fields, see “Defining user-defined functions”.

Figure 8-2: Prototype window for a user-defined event

Shown is the Script View for the window w_notepad with the prototype definition for the U E underscore Replace underscore Text event. In the first drop down at top left is the selected window w _ notepad. Partially visible in the second list box is the user defined event. Below this is the Prototype window with drop down lists labeled Access and Return Type, and a text field for the Event Name. Other drop down lists display selections for Pass By and Argument Type for each argument listed in Argument Name text boxes. At bottom is a text box labeled Throws:, a check box labeled External, and a drop down list for Event ID.

The Prototype window for user-defined events has an additional field that you use if you want to map the user event to an event ID.

External check box When you check the External check box, PocketBuilder sets the IsExternalEvent property of the ScriptDefinition object associated with the event to “true”. This has no effect on your application in this release. The feature might be used in a future release.

Mapped user events

When a system message occurs, PocketBuilder triggers any user event that has been mapped to the message and passes the appropriate values to the event script as arguments. When you define a user event and map it to an event ID, you must use the return value and arguments that are associated with the event ID.

To define a mapped user event:

Open the object for which you want to define a user event.
If you want to define a user event for a control on a window or visual user object, double-click the control to select it.
Select Insert>Event from the menu bar or select Add from the Event List view pop-up menu.

The Prototype window opens in the Script view. If you display the Script view’s title bar, you see (Untitled) because you have not yet named the event.
Name the event and tab to the next field.

To recognize a user event easily, consider prefacing the name with an easily recognizable prefix such as ue_. Event names can have up to 40 characters. For valid characters, see “identifier names” in the online Help.

When you tab to the next field, the user event is added to the Event List view. It is saved as part of the object whenever you save the object.
Select an ID from the drop-down list box at the bottom of the Prototype window.

Unmapped user events

Unmapped user events are associated with PocketBuilder activities and do not have event IDs. When you define an unmapped user event, you specify the arguments and return datatype; only your application scripts can trigger the user event. For example, if you create an event called ue_update that updates a database, you might trigger or post the event in the Clicked event of an Update command button.

To define an unmapped user event:

Open the object for which you want to define a user event.
If you want to define a user event for a control on a window or visual user object, double-click the control to select it.
Select Insert>Event from the menu bar or select Add from the pop-up menu for the Event List view.

The Prototype window opens in the Script view. If you display the Script view’s title bar, you see (Untitled) because you have not yet named the event.
Select a return type and tab to the next field.

Defining return types for events is similar to defining them for functions. See “Defining a return type”.
Name the event and tab to the next field.

To recognize a user event easily, consider prefacing the name with an easily recognizable prefix such as ue_. Event names can have up to 40 characters. For valid characters, see “identifier names” in the online Help.

When you tab to the next field, the user event is added to the Event List view. It is saved as part of the object whenever you save the object.
If the event takes arguments, define arguments for the event.

Defining arguments for events is similar to defining them for functions. See “Defining arguments” and “Adding, inserting, and deleting arguments”.
Optionally enter the name of exceptions that can be thrown by the event.

To open a user event for editing:

In the Event List view, double-click the event’s name

To delete a user event:

In the Event List view, select the user event’s name and select Delete from the Edit menu or the pop-up menu