File indexing completed on 2024-04-14 03:57:01

0001 /*
0002     SPDX-FileCopyrightText: 2001 Ellis Whitehead <ellis@kde.org>
0003 
0004     Win32 port:
0005     SPDX-FileCopyrightText: 2004 Jarosław Staniek <staniek@kde.org>
0006 
0007     SPDX-License-Identifier: LGPL-2.1-or-later
0008 */
0009 
0010 #ifndef _KKEYSERVER_H
0011 #define _KKEYSERVER_H
0012 
0013 #include <kwindowsystem_export.h>
0014 
0015 #include <X11/Xlib.h>
0016 #include <fixx11h.h>
0017 #include <qglobal.h>
0018 #include <xcb/xcb.h>
0019 
0020 class QString;
0021 
0022 /**
0023  * A collection of functions for the conversion of key presses and
0024  * their modifiers from the window system specific format
0025  * to the generic format and vice-versa.
0026  */
0027 namespace KKeyServer
0028 {
0029 /**
0030  * Converts the mask of ORed KKey::ModFlag modifiers to a
0031  * user-readable string.
0032  * @param mod the mask of ORed KKey::ModFlag modifiers
0033  * @return the user-readable string (in English)
0034  */
0035 KWINDOWSYSTEM_EXPORT QString modToStringUser(uint mod);
0036 
0037 /**
0038  * Converts the modifier given as user-readable string (in English)
0039  * to KKey::ModFlag modifier, or 0.
0040  * @internal
0041  */
0042 KWINDOWSYSTEM_EXPORT uint stringUserToMod(const QString &mod);
0043 
0044 /**
0045  * Test if the shift modifier should be recorded for a given key.
0046  *
0047  * For example, if shift+5 produces '%' Qt wants ctrl+shift+5 recorded as ctrl+% and
0048  * in that case this function would return false.
0049  *
0050  * @since 4.7.1
0051  */
0052 KWINDOWSYSTEM_EXPORT bool isShiftAsModifierAllowed(int keyQt);
0053 
0054 static const int MODE_SWITCH = 0x2000;
0055 
0056 /**
0057  * Initialises the values to return for the mod*() functions below.
0058  * Called automatically by those functions if not already initialized.
0059  */
0060 KWINDOWSYSTEM_EXPORT bool initializeMods();
0061 
0062 /**
0063  * Returns true if the current keyboard layout supports the Meta key.
0064  * Specifically, whether the Super or Meta keys are assigned to an X modifier.
0065  * @return true if the keyboard has a Meta key
0066  * @see modXMeta()
0067  */
0068 KWINDOWSYSTEM_EXPORT bool keyboardHasMetaKey();
0069 
0070 /**
0071  * Returns the X11 Shift modifier mask/flag.
0072  * @return the X11 Shift modifier mask/flag.
0073  * @see accelModMaskX()
0074  */
0075 KWINDOWSYSTEM_EXPORT uint modXShift();
0076 
0077 /**
0078  * Returns the X11 Lock modifier mask/flag.
0079  * @return the X11 Lock modifier mask/flag.
0080  * @see accelModMaskX()
0081  */
0082 KWINDOWSYSTEM_EXPORT uint modXLock();
0083 
0084 /**
0085  * Returns the X11 Ctrl modifier mask/flag.
0086  * @return the X11 Ctrl modifier mask/flag.
0087  * @see accelModMaskX()
0088  */
0089 KWINDOWSYSTEM_EXPORT uint modXCtrl();
0090 
0091 /**
0092  * Returns the X11 Alt (Mod1) modifier mask/flag.
0093  * @return the X11 Alt (Mod1) modifier mask/flag.
0094  * @see accelModMaskX()
0095  */
0096 KWINDOWSYSTEM_EXPORT uint modXAlt();
0097 
0098 /**
0099  * Returns the X11 Win (Mod3) modifier mask/flag.
0100  * @return the X11 Win (Mod3) modifier mask/flag.
0101  * @see keyboardHasWinKey()
0102  * @see accelModMaskX()
0103  */
0104 KWINDOWSYSTEM_EXPORT uint modXMeta();
0105 
0106 /**
0107  * Returns the X11 NumLock modifier mask/flag.
0108  * @return the X11 NumLock modifier mask/flag.
0109  * @see accelModMaskX()
0110  */
0111 KWINDOWSYSTEM_EXPORT uint modXNumLock();
0112 
0113 /**
0114  * Returns the X11 ScrollLock modifier mask/flag.
0115  * @return the X11 ScrollLock modifier mask/flag.
0116  * @see accelModMaskX()
0117  */
0118 KWINDOWSYSTEM_EXPORT uint modXScrollLock();
0119 
0120 /**
0121  * Returns the X11 Mode_switch modifier mask/flag.
0122  * @return the X11 Mode_switch modifier mask/flag.
0123  * @see accelModMaskX()
0124  */
0125 KWINDOWSYSTEM_EXPORT uint modXModeSwitch();
0126 
0127 /**
0128  * Returns bitwise OR'ed mask containing Shift, Ctrl, Alt, and
0129  * Win (if available).
0130  * @see modXShift()
0131  * @see modXLock()
0132  * @see modXCtrl()
0133  * @see modXAlt()
0134  * @see modXNumLock()
0135  * @see modXWin()
0136  * @see modXScrollLock()
0137  */
0138 KWINDOWSYSTEM_EXPORT uint accelModMaskX();
0139 
0140 #if KWINDOWSYSTEM_BUILD_DEPRECATED_SINCE(6, 0)
0141 /**
0142  * Extracts the symbol from the given Qt key and
0143  * converts it to an X11 symbol + modifiers.
0144  * @param keyQt the qt key code
0145  * @param sym if successful, the symbol will be written here
0146  * @return true if successful, false otherwise
0147  *
0148  * @deprecated Since 6.0, Use keyQtToSymXs(keyQt)
0149  */
0150 KWINDOWSYSTEM_EXPORT
0151 KWINDOWSYSTEM_DEPRECATED_VERSION(6, 0, "Use keyQtToSymXs(int keyQt)")
0152 bool keyQtToSymX(int keyQt, int *sym);
0153 #endif
0154 
0155 /**
0156  * Extracts the symbols from the given Qt key and
0157  * converts it to an X11 symbol + modifiers.
0158  * @param keyQt the qt key code
0159  * @return the symbols; emtpy if unsuccessful
0160  */
0161 KWINDOWSYSTEM_EXPORT QList<int> keyQtToSymXs(int keyQt);
0162 
0163 #if KWINDOWSYSTEM_BUILD_DEPRECATED_SINCE(6, 0)
0164 /**
0165  * Extracts the code from the given Qt key.
0166  * @param keyQt the qt key code
0167  * @param keyCode if successful, the symbol will be written here
0168  * @return true if successful, false otherwise
0169  *
0170  * @deprecated Since 6.0, Use keyQtToCodeXs(keyQt)
0171  */
0172 KWINDOWSYSTEM_EXPORT
0173 KWINDOWSYSTEM_DEPRECATED_VERSION(6, 0, "Use keyQtToCodeXs(int keyQt)")
0174 bool keyQtToCodeX(int keyQt, int *keyCode);
0175 #endif
0176 
0177 /**
0178  * Extracts the codes from the given Qt key.
0179  * @param keyQt the qt key code
0180  * @param return the codes; empty if unsuccessful
0181  */
0182 KWINDOWSYSTEM_EXPORT QList<int> keyQtToCodeXs(int keyQt);
0183 
0184 /**
0185  * Extracts the modifiers from the given Qt key and
0186  * converts them in a mask of X11 modifiers.
0187  * @param keyQt the qt key code
0188  * @param mod if successful, the modifiers will be written here
0189  * @return true if successful, false otherwise
0190  */
0191 KWINDOWSYSTEM_EXPORT bool keyQtToModX(int keyQt, uint *mod);
0192 
0193 /**
0194  * Converts the given symbol and modifier combination to a Qt key code.
0195  * @param keySym the X key symbol
0196  * @param modX the mask of X11 modifiers
0197  * @param keyQt if successful, the qt key code will be written here
0198  * @return true if successful, false otherwise
0199  */
0200 KWINDOWSYSTEM_EXPORT bool symXModXToKeyQt(uint32_t keySym, uint16_t modX, int *keyQt);
0201 
0202 /**
0203  * Converts the mask of ORed X11 modifiers to
0204  * a mask of ORed Qt key code modifiers.
0205  * @param modX the mask of X11 modifiers
0206  * @param modQt the mask of Qt key code modifiers will be written here
0207  *        if successful
0208  * @return true if successful, false otherwise
0209  */
0210 KWINDOWSYSTEM_EXPORT bool modXToQt(uint modX, int *modQt);
0211 
0212 /**
0213  * Converts an X keypress event into a Qt key + modifier code
0214  * @param e the X11 keypress event
0215  * @param keyModQt the Qt keycode and mask of Qt key code modifiers will be written here
0216  *        if successful
0217  * @return true if successful, false otherwise
0218  */
0219 KWINDOWSYSTEM_EXPORT bool xEventToQt(XEvent *e, int *keyModQt);
0220 
0221 /**
0222  * Converts an XCB keypress event into a Qt key + modifier code
0223  * @param e the XCB keypress event
0224  * @param keyModQt the Qt keycode and mask of Qt key code modifiers will be written here
0225  *        if successful
0226  * @return true if successful, false otherwise
0227  */
0228 KWINDOWSYSTEM_EXPORT bool xcbKeyPressEventToQt(xcb_generic_event_t *e, int *keyModQt);
0229 /**
0230  * Overloaded method for convenience.
0231  */
0232 KWINDOWSYSTEM_EXPORT bool xcbKeyPressEventToQt(xcb_key_press_event_t *e, int *keyModQt);
0233 
0234 }; // namespace KKeyServer
0235 
0236 #endif // !_KKEYSERVER_H