From 373c3b707cea33b1eabb9e1d417d9003a2e8a051 Mon Sep 17 00:00:00 2001 From: culler Date: Tue, 28 Apr 2020 14:41:46 +0000 Subject: More comment edits. Add a new test command which can by used to inject key NSEvents directly into the macOS event queue. --- macosx/tkMacOSXKeyboard.c | 107 ++++++++++++++++++++++------------------------ macosx/tkMacOSXTest.c | 99 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 149 insertions(+), 57 deletions(-) diff --git a/macosx/tkMacOSXKeyboard.c b/macosx/tkMacOSXKeyboard.c index 4dbf692..6430484 100644 --- a/macosx/tkMacOSXKeyboard.c +++ b/macosx/tkMacOSXKeyboard.c @@ -6,6 +6,7 @@ * Copyright (c) 1995-1997 Sun Microsystems, Inc. * Copyright 2001-2009, Apple Inc. * Copyright (c) 2005-2009 Daniel A. Steffen + * Copyright (c) 2020 Marc Culler * * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -347,8 +348,9 @@ KeyDataToUnicode( * XKeycodeToKeysym -- * * This is a stub function which translates from the keycode used in an - * XEvent to a numerical keysym. On macOS, the display input variable is - * ignored and only the virtual keycode in bits 24-31 is used. + * XEvent to a numerical keysym. On macOS, the display parameter is + * ignored and only the the virtual keycode stored in bits 24-31 is + * used. * * Results: * Returns the corresponding numerical keysym, or NoSymbol if the keysym @@ -408,11 +410,11 @@ XKeycodeToKeysym( * * TkpGetString -- * - * Retrieve the string stored in the transchars field of an XEvent - * and convert it to a DString. + * This is a stub function which retrieves the string stored in the + * transchars field of an XEvent and converts it to a Tcl_DString. * * Results: - * Returns the DString. + * Returns a pointer to the string value of the DString. * * Side effects: * None. @@ -441,10 +443,11 @@ TkpGetString( * * XGetModifierMapping -- * - * Fetch the current keycodes used as modifiers. + * X11 stub function to get the keycodes used as modifiers. This + * is never called by the macOS port. * * Results: - * Returns a new modifier map. + * Returns a newly allocated modifier map. * * Side effects: * Allocates a new modifier map data structure. @@ -458,13 +461,6 @@ XGetModifierMapping( { XModifierKeymap *modmap; - (void) display; /*unused*/ - - /* - * MacOS doesn't use the key codes for the modifiers for anything, and we - * don't generate them either. So there is no modifier map. - */ - modmap = ckalloc(sizeof(XModifierKeymap)); modmap->max_keypermod = 0; modmap->modifiermap = NULL; @@ -476,7 +472,8 @@ XGetModifierMapping( * * XFreeModifiermap -- * - * Deallocate a modifier map that was created by XGetModifierMapping. + * Deallocates a modifier map that was created by XGetModifierMapping. + * This is also never called by the macOS port. * * Results: * None. @@ -503,9 +500,10 @@ XFreeModifiermap( * * XKeysymToString, XStringToKeysym -- * - * These X window functions map keysyms to strings & strings to keysyms. - * They are never called because we define REDO_KEYSYM_LOOKUP, which - * instructs tkBind to do the conversion for us. + * These X11 stub functions map keysyms to strings & strings to keysyms. + * A platform can do its own conversion by defining these and undefining + * REDO_KEYSYM_LOOKUP. The macOS port defines REDO_KEYSYM_LOOKUP so these + * are never called and Tk does the conversion for us. * * Results: * None. @@ -535,15 +533,16 @@ XStringToKeysym( * * XKeysymToKeycode -- * - * This is a stub function which onverts a numerical keysym to the keycode - * which should be used as the in a KeyPress or KeyRelease XEvent for the - * corresponding key. + * This is a stub function which converts a numerical keysym to the + * platform-specific keycode used in a KeyPress or KeyRelease XEvent. The + * implementation calls a static function which also provides information + * about the modifier state, needed by TkpSetKeycodeAndState. * * Results: * - * An X11 KeyCode with a unicode character in the low 16 bits and the - * 8-bit "virtual keycode" in the highest byte. See the description of - * keycodes on the Macintosh at the top of this file. + * On macOS, a KeyCode with a unicode character in the lowest 16 bits and + * the 8-bit "virtual keycode" in the highest byte. See the description + * of keycodes on the Macintosh at the top of this file. * * Side effects: * None. @@ -612,8 +611,8 @@ XKeysymToKeycode( * * Modifies the XEvent. Sets the xkey.keycode to a keycode value formatted * by XKeysymToKeycode and sets the shift and option flags in xkey.state - * to the values implied by the keysym. Also fills in xkey.trans_chars, so - * that the actual characters can be retrieved later. + * to the values implied by the keysym. Also fills in xkey.trans_chars for + * printable events. * *---------------------------------------------------------------------- */ @@ -650,16 +649,17 @@ TkpSetKeycodeAndState( * * TkpGetKeySym -- * - * This is a stub function called in tkBind.c. Given an X KeyPress or - * KeyRelease event, map the keycode in the event to a keysym. + * This is a stub function called in tkBind.c. Given a KeyPress or + * KeyRelease XEvent, it maps the keycode in the event to a numerical + * keysym. * * Results: * The return value is the keysym corresponding to eventPtr, or NoSymbol * if no matching keysym could be found. * * Side effects: - * In the first call for a given display, keycode-to-keysym maps get - * loaded. + * In the first call for a given display, calls TkpInitKeymapInfo. + * * *---------------------------------------------------------------------- */ @@ -714,17 +714,15 @@ TkpGetKeySym( /* * Figure out which of the four slots in the keymap vector to use for this * key. Refer to Xlib documentation for more info on how this computation - * works. (Note: We use "Option" in keymap columns 2 and 3 where other - * implementations have "Mode_switch".) + * works. */ index = 0; if (eventPtr->xkey.state & Mod2Mask) { /* Option */ index |= 2; } - if ((eventPtr->xkey.state & ShiftMask) - || (/* (dispPtr->lockUsage != LU_IGNORE) - && */ (eventPtr->xkey.state & LockMask))) { + if ((eventPtr->xkey.state & ShiftMask) || /* Shift or caps lock. */ + (eventPtr->xkey.state & LockMask)) { index |= 1; } @@ -767,15 +765,14 @@ TkpGetKeySym( * * TkpInitKeymapInfo -- * - * This procedure is invoked to scan keymap information to recompute stuff - * that's important for binding, such as the modifier key (if any) that - * corresponds to the "Mode_switch" keysym. + * This procedure initializes fields in the display that pertain + * to modifier keys. * * Results: * None. * * Side effects: - * Keymap-related information in dispPtr is updated. + * Modifier key information in dispPtr is initialized. * *-------------------------------------------------------------- */ @@ -788,34 +785,32 @@ TkpInitKeymapInfo( dispPtr->bindInfoStale = 0; /* - * Behaviors that are variable on X11 are defined constant on MacOSX. - * lockUsage is only used above in TkpGetKeySym(), nowhere else currently. + * On macOS the caps lock key is always interpreted to mean that alphabetic + * keys become uppercase but other keys do not get shifted. (X11 allows + * a configuration option which makes the caps lock equivalent to holding + * down the shift key.) * There is no offical "Mode_switch" key. */ dispPtr->lockUsage = LU_CAPS; + + /* This field is no longer used by tkBind.c */ + dispPtr->modeModMask = 0; -#if 0 - /* - * With this, and become synonyms for and