Previous

Next

User Defined Messages

A user interface will be composed of any combination of RTPEG-32 windows, buttons, strings, etc., along with custom objects. At some point you will want to perform an action based on the user selecting a button, or typing into a string field. You are notified of this user input via messages sent from the RTPEG-32 control to the parent window. When you create a control object, you tell the object what message to send back to the parent window when the object is modified by the user by defining the object ID value. Once you have constructed and displayed the control, you simply wait for the arrival of the message which indicates the control has been modified.

As an example, suppose the interface has two separate but related windows visible on the screen, Window A and Window B. Window A displays several data values, in alphanumeric format, that can be modified by the user. Window B displays these same data values as a line chart. When the user modifies a data value in Window A, we want Window B to update the line chart to reflect the new value. One way of accomplishing this is to define a new message which contains the altered data value. When Window A is notified by one of its child controls that a value has been changed, it builds an instance of the newly defined message, places the data value into the message, and sends the message to Window B. When Window B receives the message, it realizes that the line chart should be redrawn using the new data value.

When defining custom messages, using enumerations is recommended with the first enumeration equal to FIRST_USER_MESSAGE. For example, the following class declaration includes the typical method of defining custom messages:

Class MyWindow::public PegWindow 
{ 
   public: 
      enum ThisWindowMessages // my user defined messages 
      { 
         TURN_BLUE = FIRST_USER_MESSAGE, 
         TURN_GREEN, 
         TURN_INVISIBLE 
      }; 
}

The above example illustrates a common way to define your own messages. We have implied in this example that you can re-use message values over and over again since the message number enumeration is a member of the class, rather than a global enumeration. This is in fact the case. As long as the object receiving the message can clearly identify what the message means you don't have to worry about reusing the same message numbers at various points in your application.

There are three ways to send a message from one window to another. First, you can either call the destination window's message handling function directly, passing your message as a parameter. Second, you can load the message's pTarget field with the address of the window (or any object) that should receive the message and push the message into PegMessageQueue. Finally, you can load the message's pTarget field with NULL, the message iData member with the ID of the target window, and push the message into PegMessageQueue. The second or third methods are generally preferred, because they adhere to the encapsulation philosophy.

With pTarget pointing to an application object, it must be ensured that the object is not deleted before the message arrives. When a user defined message contains a non-NULL pTarget value, there is no verification that the pTarget field of the message is a valid object pointer. For this reason, in some situations it is better to use NULL pTarget values, and route messages using object IDs. If PegPresentationManager is unable to locate an object with the indicated ID, the message is simply discarded.

There are also differences between these methods in terms of the order in which things are done. When a message is sent, the sending object immediately continues processing, and the target window will receive and process the new message after the sending window returns from message processing. If the receiving window's message handling function is called directly, it will immediately receive and process the message, in effect pre-empting the current execution thread. While these differences are generally inconsequential for user defined messages, they can be very important for RTPEG-32 system messages.

Class PegMessageQueue

System Messages

Signals