wGui has a messaging framework which it uses for passing messages and events between objects.
Message objects are used to notify other objects of events (such as user input) and as a method of passing information. All message objects are derived from the CMessage class which simply provides an identifier of the message type, and an optional destination for the message (so that other objects know to ignore the message).
There are a number of derived message classes, like CMouseMessage, which are translated from SDL mouse events. Since all user input is translated into messages, this allows the programmer to simulate user input programmatically. A CKeyboardMessage object will look the same if it came from an SDL keyboard event, or was created by the programmer.
SDL events that aren't translated as a specific wGui message will be passed to the app as a CSDLMessage which contains all the original SDL_Event information.
Message objects are managed by a message server. The server is responsible for queing and distributing messages. An application requires one and only one message server. This is handled by the CMessageServer class. CMessageServer is a singleton, and doesn't need to be instantiated by the programmer. Simply calling it's static Instance() method will instantiate a server if required and will return a reference to it.
Messages are distributed to clients on a priority basis. Higher priority clients get messages before lower priority clients. For clients of the same priority, there is no predetermined order in which they receive messages (though the current implimentation dictates that they will get them in the order in which they register with the server). The destination value of a message is ignored by the server, it is up to the clients to inspect that value and ignore messages that are not destined for them (this allows a client to intercept messages not destined for another object).
A message will be passed to all clients registered for that message in order until one returns true from their message handler. The true indicates that the client handled the message.
The Application is responsible for checking the Server queue and telling it to dispatch the next message.
Message clients are any objects that can receive messages. The CMessageClient class is the base from which such objects should be derived. Clients must also register with the server to receive messages. When registering, the client specifies what types of messages it wants to receive, and optionally the priority. By registering at a higher priority than other objects, a client can ensure that it receives the message first.
This can be useful for modifying or filtering the message before it was passed on to the other objects. For example if you wanted to be able to reverse the left and right mouse buttons, instead of rewriting every object, an object would be created to simply reverse the button values in a mouse message, and then pass it on. This object would then just have to register itself with the server at a higher priority than the other controls in the application.
CMessageClient defines an overidable MessageHandler function which is what recieves the messages from the server. If a client handles a message, it should generally return true from the handler to indicate to the server that it has done something with the message. Once a client returns true, the server will stop sending that message to other clients. If the client doesn't do anything with a message or is modifying a message that should be passed on to other objects (as in the mouse button switching example), the handler should return false so that the server continues to distribute the message. All of the controls in wGui are also message clients, many of which register for mouse messages, so it is possible to cause strange behavior by eating the messages before the controls get them.
Mouse messages represent a special case for the messaging system. When a mouse message is sent, a CView object will call OnMouseButtonDown() or OnMouseButtonUp() for it's clients. These handlers should determine which window is on 'top' and ensure that only that window processes the mouse button event. The regular mouse message is still passed to all message clients that requested it, but it should be used for notification purposes only. Message clients shouldn't return true from their HandleMessage() methods for mouse button messages.