Introduction to PowerBuilder

Triggering an Event

Events that are mapped to regular event ids are triggered automatically. For example, clicking on a CommandButton automatically executes the script written for its "Clicked" event ( pbm_bnclicked event id for the CommandButton ). Sometimes, you may want to trigger the event programmatically. For example, you may want to trigger the 'Sort' event in the DataWindow control, if the user selects the 'ue_sort' option from the popup menu of a DataWindow. To trigger an event, you need to use the TriggerEvent(), and the syntax is:

ObjectName.TriggerEvent( Event, { WordParm }, { LongParm } )

"WordParm" and "LongParm" arguments are optional. All pre-defined events are defined as enumerated data types under "trigevent". For example, for "close" event, there's an enumerated data type "close!", for "activate" event, it's "activate!" and so on. To trigger pre-defined events, you need to use enumerated data types. The following examples trigger "close" and "activate" events for the "w_script_practice" window.

Int li_retstat
li_retstat = w_script_practice.TriggerEvent( Close! )
If li_retstat <> 1 Then
   //Error handling ...
End If

li_retstat = w_script_practice.TriggerEvent( Activate! )
If li_retstat <> 1 Then
   //Error handling ...
End If

If triggering an user-defined event, use the event name within quotations. The following example triggers "ue_save" event in "w_script_practice" window.

Int li_retstat
w_script_practice.TriggerEvent( "ue_save" )
If li_retstat <> 1 Then
   //Error handling ...
End If

If the specified event's script executes successfully, TriggerEvent() returns 1. If no script exists or the specified event is invalid ( may be you forgot defining that event or misspelled the event name ), -1 will be returned. We always recommend checking of return values.

TriggerEvent() function executes synchronously, i.e., the next command after this command will not be executed until this command is executed completely.

As shown in the above syntax, you can also send parameters to the event in the TriggerEvent(). When you send parameters, they are stored in the Message object. Message Object is explained in detail in the "Inter Object Communication" section. For the time being just note that, Message object is a global object and is available by default in all PowerBuilder applications. In simple terms, the main purpose of this object is to store information which are accessed from other objects. Parameters passed to the event in the TriggerEvent() are available in Message.StringParm and Message.LongParm members.

There are limitations in the number of parameters you can pass for an event through this function. That being two. Another disadvantage with this function is that, the return value of the event can't be trapped. The return value of this function is the success/failure of the function call itself, and not the return code returned in the event script.

With version 5.0, another syntax is available for executing events and functions. PowerSoft says that the new syntax is only an enhancement, and not a replacement for the old syntax, but I am afraid it is not so. Once you start using the new syntax, there are chances that you will not go back to the old syntax again. The much talked about syntax is as follows:

{ObjectName.}{Type} {CallType} {When} &
      Function/Event Name ({ ArgumentList})

The same syntax allows you to execute either an event or a function, just specify keyword Function or Event in place of 'Type'. If you do not specify anything, Function will be taken by default. CallType indicates whether it is a static or a dynamic event, which we will explain in a moment. When indicates whether you want to trigger or post the event/function. Similar to calling a function, you always need to specify parenthesis after the event or function name irrespective of the parameters. The following script triggers "ue_save" event at the window.

/* Either lines trigger ' ue_save'
   event at the window. */
Parent.Event Trigger ue_save()
Parent.Event ue_save()

The return value for the TriggerEvent() is always an integer. However, the return value for this new syntax depends on the return value type declared at the called event/function. If the event is returning a string value, you need to assign the return value to a string variable. Even though it is good practice to check the return value, assigning return values is not mandatory.

String ls_status
ls_status = Parent.EVENT STATIC TRIGGER ue_SendToMainFrame()
ls_status = Parent.EVENT TRIGGER ue_SendToMainFrame()
Parent.EVENT STATIC TRIGGER ue_SendToMainFrame()
Parent.EVENT TRIGGER ue_SendToMainFrame()

All the above statements are correct. The only limitation on return value being, that the return value expression shouldn't return an array. CallType is "static" by default. That means, compiler checks the presence of the calling event or function and its return value type at the compilation time. If the event or function doesn't exist, or the assigned returned value type is incorrect, error will be generated.

Calling ancestor events is explained in "Inheriting a Window" section.

Home	Previous Lesson: Events and Return Values Next Lesson: Triggering Events Dynamically