DeskLib 2.90a:EventMsg.h

Contents

• Introduction and Overview
• Functions
  • EventMsg_Claim
  • EventMsg_Release
  • EventMsg_ReleaseSpecific
  • EventMsg_ReleaseWindow
  • EventMsg_ReleaseMessage
• Type
  • eventmsg_claimorreleasefn

Introduction and Overview

EventMsg is an add-on for the Event system, which provides a layer of handlers to handle user messages (reason codes 17-19).

Functions

---

EventMsg_Claim

BOOL EventMsg_Claim(message_action messagetype, window_handle window, event_handler handler, void *reference);

Much like Event_Claim, but for messages.

Pass this the type of message (message action) you want to register a handler for, the window for which this applies (where appropriate) and the handler function to attach. 'messagetype' or 'window' can by event_ANY to be called for any message or any window. 'reference' will be passed to your handler - it can be anything you want.

Priorities work like Event_Claim - specific window handlers have priority over all-window ones.

This will call Wimp_AddMessages for any message codes you claim, so that your task does not need to pass a list of messages to listen for when the Wimp_Initialise SWI is called by the Event library.

---

EventMsg_Release

int EventMsg_Release(message_action messagetype, window_handle window, event_handler handler);

This releases all instances of 'handler' attached to the given message and window.

It returns the number of handlers released.

---

EventMsg_ReleaseSpecific

BOOL EventMsg_ReleaseSpecific(message_action messagetype, window_handle window, event_handler handler, void *ref);

This releases the message handler which was attached with the given type, window, etc. This should be called with same parameters as were passed to EventMsg_Claim to claim it.

It returns TRUE if it released a handler, FALSE otherwise.

---

EventMsg_ReleaseWindow

int EventMsg_ReleaseWindow(window_handle window);

Finds and removes all message handlers that relate to the given window. If you pass in event_ANY as the window handle, all non-window-specific handlers will be released.

It returns the number of handlers released.

---

EventMsg_ReleaseMessage

BOOL EventMsg_ReleaseMessage(message_action messagetype);

Finds and removes all message handlers that relate to the specified message type. If you pass in event_ANY as the type, all handlers that were registered as event_ANY will be released.

Type

---

eventmsg_claimorreleasefn

typedef BOOL (*eventmsg_claimorreleasefn)(message_action messagetype, window_handle window, event_handler handler, void *ref);

This is the function-type of the EventMsg_Claim and EventMsg_ReleaseSpecific functions. It is useful for writing functions which accept a pointer to either of these functions, in order to claim or release a set of message events consistently.