Previous

Next

Class PegMessageQueue

PegMessageQueue is a FIFO message queue with functions for sending and receiving PegMessage formatted messages. PegMessageQueue also performs timer maintenance and miscellaneous housekeeping duties.

Function PegInitialize created the application's message queue.

class PegMessageQueue 
{ 
   public: 
      void Push(PegMessage * Msg); 
      void Push(PegMessage &In); 
      void Pop(PegMessage * Msg); 
      void Fold(PegMessage * Msg); 
      void Purge(PegThing * pTarget, PEGUINT wType = 0); 
      int  Messages(void); 
      void SetTimer(PegThing * Who, PEGUINT wId, LONG lCount, LONG lReset); 
      void KillTimer(PegThing * Who, PEGUINT wId); 
};

Method Push

Places a copy of a message in the message queue. The PegPresentationManager will retrieve such messages from the queue and pass them to the receiving message handler.

Method Fold

Looks for a matching message in the queue, and if one is found updates the existing message to contain the data values of the replacing message. If a duplicate message is not found, Fold() calls Push() to place the message at the end of the queue. Messages are determined to be equal if the wType, iData, pTarget, and pSource values of the messages are equivalent.

Method Purge

Removes messages from the queue which have a Mesg.pTarget field matching pTarget. This is used to remove messages from the queue which are destined for objects that have been deleted. If parameter wType is not 0, only messages of that type will be deleted.

Method Messages

Returns the number of messages currently stored in the message queue, waiting to be dispatched.

Method SetTimer

SetTimer is called to load and start a new timer. The timer will send PM_TIMER messages to parameter Who each time the timer expires. The PM_TIMER message iData field will contain the wId of the timer, allowing an object to create and identify several timers simultaneously. Parameter lCount indicates the number of milliseconds before the first timeout. If the lReset value is non-zero, the timer will restart after expiration with lReset milliseconds. This can be used for a periodic timer. If the lReset value is 0, the timer will expire once, send one PM_TIMER message, and destroy itself. This is a one-shot timer.

RTPEG-32 Timers are not guaranteed real-time timers. The internal timer granularity used is the frequency of the timer interrupt, but never less than 10 milliseconds. RTPEG-32 will not sent multiply timer messages to an object when several lReset intervals have expired. Instead, timer messages are dropped when the system falls behind.

Method KillTimer

Destroys the timer owned by Who with ID wId. All timers created by application level objects must be destroyed when the objects are destroyed. Forgetting to kill timers associated with deleted objects will cause invalid pointer references and program failure.

Examples:

The following example sends a message to cause the target object to resize.

void SomeObject::ResizeWindow(PegWindow * Target, PegRect NewSize) 
{ 
   PegMessage NewMessage(PM_SIZE); 
   NewMessage.pTarget = Target; 
   NewMessage.Rect = NewSize; 
   MessageQueue()->Push(NewMessage); 
}

The following example window creates a periodic timer when the window is made visible, receives periodic timer messages, and destroys the timer when the window is hidden:

#define TIMER_1 1 

MyWindow::Message(const PegMessage &Mesg) 
{ 
   switch(Mesg.wType) 
   { 
      case PM_SHOW: 
         SetTimer(TIMER_1, 100, 100); 
         PegWindow::Message(Mesg); 
         break; 
      case PM_HIDE: 
         KillTimer(TIMER_1); 
         PegWindow::Message(Mesg); 
         break; 
      case PM_TIMER: 
         UpdateMySelf();   // periodic action 
         break; 
      default: 
         return PegWindow::Message(Mesg); 
    } 
    return 0; 
}

Class PegScreen