Return to ch12d.t CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / new / X / doc / Xlib

Annotation of 43BSDTahoe/new/X/doc/Xlib/ch12d.t, revision 1.1

1.1     ! root        1: .NH 2
        !             2: Keyboard Operations
        !             3: .PP
        !             4: X does not predefine the keyboard to be ascii characters.
        !             5: It is often useful to know that the ``a'' key just went down,
        !             6: or possibly that it just went back up.
        !             7: Client programs are sent keyboard events,
        !             8: which contain a ``keycode''
        !             9: which assigns a number to each physical key on the
        !            10: keyboard.
        !            11: (For historical reasons, the keycodes are a superset of the DEC LK201 keyboard
        !            12: keycodes.)
        !            13: Client programs which want to deal with
        !            14: ascii text will then have to convert the keycode into ascii
        !            15: explicitly.
        !            16: The transformation of keycode to ascii is arbitrary,
        !            17: and facilities are provided to aid people in customizing the keyboard
        !            18: layout to whatever they want.
        !            19: Remember that keyboards often differ dramatically,
        !            20: so writing code that presumes the existance of a particular key
        !            21: not on the main part of the keyboard is fraught with portability
        !            22: problems.
        !            23: It may also be difficult to get key up events on certain X implementations
        !            24: due to hardware or software restrictions.
        !            25: .PP
        !            26: Keyboard events are normally sent to the smallest enclosing window
        !            27: which is interested in that type of event underneath the
        !            28: mouse's position.
        !            29: It is also possible to assign the keyboard `input focus' to a specific
        !            30: window.
        !            31: When the input focus is attached to a window,
        !            32: keyboard events will go to  the client which has selected
        !            33: input on that window rather than the window under the mouse.
        !            34: .PP
        !            35: WARNING:
        !            36: Some implementations cannot support up events.
        !            37: You should think seriously before designing software that takes
        !            38: advantage of up events if you are concerned about wide portability,
        !            39: though there are some applications that can exploit up events
        !            40: to provide superior user interfaces.
        !            41: You should also be VERY careful when selecting which keys may be used
        !            42: in such applications.
        !            43: It may be impossible
        !            44: to guarantee the existance of a set of keys on all keyboard with the probable
        !            45: exception of a-z, spacebar, and carriage return.
        !            46: .FD
        !            47: .IN "XFocusKeyboard"
        !            48: .IN "Definitions" "XFocusKeyboard"
        !            49: XFocusKeyboard (w)
        !            50:        Window w;
        !            51: .FN
        !            52: .IN "Input Focus"
        !            53: \fIXFocusKeyboard\fP designates a window as the `input focus' window.  If
        !            54: the window that would normally receive a \fIKeyPressed\fP or \fIKeyReleased\fP
        !            55: event is not the focus window or one of its descendents, the event will
        !            56: be sent to the focus window instead.  
        !            57: The events will go to whatever
        !            58: client has selected input on the focus window;  in general, this may be
        !            59: .IN "XFocusKeyboard"
        !            60: a client other than the one which has called \fIXFocusKeyboard\fP.  For
        !            61: instance, a window manager may allow the user to designate an arbitrary
        !            62: window as the keyboard focus.
        !            63: .LP
        !            64: The root window is the default focus window.
        !            65: If the focus window is
        !            66: closed, the closest existing ancestor inherits the input focus.
        !            67: .FD
        !            68: .IN "Definitions" "XLookupMapping"
        !            69: .IN "XLookupMapping"
        !            70: .IN "Keycode to Ascii Conversion"
        !            71: .IN "Keyboard" "Customization"
        !            72: char *XLookupMapping(event, nbytes)
        !            73:        XKeyPressedEvent *event;
        !            74:        int *nbytes;
        !            75: .FN
        !            76: .PP
        !            77: This function is very useful for mapping down events to counted
        !            78: character strings (an array of characters and the length; the null
        !            79: character is legitimate in this use.)
        !            80: It returns a pointer to a static counted character string which must not be
        !            81: touched by a client, and the number of bytes in the string.
        !            82: .PP
        !            83: This mapping is normally stored in the user's home directory in the
        !            84: .IN "File" "$HOME/.Xkeymap"
        !            85: .IN "File" "/usr/lib/Xkeymap.txt"
        !            86: file ".Xkeymap".
        !            87: If this file is not present, \fIXLookupMapping\fP
        !            88: falls back to a built in table.
        !            89: If no text is defined for that key, \fInbytes\fP will be zero.
        !            90: The \fI~/.Xkeymap\fP file is produced by the \fIkeycomp(1)\fP program, 
        !            91: which reads
        !            92: a text file of keyboard mappings.  The file \fI/usr/lib/Xkeymap.txt\fP contains
        !            93: a set of standard keyboard mappings.
        !            94: The function performs normal interpretation of `shift' bits (meta, shift,
        !            95: shift lock, control).
        !            96: The user should strncpy the result if needed to his own storage if the
        !            97: data must be modified.
        !            98: .IN "XUseKeymap"
        !            99: If a different keymap file is desired, it may be set using
        !           100: \fIXUseKeymap\fP.
        !           101: 
        !           102: .FD
        !           103: .IN "Definitions" "XRebindCode"
        !           104: .IN "XRebindCode"
        !           105: .IN "Keyboard" "Customization"
        !           106: XRebindCode(keycode, shiftbits, str, nbytes)
        !           107:        unsigned int keycode;
        !           108:        unsigned int shiftbits;
        !           109:        char *str;
        !           110:        int nbytes;
        !           111: .FN
        !           112: .PP
        !           113: If you wish to rebind the keyboard, you can use this routine to change
        !           114: (on a non-permanent basis) the binding of the keyboard.
        !           115: Given a keycode,
        !           116: the meta bits (or the \fIX*Masks\fP together to specify the bits
        !           117: you wish to set), a string and the number of bytes in the string,
        !           118: .IN "XLookupMapping"
        !           119: subsequent calls to \fIXLookupMapping\fP will return the supplied string.
        !           120: The string should be stored in static storage;
        !           121: an automatic string may have been deallocated by the time it is needed.
        !           122: .FD
        !           123: .IN "Definitions" "XUseKeymap"
        !           124: .IN "XUseKeymap"
        !           125: .IN "Keyboard" "Customization"
        !           126: Status XUseKeymap(keymap_file);
        !           127:        char *keymap_file;
        !           128: .FN
        !           129: .PP
        !           130: If you wish to use an alternate keymap file, you can use this
        !           131: routine to change the file used.  Like XRebindKey, this only affects
        !           132: the keymap within the current process.
        !           133: 
        !           134: The procedure returns a zero value if it fails (if it could not find
        !           135: the keymap file named by \fIkeymap_file\fP, or if the file contains a
        !           136: bad magic number), and a non-zero value if it succeeds.  If it fails,
        !           137: the existing keymap is untouched.
        !           138: 
        !           139: 
        !           140: 
        !           141: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.