Overview

> All messages are declared in <XMessage.h>. Messages can be sent, dispatched or broadcasted; this is noted in the bracket following the symbolic constant for that event. Each event has two arguments, a long integer value and a pointer to extra data, and can optionally return information, a long integer. The value of each argument, as well as the value expected on return are both given in the description.

> Please note that when the return value is marked as "Ignored", this means the code sending the command ignores the return value. You must return -1 if your event handler routine doesn't handle the code, and any other value (usually zero) if the command was handled.

Periodic Events

> XGAppPreEvent [Broadcast]

> > long arg | Unused; set to 0
> > void *parg | Unused; set to 0

> > return | Ignored

> > This is sent before an event is pulled from the event queue. This gives the application the chance to perform certain housekeeping events before an event is pulled from the event queue.

> XGAppPostEvent [Broadcast]

> > long arg | Unused; set to 0
> > void *parg | Unused; set to 0

> > return | Ignored

> > This is sent at the same time that an XGAppPreEvent is sent, but this is sent to the current focus, and gives editing code the opportunity to blink a cursor.

> XGAppPeriodic [Dispatched]

> > long arg | Unused; set to 0
> > void *parg | Unused; set to 0

> > return | Ignored

> > This is sent after an event has been processed. This gives the application an opportunity to do certain processing after an event has been processed by the application.

Keyboard Events

> KXGKeyEvent [Dispatched]

> > long arg | High word: modifier flags Low word: keyboard key code (generally an ASCII code for the key pressed; see below.)
> > void *parg | Unused; set to 0

> > return | Ignored

> > This is sent to the current focus when a key is pressed. This is sent whenever a key is pressed, but not when a "menu key" is pressed. (A "menu key" is a key which is associated with an accelerator.)

> > The high word of 'arg' (which can be retrieved by using the macro GETHIWORD) contains the modifier flags, a bitfield (defined in <XModifiers.h>) indicating which option keys are currently down. These modifiers are the same as the modifier flags passed to XGView::DoMouseDown() et. al..

> > If the modifer flag 'KSpecialKey' is set, then the low word (which can be retrieved by using the macro GETLOWORD) contains a special key code. Otherwise, the low word contains the ASCII code of the pressed key. Special key codes are defined in <XMessages.h>:

> > KKeyUpCursor | Up arrow key
> > KKeyDownCursor | Down arrow key
> > KKeyLeftCursor | Left arrow key
> > KKeyRightCursor | Right arrow key
> > KKeyInsert | Insert key
> > KKeyDelete | Delete key
> > KKeyHome | Home key
> > KKeyEnd | End key
> > KKeyPageUp | Page up key
> > KKeyPageDown | Page down key
> > KKeyEscape | Escape key
> > KKeyHelp | (Macintosh) Help key
> > KKeyNumLock | Num Lock Key
> > KKeyClear | (Macintosh) Clear key
> > KKeyF1 | F1
> > KKeyF2 | F2
> > KKeyF3 | F3
> > KKeyF4 | F4
> > KKeyF5 | F5
> > KKeyF6 | F6
> > KKeyF7 | F7
> > KKeyF8 | F8
> > KKeyF9 | F9
> > KKeyF10 | F10
> > KKeyF11 | F11
> > KKeyF12 | F12
> > KKeyF13 | F13
> > KKeyF14 | F14
> > KKeyF15 | F15

> KXGMenuKey [Dispatched]

> > This message is sent on Windows and X when a "menu key" (a key pressed with the menu key accelerator) is pressed by the user. This permits keyboard accelerator nagivation of dialogs to take place.

> > long arg | High word: modifier flags Low word: keyboard key code (generally an ASCII code for the key pressed; see below.)
> > void *parg | Unused; set to 0

> > return | If not -1 (that is, if handled), the accelerator key is not processed as an accelerator shortcut in the menu bar.

> > (Note that the arguments here are the same as for KXGKeyEvent above.)

Application Events

> These are events that are sent by the XGAppCore class in order to give the application and YAAF library an opportunity to incercept normal event processing.

> KXGAppEvent [Dispatched]

> > Sent before the event is processed; this gives the application the opportunity to intercept OS events.

> > long arg | Ignored; set to 0
> > void *parg | Pointer to OS specific event structure

> > return | If not -1 (that is, if handled), the event is not further processed by the YAAF library.

> KXGWInternal [Dispatched]

> > This is an internal event internal to Windows 95 and Windows NT. This event is sent to the XGView associated with a control or view and permits the XGView to handle the associated event.

> > long arg | Ignored; set to 0
> > void *parg | Points to an XGSWInternalRecord, defined as:
> >     struct XGSWInternalRecord {
> >         HWND w;
> >         UINT msg;
> >         WPARAM wp;
> >         LPARAM lp;
> >     };

