Description
Adds an event to the end of the event queue of an object.
Applies to
Any object, except the application object
Syntax
objectname.PostEvent ( event {, word, long } )
|
Argument |
Description |
|---|---|
|
objectname |
The name of any PowerBuilder object or control (except an application) 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
Boolean. Returns true if it is successful and false if the event is not a valid event for objectnameobjectname. Also returns true if no script exists for the event in objectname. If any argument's value is null, PostEvent returns null.
Usage
You cannot post events to the event queue for an application object. Use TriggerEvent instead.
You cannot post or trigger events for objects that do not have events, such as drawing objects. You cannot post or trigger events in a batch application that has no user interface because the application has no event queue.
After you call PostEvent, check the return code to determine whether PostEvent succeeded.
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. Note that the Message object is saved and restored just before the posted event script runs so that the information you passed is available even if other code has used the Message object too.
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. (Note that PowerBuilder has stored the string at an arbitrary memory location and you are relying on nothing else having altered the pointer or the stored string.) Your event script might begin as follows:
string PassedString PassedString = String(Message.LongParm, "address")
TriggerEvent and PostEvent are useful for preventing duplication of code. If two controls perform the same task, you can use PostEvent in one control's event script to execute the other's script, instead of repeating the code in two places. For example, if both a button and a menu delete data, the button's Clicked script can perform the deletion and the menu's Clicked event script can post an event that runs the button's Clicked event script.
Choosing PostEvent or TriggerEvent
Both PostEvent and TriggerEvent cause event scripts to be executed. PostEvent is asynchronous; it adds the event to the end of an object's event queue. TriggerEvent is synchronous; the event is triggered immediately.
Use PostEvent when you want the current event script to complete before the posted event script runs. TriggerEvent interrupts the current script to run the triggered event's script. Use it when you need to interrupt a process, such as canceling printing.
If the function is the last line in an event script and there are no other events pending, PostEvent and TriggerEvent have the same effect.
Events and messages in Windows
Both PostEvent and TriggerEvent cause a script associated with an event to be executed. However, these functions do not send the actual event message. This is important when you are choosing the target object and event. The following background information explains this concept.
Many PowerBuilder functions send Windows messages, which in turn trigger events and run scripts. For example, the Close function sends a Windows close message (WM_CLOSE). PowerBuilder maps the message to its internal close message (PBM_CLOSE), then runs the Close event's script and closes the window.
If you use TriggerEvent or PostEvent with Close! as the argument, PowerBuilder runs the Close event's script but it does not close the window because it did not receive the close message. Therefore, the choice of which event to trigger is important. If you trigger the Clicked! event for a button whose script calls the Close function, PowerBuilder runs the Close event's script and closes the window.
Use Post or Send when you want to trigger system events that are not PowerBuilder-defined events.
Examples
This statement adds the Clicked event to the event queue for CommandButton cb_OK. The event script will be executed after any other pending event scripts are run:
cb_OK.PostEvent(Clicked!)
This statement adds the user-defined event cb_exit_request to the event queue in the parent window:
Parent.PostEvent("cb_exit_request")This example posts an event for cb_exit_request with an argument and then retrieves that value from the Message object in the event's script.
The first part of the example is code for a button in a window. It adds the user-defined event cb_exit_request to the event queue in the parent window. The value 455 is stored in the Message object for the use of the event's script:
Parent.PostEvent("cb_exit_request", 455, 0)The second part of the example is the beginning of the cb_exit_request event script, which assigns the value passed in the Message object to a local variable. The script can use the value in whatever way is appropriate to the situation:
integer numarg numarg = Message.WordParm
See also
