XlDispatch.mesa
Copyright Ó 1990, 1991 by Xerox Corporation. All rights reserved.
Christian Jacobi, November 12, 1990 5:42 pm PST
Christian Jacobi, March 7, 1991 5:01 pm PST
DIRECTORY
Xl USING [Connection, Details, Event, Match, MatchList, SetOfEvent, unspecifiedEvents, Window];
General event dispatching
This ought to be used mainly by the main loop of XlImpl; but it is conceivable that these procedures are useful for applications like TIP table implementations.
DispatchHandle:
TYPE =
REF DispatchHandleRec;
One such data per connection.
DispatchHandleRec: TYPE;
GetDispatchHandle:
PROC [c: Connection]
RETURNS [DispatchHandle];
Get the dispatch data structure.
Dispatch:
PROC [handle: DispatchHandle, event: Event];
Dispatches to all listeners for event.dispatchDrawable.
FindAndDispatch:
PROC [event: Event];
Get appropriate DispatchHandle and dispatches to all listeners for event.dispatchDrawable.
Speed hack useful for speeding up local events
This ought to be used by some speed crazy applications dispatching local events. E.g. TIP table implementations.
WindowData:
TYPE =
REF WindowDataRec;
One such data per window while it is active.
WindowDataRec: TYPE;
GetWindowData:
PROC [c: Connection, w: Window]
RETURNS [WindowData];
Get window data structure which allows DispatchExplicite.
This data structure is kept alive only while the window has active matches.
Returns NIL if not available. For safe use, use only after adding match and don't use after removing of match.
DispatchExplicite:
PROC [wd: WindowData, event: Event];
Dispatches to explicite listeners; might be slightly faster then Dispatch.
Adding and removing matches
Updating the knowledge what to call on dispatch.
In general matches are set up and not removed. Once an event made it all the way from the X server we can not gain much efficiency by discarding the event before dispatching. In exceptional cases (ICCCM) we are required to listen to events sent in account of foreign windows owned by other connections. The problem is to guarantee cleanup of foreign WindowData when those windows are no more used, or, the window or its real connection is destroyed.
AddMatch:
PROC [c: Connection, w: Window, match: Match ¬
NIL, generate: SetOfEvent ¬ unspecifiedEvents, details: Details ¬
NIL];
Add a match and events for a window.
(Removed on window deletion.)
RemoveMatch:
PROC [c: Connection, w: Window, match: Match ¬
NIL, details: Details ¬
NIL];
Removes all matches on window using equal proc, thread and data.
AddMatches:
PROC [c: Connection, w: Window, matchList: MatchList ¬
NIL, generate: SetOfEvent ¬ unspecifiedEvents, details: Details ¬
NIL];
Add multiple matches and events for a window.
(Removed on window deletion.)
AddMatchForUnregistered:
PROC [c: Connection, match: Match ¬
NIL];
Add match for non-found windows.
Priviledged procedures
Expensive.
AddPriviledgedMatch:
PRIVATE
PROC [c: Connection, match: Match];
Event will match non-explicite matches for all windows.
RemovePriviledgedMatch:
PROC [c: Connection, match: Match];
Get rid of expensive priviledged match as fast as possible.
Private engine room procedures
Reserved for the implementation of XlImpl and friends. Clients ought not use these procedures as problems from incorrect use may impact independent clients.
InitConnection:
PRIVATE
PROC [c: Connection];
Call this after creation of connection to initialize internal data.
InitWindow:
PRIVATE
PROC [c: Connection, w: Window];
Call this after creation of a window.
RemoveWindow:
PRIVATE
PROC [c: Connection, w: Window];
Call this on a destroyNotify event after dispatching the event.
InternalAddMatch:
PRIVATE
PROC [c: Connection, w: Window, match: Match, generate: SetOfEvent ¬ unspecifiedEvents];
Call this from within c's lock only. Procedure made for implementation of Xl.CreateWindow only.
Des NOT request server to generate "generate" events. Caller must do this and must also require structureNotifyMask himself.
EnforcedSetOfEvent:
PRIVATE
PROC [c: Connection, w: Window, external: SetOfEvent ¬ unspecifiedEvents]
RETURNS [SetOfEvent];
To be used by implementation of Xl.ChangeWindowAttributes.
Does tell XlDispatchImpl that the externally set events are "external". They are or'ed with the internal set of events when doing a internal ChangeWindowAttributes.
Returns set of internally required events or'ed with "external".
Must be used reliably and within connection lock only.