> > return | Ignored

> These events are sent in response to the file being opened or closed from another application. (Generally they are sent in response to the command-line arguments on X or Windows, or in response to Finder Events on the Macintosh.)

> KXGOpenApplication

> > Sent when the appication is open without any files.

> > long arg | Ignored; set to 0
> > void *parg | Ignored; set to NULL

> > return | Ignored

> KXGOpenDocument

> > Sent when the application is aked to open a file.

> > long arg | Ignored; set to 0
> > void *parg | Pointer to the file. Macintosh: Points to an FSSpec Windows, X: Points to a char[] with the file name

> > return | Ignored

> KXGPrintDocument

> > Sent when the application is aked to print a file. (This is sent in response to the command line flag '-p' in X and Windows.)

> > long arg | Ignored; set to 0
> > void *parg | Pointer to the file. Macintosh: Points to an FSSpec Windows, X: Points to a char[] with the file name

> > return | Ignored

> KXGQuitApplication

> > Sent when the application is asked to quit.

> > NOTE: The XGAppCore class handles this event properly by closing all open document windows and marking the event loop as 'terminated.' You should not process this event yourself; instead, you should return '-1' to allow this event to be processed by the XGAppCore class. (This does provide a way to intercept a 'quit' message by allowing you to intercept and return a value other than -1.)

> > long arg | Ignored; set to 0
> > void *parg | Ignored; set to NULL

> > return | Ignored

Menu Events

> These events are dispatched to the current focus in response to the user selecting items in the menu bar.

> KXGCurMenuBar [Dispatched]

> > Sent periodicially to determine which menu bar resource should be displayed. This gives the frontmost window the opportunity to change the current menu to something else.

> > long arg | Unused; set to 0
> > void *parg |
> >     Unused; set to NULL

> > return | The menu bar resource ID to display. If 0, do not change the menu bar from whatever was up before. This is useful for dialog boxes which don't want to change the menu bar. If -1 is returned (meaning not handled by anyone), the system default (128) is used. If >0, the resource number of the menu resouce to display.

> KXGGetMenuStatus [Dispatched]

> > Sent periodically to the focus to determine the state of a particular menu item.

> > long arg | The Command ID of the menu item this is querying.
> > void *parg | A pointer to an XGSMenuStatus record which receives the results:
> >     struct XGSMenuStatus {
> >         bool enable;// true if enabled
> >         bool check; // checkmark?
> >         char mark;  // what mark to use?
> >     };

> > return | Ignored

> KXGDoMenuCommand [Dispatched]

> > Sent when the menu command is selected from the menu bar.

> > long arg | The Command ID of the menu item being done.
> > void *parg | Unused; set to NULL

> > return | Ignored

Document Events

> The XGDocument object sends several different events to indicate it's current status.

> KXGEventDocRenamed [Sent]

> > Sent to all registered receivers when this document is renamed. Windows which display a document should register with the document to receive this event.

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSDocEvent record which contains a pointer to the document
> >     struct XGSDocEvent {
> >         XGDocument *doc;
> >     };

> > return | Ignored

> KXGEventDocChanged [Sent]

> > Sent when the current document has changed. This is sent in response to the document's XGDocument::DocumentChanged method being called. (Note that multiple calls to DocumentChanged are buffered, so only one event is sent.)

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSDocEvent record which contains a pointer to the document
> >     struct XGSDocEvent {
> >         XGDocument *doc;
> >     };

> > return | Ignored

> KXGEventDocSaved [Sent]

> > Sent when the current document has been saved.

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSDocEvent record which contains a pointer to the document
> >     struct XGSDocEvent {
> >         XGDocument *doc;
> >     };

> > return | Ignored

Window Events

> KXGEventWindowName [Dispatched to self]

> > This event is sent when the window is renamed. This gives the application the chance to update a menu list or other list of menu names.

> > Note: If you intercept this event, you must return -1 to allow the event to propagate upwards. This event is used by the XGAppMultiWindow class to maintain the window menu list.

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSWindowEvent record which contains a pointer to the document
> >     struct XGSWindowEvent {
> >         XGWindow *window;
> >     };

> > return | Ignored

> KXGEventWindowCreate [Dispatched to self]

> > This event is sent when the window is first created. This gives the application the chance to update a menu list or other list of menu names.

> > Note: If you intercept this event, you must return -1 to allow the event to propagate upwards. This event is used by the XGAppMultiWindow class to maintain the window menu list.

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSWindowEvent record which contains a pointer to the document
> >     struct XGSWindowEvent {
> >         XGWindow *window;
> >     };

> > return | Ignored

> KXGEventWindowPreDestroy [Dispatched to self]

