TriggerEvent PowerScript function

Description

Triggers an event associated with the specified object, which
executes the script for that event immediately.

Controls

Any object

Syntax

<span>objectname</span>.<span>TriggerEvent</span> ( <span>event</span> {, <span>word</span>, <span>long</span> } )

1	<span>objectname</span>.<span>TriggerEvent</span> ( <span>event</span> {, <span>word</span>, <span>long</span> } )

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 Values

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

1	string PassedString

PassedString = String(Message.LongParm, "address")

1	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))

1	Send(Handle(Parent), 273, 0, Long(Handle(cb_OK), 0))

is equivalent to:

cb_OK.<span>TriggerEvent</span>(Clicked!)

1	cb_OK.<span>TriggerEvent</span>(Clicked!)

Examples

This statement executes the script for the Clicked
event in the CommandButton cb_OK immediately:

cb_OK.<span>TriggerEvent</span>(Clicked!)

1	cb_OK.<span>TriggerEvent</span>(Clicked!)

This statement executes the script for the user-defined
event cb_exit_request in the parent window:

Parent.<span>TriggerEvent</span>("cb_exit_request")

1	Parent.<span>TriggerEvent</span>("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<span>.TriggerEvent</span>(Clicked!)

1	m_Appl.m_File<span>.TriggerEvent</span>(Clicked!)

TriggerEvent – PB Docs 150