Previous

Next

Signals

Messages are used to issue commands or send other information between objects that are part of the user interface. The previous section explained how a user defined messages notifies a parent window that a child control has been modified. This usage is so common, in fact, that RTPEG-32 has defined a simplified method for defining these messages and a corresponding syntax for receiving them. This method is called Signalling, and the messages sent and received via Signalling are called Signals. Signals are designed to simplify programming by reducing the complexity associated with windows and dialogs containing a large number of child controls. Signals are also defined to solve some common problems associated with other less friendly messaging systems:

• Very often a single window, such as a modal dialog window, will have a large number of child objects. It can be very difficult to remember all of the unique messages associated with each of these objects.
• Complex control types, such as PegString or PegComboBox, can be modified in several different ways. The result of this is that either multiple message types must be sent by the control to the parent window, or the receiver of a single notification message would have to further interrogate the control to determine exactly why it sent a message.
• Although a control may define several different types of modification, you may not be interested in every type of control modification that can occur. In that case, you do not want the control to waste processing time by generating messages you are not interested in.
• To facilitate the implementation of a RAD window prototyping tool such as WindowBuilder, a consistent, simple, and robust message definition method must be in place.

Basically, signalling is nothing more than allowing an object to automatically generate and use multiple user defined message types based on a single object ID value. Every object using signals must have an object 'ID' value, which can and should be an enumerated ID name.

RTPEG-32 defines many different signals that can be monitored for each control. Whenever the control is modified by the user, the control checks to see if it is configured to notify its parent of the modification. If so, the control generates a unique message number based on the control ID and the type of notification. The message source pointer is loaded to point to the control, and the message is then sent to the parent window or dialog.

To receive a signal, RTPEG-32 defines the SIGNAL macro, which is used in the parent window message processing function. The parameters to the SIGNAL macro are the object ID and the notification message number. The SIGNAL macro is a shorthand method for determining the exact message number sent by a control with a given ID and corresponding to one of the 32 possible notification types.

The example below illustrates the use of signals in the definition and run-time processing of a typical dialog window. Since we have not yet discussed all of the information you need to know to fully understand this example, we don't want you to be concerned with the details (in fact, a lot of the details have been left out). Instead, the syntax for defining the control object IDs for each of the dialog controls and the message processing statements corresponding to each control is shown.

A few object Ids are reserved to facilitate the proper operation of modal dialog and modal message windows. The reserved object ID values occupy the upper range of the possible Id values. Custom Id values should start at 1.

Class MyDialog : public PegDialogWindow 
{ 
   private: 
      enum MyChildControls 
      { 
         USER_NAME = 1, // string control ID 
         HAS_EMAIL,     // check box ID 
         EMAIL_ADDRESS, // email address string ID 
      }; 
}; 

PEGINT MyDialog::Message(const PegMessage &Mesg) 
{ 
   switch (Mesg.wType) 
   { 
      case SIGNAL(USER_NAME, PSF_TEXT_EDITDONE): 
         // add code for user name modification here: 
         break; 
      case SIGNAL(USER_NAME, PSF_FOCUS_RECEIVED): 
         // add code here to bring up help for user name: 
         break; 
      case SIGNAL(EMAIL_ADDRESS, PSF_TEXT_EDITDONE): 
         // add code for email address change here: 
         break; 
      case SIGNAL(HAS_EMAIL, PSF_CHECK_ON): 
         // add code for checkbox turned on: 
         break; 
      case SIGNAL(HAS_EMAIL, PSF_CHECK_OFF): 
         // add code for checkbox turned off: 
         break; 
    default: 
        return PegDialogWindow::Message(Mesg); 
   } 
   return 0; 
}

Class PegMessageQueue

User Defined Messages