About events
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 |
|
System events without an ID |
PowerBuilder messages or a call in your |
|
User-defined events with an ID |
User actions or other system messages or a call in |
|
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.
Event IDs
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.
Arguments
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.
|
1 |
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.
Return values
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:
|
1 |
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.
Ancestor event script return values
Sometimes you want to perform some processing in an event in a
descendant 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.
User-defined events
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.
For more information
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 section called “Working with User Events” in Users Guide.