/*
* tkGrab.c --
*
* This file provides procedures that implement grabs for Tk.
*
* Copyright (c) 1992-1994 The Regents of the University of California.
* Copyright (c) 1994-1995 Sun Microsystems, Inc.
*
* See the file "license.terms" for information on usage and redistribution
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
* SCCS: @(#) tkGrab.c 1.51 96/09/05 12:29:43
*/
#include "tkInt.h"
/*
* The grab state machine has four states: ungrabbed, button pressed,
* grabbed, and button pressed while grabbed. In addition, there are
* three pieces of grab state information: the current grab window,
* the current restrict window, and whether the mouse is captured.
*
* The current grab window specifies the point in the Tk window
* heirarchy above which pointer events will not be reported. Any
* window within the subtree below the grab window will continue to
* receive events as normal. Events outside of the grab tree will be
* reported to the grab window.
*
* If the current restrict window is set, then all pointer events will
* be reported only to the restrict window. The restrict window is
* normally set during an automatic button grab.
*
* The mouse capture state specifies whether the window system will
* report mouse events outside of any Tk toplevels. This is set
* during a global grab or an automatic button grab.
*
* The transitions between different states is given in the following
* table:
*
* Event\State U B G GB
* ----------- -- -- -- --
* FirstPress B B GB GB
* Press B B G GB
* Release U B G GB
* LastRelease U U G G
* Grab G G G G
* Ungrab U B U U
*
* Note: U=Ungrabbed, B=Button, G=Grabbed, GB=Grab and Button
*
* In addition, the following conditions are always true:
*
* State\Variable Grab Restrict Capture
* -------------- ---- -------- -------
* Ungrabbed 0 0 0
* Button 0 1 1
* Grabbed 1 0 b/g
* Grab and Button 1 1 1
*
* Note: 0 means variable is set to NULL, 1 means variable is set to
* some window, b/g means the variable is set to a window if a button
* is currently down or a global grab is in effect.
*
* The final complication to all of this is enter and leave events.
* In order to correctly handle all of the various cases, Tk cannot
* describes the correct sequence of enter and leave events that
* should be observed by Tk scripts:
*
* ------------ ----------------------
* LastRelease(B | GB): restrict window -> anc(grab window, event window)
* Grab(U | B): event window -> anc(grab window, event window)
* Grab(G): anc(old grab window, event window) ->
* anc(new grab window, event window)
* Grab(GB): restrict window -> anc(new grab window, event window)
* Ungrab(G): anc(grab window, event window) -> event window
* Ungrab(GB): restrict window -> event window
*
* Note: anc(x,y) returns the least ancestor of y that is in the tree
* of x, terminating at toplevels.
*/
/*
* The following structure is used to pass information to
* GrabRestrictProc from EatGrabEvents.
*/
typedef struct {
} GrabInfo;
/*
* Bit definitions for grabFlags field of TkDisplay structures:
*
* GRAB_GLOBAL 1 means this is a global grab (we grabbed via
* the server so all applications are locked out).
* 0 means this is a local grab that affects
* only this application.
* GRAB_TEMP_GLOBAL 1 means we've temporarily grabbed via the
* server because a button is down and we want
* to make sure that we get the button-up
* event. The grab will be released when the
* last mouse button goes up.
*/
/*
* The following structure is a Tcl_Event that triggers a change in
* the grabWinPtr field of a display. This event guarantees that
* the change occurs in the proper order relative to enter and leave
* events.
*/
typedef struct NewGrabWinEvent {
* recorded instead of a (TkWindow *) because
* it will allow us to detect cases where
* the window is destroyed before this event
* is processed. */
/*
* The following magic value is stored in the "send_event" field of
* EnterNotify and LeaveNotify events that are generated in this
* file. This allows us to separate "real" events coming from the
* server from those that we generated.
*/
/*
* Mask that selects any of the state bits corresponding to buttons,
* plus masks that select individual buttons' bits:
*/
#define ALL_BUTTONS \
static unsigned int buttonStates[] = {
};
/*
* Forward declarations for procedures declared later in this file:
*/
unsigned int serial));
int *countPtr2));
int flags));
int EnterEvents));
TkWindow *grabWinPtr));
/*
*----------------------------------------------------------------------
*
* Tk_GrabCmd --
*
* This procedure is invoked to process the "grab" Tcl command.
* See the user documentation for details on what it does.
*
* Results:
* A standard Tcl result.
*
* Side effects:
* See the user documentation.
*
*----------------------------------------------------------------------
*/
/* ARGSUSED */
int
* interpreter. */
int argc; /* Number of arguments. */
char **argv; /* Argument strings. */
{
int globalGrab, c;
if (argc < 2) {
" option ?arg arg ...?\"", (char *) NULL);
return TCL_ERROR;
}
c = argv[1][0];
if (c == '.') {
if (argc != 2) {
goto badArgs;
}
return TCL_ERROR;
}
&& (length >= 2)) {
if (argc != 3) {
goto badArgs;
}
return TCL_ERROR;
}
if (argc > 3) {
return TCL_ERROR;
}
if (argc == 3) {
return TCL_ERROR;
}
}
} else {
}
}
}
return TCL_OK;
if (argc != 3) {
return TCL_ERROR;
}
} else {
}
&& (length >= 2)) {
return TCL_ERROR;
}
if (argc == 3) {
globalGrab = 0;
} else {
globalGrab = 1;
(char *) NULL);
return TCL_ERROR;
}
}
return TCL_ERROR;
}
&& (length >= 2)) {
if (argc != 3) {
return TCL_ERROR;
}
(Tk_Window) clientData);
return TCL_ERROR;
}
} else {
}
} else {
"\": must be current, release, set, or status",
(char *) NULL);
return TCL_ERROR;
}
return TCL_OK;
}
/*
*----------------------------------------------------------------------
*
* Tk_Grab --
*
* Grabs the pointer and keyboard, so that mouse-related events are
* only reported relative to a given window and its descendants.
*
* Results:
* A standard Tcl result is returned. TCL_OK is the normal return
* value; if the grab could not be set then TCL_ERROR is returned
* and interp->result will hold an error message.
*
* Side effects:
* Once this call completes successfully, no window outside the
* tree rooted at tkwin will receive pointer- or keyboard-related
* events until the next call to Tk_Ungrab. If a previous grab was
* in effect within this application, then it is replaced with a new
* one.
*
*----------------------------------------------------------------------
*/
int
* is to be grabbed. */
int grabGlobal; /* Non-zero means issue a grab to the
* server so that no other application
* gets mouse or keyboard events.
* Zero means the grab only applies
* within this application. */
{
unsigned int serial;
return TCL_OK;
}
return TCL_ERROR;
}
}
if (!grabGlobal) {
unsigned int state;
/*
* Local grab. However, if any mouse buttons are down, turn
* it into a global grab temporarily, until the last button
* goes up. This does two things: (a) it makes sure that we
* see the button-up event; and (b) it allows us to track mouse
* motion among all of the windows of this application.
*/
if ((state & ALL_BUTTONS) != 0) {
goto setGlobalGrab;
}
} else {
/*
* Tricky point: must ungrab before grabbing. This is needed
* in case there is a button auto-grab already in effect. If
* there is, and the mouse has moved to a different window, X
* won't generate enter and leave events to move the mouse if
* we grab without ungrabbing.
*/
/*
* Another tricky point: there are races with some window
* managers that can cause grabs to fail because the window
* manager hasn't released its grab quickly enough. To work
* around this problem, retry a few times after AlreadyGrabbed
* errors to give the grab release enough time to register with
* the server.
*/
grabResult = 0; /* Needed only to prevent gcc
* compiler warnings. */
None, CurrentTime);
if (grabResult != AlreadyGrabbed) {
break;
}
Tcl_Sleep(100);
}
if (grabResult != 0) {
if (grabResult == GrabNotViewable) {
} else if (grabResult == AlreadyGrabbed) {
goto alreadyGrabbed;
} else if (grabResult == GrabFrozen) {
} else if (grabResult == GrabInvalidTime) {
} else {
}
return TCL_ERROR;
}
if (grabResult != 0) {
goto grabError;
}
/*
* Eat up any grab-related events generated by the server for the
* grab. There are several reasons for doing this:
*
* 1. We have to synthesize the events for local grabs anyway, since
* the server doesn't participate in them.
* 2. The server doesn't always generate the right events for global
* grabs (e.g. it generates events even if the current window is
* in the grab tree, which we don't want).
* 3. We want all the grab-related events to be processed immediately
* (before other events that are already queued); events coming
* from the server will be in the wrong place, but events we
* synthesize here will go to the front of the queue.
*/
}
/*
* Synthesize leave events to move the pointer from its current window
* up to the lowest ancestor that it has in common with the grab window.
* However, only do this if the pointer is outside the grab window's
* subtree but inside the grab window's application.
*/
break;
}
break;
}
}
}
return TCL_OK;
}
/*
*----------------------------------------------------------------------
*
* Tk_Ungrab --
*
* Releases a grab on the mouse pointer and keyboard, if there
* is one set on the specified window.
*
* Results:
* None.
*
* Side effects:
* Pointer and keyboard events will start being delivered to other
* windows again.
*
*----------------------------------------------------------------------
*/
void
* released. */
{
unsigned int serial;
return;
}
}
/*
* Generate events to move the pointer back to the window where it
* really is. Some notes:
* 1. As with grabs, only do this if the "real" window is not a
* descendant of the grab window, since in this case the pointer
* is already where it's supposed to be.
* 2. If the "real" window is in some other application then don't
* generate any events at all, since everything's already been
* reported correctly.
* 3. Only generate enter events. Don't generate leave events,
* because we never told the lower-level windows that they
* had the pointer in the first place.
*/
if (winPtr == grabWinPtr) {
break;
}
NotifyUngrab, 0, 1);
}
break;
}
}
}
/*
*----------------------------------------------------------------------
*
* ReleaseButtonGrab --
*
* This procedure is called to release a simulated button grab, if
* there is one in effect. A button grab is present whenever
* dispPtr->buttonWinPtr is non-NULL or when the GRAB_TEMP_GLOBAL
* flag is set.
*
* Results:
* None.
*
* Side effects:
* DispPtr->buttonWinPtr is reset to NULL, and enter and leave
* events are generated if necessary to move the pointer from
* the button grab window to its current window.
*
*----------------------------------------------------------------------
*/
static void
* released. */
{
unsigned int serial;
}
}
}
}
/*
*----------------------------------------------------------------------
*
* TkPointerEvent --
*
* This procedure is called for each pointer-related event, before
* the event has been processed. It does various things to make
* grabs work correctly.
*
* Results:
* If the return value is 1 it means the event should be processed
* (event handlers should be invoked). If the return value is 0
* it means the event should be ignored in order to make grabs
* work correctly. In some cases this procedure modifies the event.
*
* Side effects:
* Grab state information may be updated. New events may also be
* pushed back onto the event queue to replace or augment the
* one passed in here.
*
*----------------------------------------------------------------------
*/
int
* where event was reported. */
{
unsigned int serial;
int outsideGrabTree = 0;
int ancestorOfGrab = 0;
* reported to an application that is
* affected by the grab. */
/*
* Collect information about the grab (if any).
*/
switch (TkGrabState(winPtr)) {
case TK_GRAB_IN_TREE:
appGrabbed = 1;
break;
case TK_GRAB_ANCESTOR:
appGrabbed = 1;
outsideGrabTree = 1;
ancestorOfGrab = 1;
break;
case TK_GRAB_EXCLUDED:
appGrabbed = 1;
outsideGrabTree = 1;
break;
}
/*
* Keep track of what window the mouse is *really* over.
* Any events that we generate have a special send_event value,
* which is detected below and used to ignore the event for
* purposes of setting serverWinPtr.
*/
} else {
}
}
/*
* When a grab is active, X continues to report enter and leave
* events for windows outside the tree of the grab window:
* 1. Detect these events and ignore them except for
* windows above the grab window.
* 2. Allow Enter and Leave events to pass through the
* windows above the grab window, but never let them
* end up with the pointer *in* one of those windows.
*/
if (outsideGrabTree && appGrabbed) {
if (!ancestorOfGrab) {
return 0;
}
case NotifyInferior:
return 0;
case NotifyAncestor:
break;
case NotifyNonlinear:
break;
}
}
/*
* Make buttons have the same grab-like behavior inside a grab
* as they do outside a grab: do this by ignoring enter and
* leave events except for the window in which the button was
* pressed.
*/
return 0;
}
}
return 1;
}
if (!appGrabbed) {
return 1;
}
/*
* When grabs are active, X reports motion events relative to the
* window under the pointer. Instead, it should report the events
* relative to the window the button went down in, if there is a
* button down. Otherwise, if the pointer window is outside the
* subtree of the grab window, the events should be reported
* relative to the grab window. Otherwise, the event should be
* reported to the pointer window.
*/
}
return 0;
}
return 1;
}
/*
* Process ButtonPress and ButtonRelease events:
* 1. Keep track of whether a button is down and what window it
* went down in.
* 2. If the first button goes down outside the grab tree, pretend
* it went down in the grab window. Note: it's important to
* redirect events to the grab window like this in order to make
* things like menus work, where button presses outside the
* grabbed menu need to be seen. An application can always
* ignore the events if they occur outside its window.
* 3. If a button press or release occurs outside the window where
* the first button was pressed, retarget the event so it's reported
* to the window where the first button was pressed.
* 4. If the last button is released in a window different than where
* move the mouse from the button window to its current window.
* 5. If the grab is set at a time when a button is already down, or
* if the window where the button was pressed was deleted, then
* dispPtr->buttonWinPtr will stay NULL. Just forget about the
* auto-grab for the button press; events will go to whatever
* window contains the pointer. If this window isn't in the grab
* tree then redirect events to the grab window.
* 6. When a button is pressed during a local grab, the X server sets
* a grab of its own, since it doesn't even know about our local
* grab. This causes enter and leave events no longer to be
* generated in the same way as for global grabs. To eliminate this
* problem, set a temporary global grab when the first button goes
* down and release it when the last button comes up.
*/
if (outsideGrabTree) {
} else {
}
}
if (outsideGrabTree) {
return 0; /* Note 2. */
}
CurrentTime) == 0) {
CurrentTime) == 0) {
} else {
}
}
}
return 1;
}
} else {
}
}
return 0; /* Note 3. */
}
}
return 1;
}
/*
*----------------------------------------------------------------------
*
* TkChangeEventWindow --
*
* Given an event and a new window to which the event should be
* retargeted, modify fields of the event so that the event is
* properly retargeted to the new window.
*
* Results:
* The following fields of eventPtr are modified: window,
* subwindow, x, y, same_screen.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
void
* type ButtonPress, ButtonRelease, KeyPress,
* KeyRelease, MotionNotify, EnterNotify,
* or LeaveNotify. */
{
continue;
}
}
}
sameScreen = 1;
} else {
sameScreen = 0;
}
} else {
}
}
/*
*----------------------------------------------------------------------
*
* TkInOutEvents --
*
* This procedure synthesizes EnterNotify and LeaveNotify events
* to correctly transfer the pointer from one window to another.
* It can also be used to generate FocusIn and FocusOut events
* to move the input focus.
*
* Results:
* None.
*
* Side effects:
* Synthesized events may be pushed back onto the event queue.
* The event pointed to by eventPtr is modified.
*
*----------------------------------------------------------------------
*/
void
* properly set except for type, window,
* subwindow, x, y, detail, and same_screen
* (Not all of these fields are valid for
* though x and y needn't be valid). */
* focus (NULL means it was not in a window
* managed by this process). */
* or focus (NULL means it's not one managed
* by this process). */
int leaveType; /* Type of events to generate for windows
* being left (LeaveNotify or FocusOut). 0
* means don't generate leave events. */
int enterType; /* Type of events to generate for windows
* being entered (EnterNotify or FocusIn). 0
* means don't generate enter events. */
* the system event queue. */
{
/*
* There are four possible cases to deal with:
*
* 1. SourcePtr and destPtr are the same. There's nothing to do in
* this case.
* 2. SourcePtr is an ancestor of destPtr in the same top-level
* window. Must generate events down the window tree from source
* to dest.
* 3. DestPtr is an ancestor of sourcePtr in the same top-level
* window. Must generate events up the window tree from sourcePtr
* to destPtr.
* 4. All other cases. Must first generate events up the window tree
* from sourcePtr to its top-level, then down from destPtr's
* top-level to destPtr. This form is called "non-linear."
*
* The call to FindCommonAncestor separates these four cases and decides
* how many levels up and down events have to be generated for.
*/
return;
}
focus = 1;
} else {
focus = 0;
}
/*
*/
#define QUEUE(w, t, d) \
if (focus) { \
} else { \
TkChangeEventWindow(eventPtr, w); \
} \
}
if (downLevels == 0) {
/*
* SourcePtr is an inferior of destPtr.
*/
if (leaveType != 0) {
}
}
}
} else if (upLevels == 0) {
/*
* DestPtr is an inferior of sourcePtr.
*/
}
if (enterType != 0) {
for (i = downLevels-1; i > 0; i--) {
}
}
}
}
} else {
/*
* Non-linear: neither window is an inferior of the other.
*/
if (leaveType != 0) {
}
}
if (enterType != 0) {
for (i = downLevels-1; i > 0; i--) {
}
}
}
}
}
}
/*
*----------------------------------------------------------------------
*
* MovePointer2 --
*
* This procedure synthesizes EnterNotify and LeaveNotify events
* to correctly transfer the pointer from one window to another.
* It is different from TkInOutEvents in that no template X event
* needs to be supplied; this procedure generates the template
* event and calls TkInOutEvents.
*
* Results:
* None.
*
* Side effects:
* Synthesized events may be pushed back onto the event queue.
*
*----------------------------------------------------------------------
*/
static void
* means it's not one managed by this
* process). */
* pointer (NULL means it's not one managed
* by this process). */
* NotifyNormal or NotifyUngrab. */
int leaveEvents; /* Non-zero means generate leave events for the
* windows being left. Zero means don't
* generate leave events. */
int enterEvents; /* Non-zero means generate enter events for the
* windows being entered. Zero means don't
* generate enter events. */
{
return;
}
}
}
/*
*----------------------------------------------------------------------
*
* TkGrabDeadWindow --
*
* This procedure is invoked whenever a window is deleted, so that
* grab-related cleanup can be performed.
*
* Results:
* None.
*
* Side effects:
* Various cleanups happen, such as generating events to move the
* pointer back to its "natural" window as if an ungrab had been
* done. See the code.
*
*----------------------------------------------------------------------
*/
void
* of being deleted. */
{
/*
* Grab window was deleted. Release the grab.
*/
}
} else {
}
}
}
}
/*
*----------------------------------------------------------------------
*
* EatGrabEvents --
*
* This procedure is called to eliminate any Enter, Leave,
* FocusIn, or FocusOut events in the event queue for a
* display that have mode NotifyGrab or NotifyUngrab and
* have a serial number no less than a given value and are not
* generated by the grab module.
*
* Results:
* None.
*
* Side effects:
* DispPtr's display gets sync-ed, and some of the events get
* removed from the Tk event queue.
*
*----------------------------------------------------------------------
*/
static void
unsigned int serial; /* Only discard events that have a serial
* number at least this great. */
{
}
}
/*
*----------------------------------------------------------------------
*
* GrabRestrictProc --
*
* A Tk_RestrictProc used by EatGrabEvents to eliminate any
* Enter, Leave, FocusIn, or FocusOut events in the event queue
* for a display that has mode NotifyGrab or NotifyUngrab and
* have a serial number no less than a given value.
*
* Results:
* Returns either TK_DISCARD_EVENT or TK_DEFER_EVENT.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
static Tk_RestrictAction
{
/*
* The diff caculation is trickier than it may seem. Don't forget
* that serial numbers can wrap around, so can't compare the two
* serial numbers directly.
*/
} else {
mode = NotifyNormal;
}
|| (diff < 0)) {
return TK_DEFER_EVENT;
} else {
return TK_DISCARD_EVENT;
}
}
/*
*----------------------------------------------------------------------
*
* QueueGrabWindowChange --
*
* This procedure queues a special event in the Tcl event queue,
* which will cause the "grabWinPtr" field for the display to get
* modified when the event is processed. This is needed to make
* sure that the grab window changes at the proper time relative
* to grab-related enter and leave events that are also in the
* queue. In particular, this approach works even when multiple
* grabs and ungrabs happen back-to-back.
*
* Results:
* None.
*
* Side effects:
* DispPtr->grabWinPtr will be modified later (by GrabWinEventProc)
* when the event is removed from the grab event queue.
*
*----------------------------------------------------------------------
*/
static void
* window. */
* window (may be NULL). */
{
if (grabWinPtr == NULL) {
} else {
}
}
/*
*----------------------------------------------------------------------
*
* GrabWinEventProc --
*
* This procedure is invoked as a handler for Tcl_Events of type
* NewGrabWinEvent. It updates the current grab window field in
* a display.
*
* Results:
* Returns 1 if the event was processed, 0 if it should be deferred
* for processing later.
*
* Side effects:
* The grabWinPtr field is modified in the display associated with
* the event.
*
*----------------------------------------------------------------------
*/
static int
int flags; /* Flags argument to Tk_DoOneEvent: indicates
* what kinds of events are being processed
* right now. */
{
return 1;
}
/*
*----------------------------------------------------------------------
*
* FindCommonAncestor --
*
* Given two windows, this procedure finds their least common
* ancestor and also computes how many levels up this ancestor
* is from each of the original windows.
*
* Results:
* If the windows are in different applications or top-level
* windows, then NULL is returned and *countPtr1 and *countPtr2
* are set to the depths of the two windows in their respective
* top-level windows (1 means the window is a top-level, 2 means
* its parent is a top-level, and so on). Otherwise, the return
* value is a pointer to the common ancestor and the counts are
* set to the distance of winPtr1 and winPtr2 from this ancestor
* (1 means they're children, 2 means grand-children, etc.).
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
static TkWindow *
int *countPtr1; /* Store nesting level of winPtr1 within
* common ancestor here. */
int *countPtr2; /* Store nesting level of winPtr2 within
* common ancestor here. */
{
/*
* Mark winPtr1 and all of its ancestors with a special flag bit.
*/
break;
}
}
}
/*
* Search upwards from winPtr2 until an ancestor of winPtr1 is
* found or a top-level window is reached.
*/
count2 = 0;
ancestorPtr = NULL;
break;
}
count2++;
break;
}
}
}
/*
* Search upwards from winPtr1 again, clearing the flag bits and
* remembering how many levels up we had to go.
*/
count1 = 0;
} else {
count1 = -1;
if (winPtr == ancestorPtr) {
count1 = i;
}
if (count1 == -1) {
count1 = i+1;
}
break;
}
}
}
return ancestorPtr;
}
/*
*----------------------------------------------------------------------
*
* TkPositionInTree --
*
* Compute where the given window is relative to a particular
* subtree of the window hierarchy.
*
* Results:
*
* Returns TK_GRAB_IN_TREE if the window is contained in the
* subtree. Returns TK_GRAB_ANCESTOR if the window is an
* ancestor of the subtree, in the same toplevel. Otherwise
* it returns TK_GRAB_EXCLUDED.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
int
{
return TK_GRAB_ANCESTOR;
}
break;
}
}
return TK_GRAB_EXCLUDED;
}
}
return TK_GRAB_IN_TREE;
}
/*
*----------------------------------------------------------------------
*
* TkGrabState --
*
* Given a window, this procedure returns a value that indicates
* the grab state of the application relative to the window.
*
* Results:
* The return value is one of three things:
* TK_GRAB_NONE - no grab is in effect.
* TK_GRAB_IN_TREE - there is a grab in effect, and winPtr
* is in the grabbed subtree.
* TK_GRAB_ANCESTOR - there is a grab in effect; winPtr is
* an ancestor of the grabbed window, in
* the same toplevel.
* TK_GRAB_EXCLUDED - there is a grab in effect; winPtr is
* outside the tree of the grab and is not
* an ancestor of the grabbed window in the
* same toplevel.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
int
* needed. */
{
if (grabWinPtr == NULL) {
return TK_GRAB_NONE;
}
return TK_GRAB_NONE;
}
}