In PowerBuilder, there are several types of events.
Type |
Occurs in response to |
|---|---|
System events with an ID |
User actions or other system messages or a call in your scripts |
System events without an ID |
PowerBuilder messages or a call in your scripts |
User-defined events with an ID |
User actions or other system messages or a call in your scripts |
User-defined events without an ID |
A call in your scripts |
The following information about event IDs, arguments, and return values applies to all types of events.
An event ID connects an event to a system message. Events that can be triggered by user actions or other system activity have event IDs. In PowerBuilder’s objects, PowerBuilder defines events for commonly used event IDs. These events are documented in this chapter. You can define your own events for other system messages using the event IDs listed in the Event Declaration dialog box.
Events without IDs Some system events, such as the application object’s Open event, do not have an event ID. They are associated with PowerBuilder activity, not system activity. PowerBuilder triggers them itself when appropriate.
System-triggered events Each system event has its own list of zero or more arguments. When PowerBuilder triggers the event in response to a system message, it supplies values for the arguments, which become available in the event script.
Events you trigger If you trigger a system event in another event script, you specify the expected arguments. For example, in the Clicked event for a window, you can trigger the DoubleClicked event with this statement, passing its flags, xpos, and ypos arguments on to the DoubleClicked event.
w_main.EVENT DoubleClicked(flags, xpos, ypos)
Because DoubleClicked is a system event, the argument list is fixed—you cannot supply additional arguments of your own.
Calling events without specifying their arguments
If you use the CALL statement, you can
trigger a system event without specifying its arguments. However, CALL is
obsolete and you should not use it in new applications except as
described in CALL.
Where does the return value go? Most events have a return value. When the event is triggered by the system, the return value is returned to the system.
When your script triggers a user-defined or system event, you can capture the return value in an assignment statement:
li_rtn = w_main.EVENT process_info(mydata)
When you post an event, the return value is lost because the calling script is no longer running when the posted script is actually run. The compiler does not allow a posted event in an assignment statement.
Return codes System events with return values have a default return code of 0, which means, “take no special action and continue processing.” Some events have additional codes that you can return to change the processing that happens after the event. For example, a return code might allow you to suppress an error message or prevent a change from taking place.
A RETURN statement is not required in an event script, but for most events it is good practice to include one. For events with return values, if you do not have a RETURN statement, the event returns 0.
Some system events have no return value. For these events, the compiler does not allow a RETURN statement.
Sometimes you want to perform some processing in an event in a descendent object, but that processing depends on the return value of the ancestor event script. You can use a local variable called AncestorReturnValue that is automatically declared and assigned the value of the ancestor event.
For more information about AncestorReturnValue, see “Calling functions and events in an object’s ancestor”.
With an ID When you declare a user-defined event that will be triggered by a system message, you select an event ID from the list of IDs. The pbm (PowerBuilder Message) codes listed in the Event dialog box map to system messages.
The return value and arguments associated with the event ID become part of your event declaration. You cannot modify them.
When the corresponding system message occurs, PowerBuilder triggers the event and passes values for the arguments to the event script.
Without an ID When you declare a user event that will not be associated with a system message, you do not select an event ID for the event.
You can specify your own arguments and return datatype in the Event Declaration dialog box.
The event will never be triggered by user actions or system activity. You trigger the event yourself in your application’s scripts.
If you want to trigger events, including system events, see “Syntax for calling PowerBuilder functions and events” for information on the calling syntax.
To learn more about user-defined events, see the PowerBuilder Users Guide.
