Description
Triggers an event associated with the specified object, which executes the script for that event immediately.
Applies to
Any object
Syntax
objectname.TriggerEvent ( event {, word, long } )
|
Argument |
Description |
|---|---|
|
objectname |
The name of any PowerBuilder object or control that has events associated with it. |
|
event |
A value of the TrigEvent enumerated datatype that identifies a PowerBuilder event (for example, Clicked!, Modified!, or DoubleClicked!) or a string whose value is the name of an event. The event must be a valid event for objectname and a script must exist for the event in objectname. |
|
word (optional) |
A long value to be stored in the WordParm property of the system's Message object. If you want to specify a value for long, but not word, enter 0. (For cross-platform compatibility, WordParm and LongParm are both longs.) |
|
long (optional) |
A long value or a string that you want to store in the LongParm property of the system's Message object. When you specify a string, a pointer to the string is stored in the LongParm property, which you can access with the String function (see Usage). |
Return value
Integer.
Returns 1 if it is successful and the event script runs and -1 if the event is not a valid event for objectname, or no script exists for the event in objectname. If any argument's value is null, TriggerEvent returns null.
Usage
If you specify the name of an event instead of a value of the TrigEvent enumerated datatype, enclose the name in double quotation marks.
Check return code
It is a good idea to check the return code to determine whether TriggerEvent succeeded and, based on the result, perform the appropriate processing.
You can pass information to the event script with the word and long arguments. The information is stored in the Message object. In your script, you can reference the WordParm and LongParm fields of the Message object to access the information.
If you have specified a string for long, you can access it in the triggered event by using the String function with the keyword "address" as the format parameter. Your event script might begin as follows:
string PassedString PassedString = String(Message.LongParm, "address")
Caution
Do not use this syntax unless you are certain the long argument contains a valid string value.
For more information about events and when to use PostEvent and TriggerEvent, see PostEvent.
To trigger system events that are not PowerBuilder-defined events, use Post or Send, instead of PostEvent and TriggerEvent. Although Send can send messages that trigger PowerBuilder events, as shown below, you have to know the codes for a particular message. It is easier to use the PowerBuilder functions that trigger the desired events.
Equivalent syntax
Both of the following statements click the CheckBox cb_OK. The following call to the Send function:
Send(Handle(Parent), 273, 0, Long(Handle(cb_OK), 0))
is equivalent to:
cb_OK.TriggerEvent(Clicked!)
Examples
This statement executes the script for the Clicked event in the CommandButton cb_OK immediately:
cb_OK.TriggerEvent(Clicked!)
This statement executes the script for the user-defined event cb_exit_request in the parent window:
Parent.TriggerEvent("cb_exit_request")This statement executes the script for the Clicked event in the menu selection m_File on the menu m_Appl:
m_Appl.m_File.TriggerEvent(Clicked!)
See also
