Sending Windows messages
To send Windows messages to a window that you created in PowerBuilder or to an external window (such as a window you created using an external function), use the Post or Send function. To trigger a PowerBuilder event, use the EVENT syntax or the TriggerEvent or PostEvent function.
Using Post and Send
You usually use the Post and Send functions to trigger Windows events that are not PowerBuilder-defined events. You can include these functions in a script for the window in which the event will be triggered or in any script in the application.
Post is asynchronous: the message is posted to the message queue for the window or control. Send is synchronous: the window or control receives the message immediately.
As of PowerBuilder 6.0, all events posted by PowerBuilder are processed by a separate queue from the Windows system queue. PowerBuilder posted messages are processed before Windows posted messages.
Obtaining the window's handle To obtain the handle of the window, use the Handle function. To combine two integers to form the long value of the message, use the Long function. Handle and Long are utility functions, which are discussed later in this chapter.
Triggering PowerBuilder events
To trigger a PowerBuilder event, you can use:
Technique Description
TriggerEvent function A synchronous function that triggers the event immediately in the window or control
PostEvent function An asynchronous function: the event is posted to the event queue for the window or control
Event call syntax A method of calling events directly for a control using dot notation
All three methods bypass the messaging queue and are easier to code than the Send and Post functions.
Example All three statements shown below click the CommandButton cb_OK and are in scripts for the window that contains cb_OK.
The Send function uses the Handle utility function to obtain the handle of the window that contains cb_OK, then uses the Long function to combine the handle of cb_OK with 0 (BN_CLICK) to form a long that identifies the object and the event:
The TriggerEvent function identifies the object in which the event will be triggered and then uses the enumerated data type Clicked! to specify the clicked event.
The dot notation uses the EVENT keyword to trigger the Clicked event. TRIGGER is the default when you call an event. If you were posting the clicked event, you would use the POST keyword:
The Message object
The Message object is a predefined PowerBuilder global object (like the default Transaction object SQLCA and the Error object) that is used in scripts to process Microsoft Windows events that are not PowerBuilder-defined events.
When a Microsoft Windows event occurs that is not a PowerBuilder-defined event, PowerBuilder populates the Message object with information about the event.
Other uses of the Message object
The Message object is also used:
To communicate parameters between windows when you open and close them
For more information, see the descriptions of OpenWithParm, OpenSheetWithParm, and CloseWithReturn in the PowerScript Reference .
To pass information to an event if optional parameters were used in TriggerEvent or PostEvent
For more information, see the PowerScript Reference .
Customizing the Message object
You can customize the global Message object used in your application by defining a standard class user object inherited from the built-in Message object. In the user object, you can add additional properties (instance variables) and functions. You then populate the user-defined properties and call the functions as needed in your application.
For more information about defining standard class user objects, see the PowerBuilder User's Guide .
Message object properties
The first four properties of the Message object correspond to the first four properties of the Microsoft Windows message structure:
Property Data type Use
Handle Integer The handle of the window or control
Number Integer The number that identifies the event (this number comes from Windows)
WordParm UnsignedInt The word parameter for the event (this parameter comes from Windows). The parameter's value and meaning are determined by the event
LongParm Long The long parameter for the event (this number comes from Windows). The parameter's value and meaning are determined by the event
DoubleParm Double A numeric or numeric variable
StringParm String A string or string variable
PowerObjectParm PowerObject Any PowerBuilder object type including structures
Processed Boolean A boolean value set in the script for the user-defined event:
True--The script processed the event (do not call the default window Proc (DefWindowProc) after the event has been processed)
False--(Default) Call DefWindowProc after the event has been processed
ReturnValue Long The value you want returned to Windows when Message.Processed is TRUE. When Message.Processed is FALSE, this attribute is ignored
Use the values in the Message object in the event script that caused the Message object to be populated. For example, suppose the FileExists event contains the following script. OpenWithParm displays a response window that asks the user if it is OK to overwrite the file. The return value from FileExists determines whether the file is saved:
OpenWithParm( w_question, & "The specified file already exists. " + & "Do you want to overwrite it?" ) IF Message.StringParm = "Yes" THEN RETURN 0 // File is saved ELSE RETURN -1 // Saving is canceled END IF
For information on Microsoft message numbers and parameters, see the Microsoft Software Developer's Kit (SDK) documentation.
Triggers an event associated with the specified object, which executes the script for that event immediately.
Controls
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 data type 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 data type, 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:
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: