[Enhancement] Missing documentation of keyboard events

Type of Issues (Enhancement, Error, Bug, Question)

Documentation

Operating System

Win10-64 update 2004

Python version

3.8.7 (tags/v3.8.7:6503f05, Dec 21 2020, 17:59:51) [MSC v.1928 64 bit (AMD64)]

PySimpleGUI Port and Version

4.33.0 Released 02-Jan-2021
Ports = tkinter, Qt, WxPython, Web
tkinter
PySimpleGUI Version:
4.33.0 Released 02-Jan-2021
tkinter version:
8.6.9

Your Experience Levels In Months or Years

6 months Python programming experience
50+ years Programming experience overall
No Have used another Python GUI Framework (tkinter, Qt, etc) previously (yes/no is fine)?

You have completed these steps:

• [ x ] Read instructions on how to file an Issue
• [ x ] Searched through main docs http://www.PySimpleGUI.org for your problem
• [ x ] Searched through the readme for your specific port if not PySimpleGUI (Qt, WX, Remi)
• [ x ] Looked for Demo Programs that are similar to your goal http://www.PySimpleGUI.com
• [ x ] Note that there are also Demo Programs under each port on GitHub
• [ x ] Run your program outside of your debugger (from a command line)
• [ x ] Searched through Issues (open and closed) to see if already reported
• [ No ] Try again by upgrading your PySimpleGUI.py file to use the current one on GitHub. Your problem may have already been fixed but is not yet on PyPI.

Description of Problem / Question / Details

For the window() function "return_keyboard_events" parameter, the API documentation does not mention that a second window.read() is required to actually get the keyboard event. By experimentation, the first window.read() returns event = string name of key field of element being read and current string value of that element (after rstrip() of value), second window.read() returns event string of keyname:keynumber with the same value.

Format of returned keyboard event string on second read is not described, nor is the relationship between the keyname and the keynumber. Review of the tkinter key names and values on the web does not make the name/number relationship obvious.

These urls show some tkinter keyname:keynumber values, but neither seems to match what is observed from PySimpleGUI results on Win10.

https://anzeljg.github.io/rin2/book2/2405/docs/tkinter/key-names.html
http://www.tcl.tk/man/tcl8.4/TkCmd/keysyms.htm

For example, for PySimpleGUI pressing the Home key returns event="Home:36" but the first url above says that the keycode for Home is 97. The second url above does not list keycode values, only keysym_num values which agree with the first url.

I assume the tkinter keycode values are probably different between OS's, but a new API page listing them all would be helpful (or maybe better a sample python program to generate them all for the interested user).

Code To Duplicate

import PySimpleGUI as sg

def main():
    layout = [  [sg.Multiline("Application messages come here\n", size=(60, 5), key="msgout")],
                [sg.Multiline("Commands come from here", size=(60, 1), enable_events=True, key='cmdinp', focus=True)],
                [sg.Button('Exit')]  ]

    window = sg.Window('Application Title', layout, return_keyboard_events=True)
    window.finalize()
    window["cmdinp"].update("")
    rdcnt = 0
    while True:             # Event Loop
        event, values = window.read()
        rdcnt += 1
        if event is not None:
            if isinstance(event, str) and event == "cmdinp":
                logging.debug("read #{} event is cmdinp".format(rdcnt))
            logging.debug("read #{} returned {},{},'{}'".format(rdcnt,
                event, 
                "0x" + "".join("{:02x}".format(ord(c)) for c in event), 
                values["cmdinp"].rstrip()))
            window["msgout"].print(event, values["cmdinp"].rstrip())
        else:
            logging.debug("read #{} returned {},'{}'".format(rdcnt, event, values))
        print(event, values)
        if event == sg.WIN_CLOSED or event == 'Exit':
            break
    window.close()

import logging
logging.basicConfig(filename="testread.log", level=logging.DEBUG)
if __name__ == '__main__':
    main()

Start with the window() return_keyboard_events parameter and the window.read() behavior shown in the reproduction. Document that keyboard events may appear on a subsequent read, explain the keyname:keynumber format and platform considerations, and verify the wording against the provided tkinter references and sample program.