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.