Detailed explanation of every message (aka event or note) used by Elgrint.
|ChildListChanged||One or more child windows of this window have been opened or closed.|
|CursorMoved||Input event from a screen pointing device (mouse, touchpad, touchpoint, pen, etc).|
|DirectoryChanged||A non-fixed drive has been activated or deactivated.|
|DirectoryChanging||An existing data carrier is about to be removed - the data on it can still be accessed, but not for long.|
|EnablingChanged||Window's enabling state changed (window was enabled or disabled).|
|FocusChanged||Window's focus state has changed (window gained or lost the input focus).|
|HotChanged||Window's hot state changes (window gained or lost the hot state).|
|KeysEntered||Input event from a keyboard, keypad, mouse button, touchpad, or mouse wheel.|
|Moved||Window's position relatively to its parent's top-left corner (including z-order) has changed.|
|Notice||Window has generated a custom event using MWindow::genNotice.|
|Paint||Informs the window that its graphical content needs to be repainted right now.|
|RectChanging||Window's size and/or position (including z-order) are about to change.|
|RemoteNotice||External custom event has been generated by another thread or another process.|
|Resized||Window's size has changed.|
|StringEntered||Derived input event - keyboard input translated into characters.|
|SystemResumed||System has been reactivated after a sleep or an hibernation mode.|
|SystemSuspending||System is about to enter a sleep/hibernation mode, or is shutting down.|
|TimerExpired||Input event from the system clock that signals an expiration of a preset timer.|
Messages report various events, which can have interest to the app's windows. Windows receive these messages through special overloadable methods called message handlers. Each message named XXXX has a corresponding mcXXXX numeric identifier (a member of the MMessageCode enumeration), the void OnXXXX() handler (protected virtual method of MWindow), and an ON_XXXX macro for a more convenient overloading of the corresponding handler.
There are three types of messages, depending on their relationship with the corresponding event: post-message, pre-message, and request-message (aka in-message).
- Post-messages are received shortly AFTER the corresponding event occurs. Vast majority of Elgrint messages are post-messages. A post-message name always ends with "ed" (past tense) to indicate that the event has already occurred, e.g. Moved or TimerExpired
- Pre-messages are received shortly BEFORE the corresponding event occurs. Pre-messages are needed only when a corresponding post-message would be inadequate (see each such message for the reason why it has to be a pre-message). A pre-message name always ends with "ing" (present progressive tense) to indicate that the event is about to occur. Pre-message events cannot be prevented. There are only 3 standard pre-messages in Elgrint: RectChanging, DirectoryChanging, and SystemSuspending
- Request-messages occupy the middle ground between post-messages and pre-messages - they actually MAKE the event. There is only one standard request message - Paint, but generally speaking, a request name ends with an imperative or command verb (paint, stop, close, etc.)
Messages can also be grouped in a different way, according to the source that causes the corresponding event. Then, there are three kinds of events: input, presentation, and system.
- Input messages are generated by input device events (directly or indirectly). There are 4 input messages: KeysEntered, StringEntered, CursorMoved, and TimerExpired
- Presentation messages are generated by window commands, and generally indicate a change in window's state or parameter. Some may also be indirectly triggered by input or system events. There are 9 presentation messages: FocusChanged, HotChanged, and EnablingChanged report a window state change; RectChanging, Resized, and Moved deal with the change in window's rectangle (size and position); and the remaining three are ChildListChanged, Paint, and Notice
- System (aka "external" or "remote") messages are usually (but not always) generated by system events outside of this app or by other programs, although RemoteNotice can be generated from the current app as well. The most defining characteristic of the system messages is that they are delivered only to the screen window, so MWindow::requestPropagation with psScreen must be used to process these messages, since the screen does not allow user-defined message processing. There are 5 system messages: RemoteNotice reports custom events; DirectoryChanging and DirectoryChanged report file system events; and SystemSuspending and SystemResumed report changes in the system state
Finally, messages can be either queued, or non-queued (aka stacked), depending on the way they are delivered.
- Queued messages are sent to the message queue (see MWindow::runMessageLoop), from which they are extracted one by one, and each is processed in a separate iteration of the message loop. Thus, queued messages are not processed immediately after being generated, but only when the app is ready to process them, and the function that generates such message returns before the message is processed. All the input and the system messages are originally queued (they have to be, because the triggering event occurs outside of the app's main thread). ChildListChanged is also queued for performance reasons (to prevent multiple messages if many children are being created or destroyed at once). All other messages are queued when generated by the system, and stacked when generated by the app's main thread
- Stacked messages are processed immediately after being generated, in the same message loop iteration, and before the generating function returns. All the programmatic events (i.e. generated by calling some Elgrint function), except for RemoteNotice and ChildListChanged are stacked. Propagated messages (see MWindow::propagateMsgTo) are always stacked, even if the original message is queued. When a stacked message mc2 is generated during the processing of another message mc1, mc1 becomes "frozen" and mc2 is processed "on top" of mc1 (that is why it is called "stacked"). When the processing of mc2 is complete, the processing of mc1 is resumed from the point at which it had become frozen
- Queued messages are also called "posted" or "asynchronous", and stacked messages are called "sent" or "synchronous"
- See MWindow::runMessageLoop for additional information about messages and message processing
Let us know
Please Contact us to report any errors on this page, or to suggest any improvements.