> > This event is sent when the window is about to be destroyed. This is sent before the warning check (to determine if the window is dirty) is displayed. This gives the application the chance to stop the closing of this window by throwing an exception.

> > Note: If you wish to silently abort closing this window, throw an XGAbort exception. If you wish to display an error message, throw an XGPostError exception (or a related exception). For more information, see the section on Error Management.

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSWindowEvent record which contains a pointer to the document
> >     struct XGSWindowEvent {
> >         XGWindow *window;
> >     };

> > return | Ignored

> KXGEventWindowName [Dispatched to self]

> > This event is sent when the window is closed. This gives the application the chance to update a menu list or other list of menu names. (Note that this is sent just before the XGWindow object is destroyed.)

> > Note: If you intercept this event, you must return -1 to allow the event to propagate upwards. This event is used by the XGAppMultiWindow class to maintain the window menu list.

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSWindowEvent record which contains a pointer to the document
> >     struct XGSWindowEvent {
> >         XGWindow *window;
> >     };

> > return | Ignored

> KXGEventWindowDirty [Dispatched to window]

> > This event is sent to a window that has no associated document object when the YAAF library needs to determine if the window is 'dirty' and needs to be 'saved'. This happens when the window is closed; if the window is dirty, a "Do you wish to save window" alert box is displayed.

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSWindowEvent record which contains a pointer to the document
> >     struct XGSWindowEvent {
> >         XGWindow *window;
> >     };

> > return | If 1, the window is considered dirty. Any other value (including -1) indicates the window is not dirty and shouldn't display the dialog.

> KXGEventWindowSave [Dispatched to window]

> > This event is sent by YAAF when a window that was dirty should be saved. This is sent immediately after a KXGEventWindowDirty event if the user then selected 'Save' from the dialog box. This indicates that the window was successfully saved and can now be closed.

> > long arg | Unused; set to 0
> > void *parg | A pointer to an XGSWindowEvent record which contains a pointer to the document
> >     struct XGSWindowEvent {
> >         XGWindow *window;
> >     };

> > return | If 1, the window was successfully saved and can now be closed. If not 1, the window was not successfully saved and must not be closed. If there was an error you can also safely throw an exception at this point.

Control Events

> These events are sent in response to manipulating controls.

> KXGControlClick

> > This is sent by a button or buton-based control (such as a radio button or a check button) when it is clicked.

> > long arg | The view ID of this control
> > void *parg |
> >     Ignored; set to NULL

> > return | Ignored

> KXGKeyClick

> > This is sent by an edit control when a key is pressed. This gives the top level code the chance to determine if the resulting edit operation is legal or not.

> > long arg | The view ID of this control
> > void *parg |
> >     Pointer to char[] containing the new string.

> > return | If 1, this C string is considered illegal. The operation is aborted and the contents of the edit control are unchanged. If any other value, the edit operation is considered legal and the control is updated.

> KXGListSelect

> > This is sent by a list control when the list is double clicked on. You would get the current value of the list control to determine what item was double-clicked.

> > long arg | The view ID of this control
> > void *parg |
> >     Ignored; set to NULL

> > return | Ignored

> KXGListValue

> > This is sent by a list control's value is changed by a user operation, such as a keyboard click or a mouse click. You would get the current value of the list control to determine what item was selected.

> > long arg | The view ID of this control
> > void *parg |
> >     Ignored; set to NULL

> > return | Ignored

> KXGPopValue

> > This is sent when a pop-up menu has changed value.

> > long arg | The view ID of this control
> > void *parg |
> >     Ignored; set to NULL

> > return | Ignored

> KXGSliderStart

> > This is sent when a slider or scrollbar is about to change in value. This is sent before the control's value is changed; this gives scrolling views and lists the opportunity to refresh themselves and avoid a potential problem with the update region becomming confused.

> > long arg | The view ID of this control
> > void *parg |
> >     Ignored; set to NULL

> > return | Ignored

> KXGSliderValue

> > This is sent when the slider's value is changed.

> > long arg | The view ID of this control
> > void *parg | Pointer to an XGSValue record containing the slider and it's old value
> >     struct XGSValue {
> >         XGSlider *slider;
> >         long      oldVal;
> >         long      newVal;
> >     };

> > return | Ignored

> KXGInlineClose

> > An 'inline editing view' is an editing control that lives in it's own self-contained view which is overlayed for inline editing. This message is sent when the inline editing view is about to closed because the focus changed, and gives the application running this edit box the chance to force the focus not to change.

> > long arg | The refNum passed to the inline editor when it was created
> > void *parg | Pointer to XGSInline structure containing a pointer to the inline editing box
> >     struct XGSInline {
> >         XGInlineEdit *edit;
> >     };

> > return | If this returns 1, the edit box should not be closed. If not 1, the inline editor box is closed and the focus is switched to another view.