Keys
Keys are a VERY important concept to understand in PySimpleGUI.
If you are going to do anything beyond the basic stuff with your GUI, then you need to understand keys.
You can think of a "key" as a "name" for an element. Or an "identifier". It's a way for you to identify and talk about an element with the PySimpleGUI library. It's the exact same kind of key as a dictionary key. They must be unique to a window.
Keys are specified when the Element is created using the key parameter.
Keys are used in these ways:
* Specified when creating the element
* Returned as events. If an element causes an event, its key will be used
* In the values dictionary that is returned from window.read()
* To make updates (changes), to an element that's in the window
After you put a key in an element's definition, the values returned from window.read will use that key to tell you the value. For example, if you have an input element in your layout:
Input(key='mykey')
And your read looks like this: event, values = window.read()
Then to get the input value from the read it would be: values['mykey']
You also use the same key if you want to call update on an element. Please see the section updating Elements to understand that usage. To get find an element object given the element's key, you can call the window method find_element (also written FindElement, element), or you can use the more common lookup mechanism:
Tuples and Other Data Types as Keys
While you'll often see keys written as strings in examples in this document, know that keys can be ANYTHING (that's hash-able... a is not, a tuple is).
Let's say you have a window with a grid of input elements. You could use their row and column location as a key (a tuple)
key=(row, col)
Then when you read the values variable that's returned to you from calling Window.read(), the key in the values variable will be whatever you used to create the element. In this case you would read the values as:
values[(row, col)]
An Example - Function As a Key
One interesting design pattern you can use is to set a key to point to a function. Then in your event loop, if you find an event is "callable", call that function. This emulates a more traditional GUI framework.
In this example code, we've set one of the Button elements to have a key that's a function. In the event loop, the statement if callable(event): determines if this event is a function or exapression that can be called. If so, then the code calls the function - event().
import PySimpleGUI as sg
def a_callback_function():
print(f'In callback function')
layout = [ [sg.Output(s=(60,10))],
[sg.Button('Button 1'), sg.Button('Button2', key=a_callback_function), sg.Button('Exit')] ]
window = sg.Window('Function as Key', layout)
while True:
event, values = window.read()
print(event, values)
if event == sg.WIN_CLOSED or event == 'Exit':
break
if callable(event):
event()
window.close()
The result is that when Button 2 is clicked, then the callback function that was used as the key is called.
The "-KEY-" Key Coding Convention
Most of the time they are simple text strings. In the Demo Programs, keys are written with this convention:
"-KEY NAME-" (You don't have to follow the convention, but it's not a bad one to follow as other users are used to seeing this format and it's easy to spot when element keys are being used).
The idea is that scanning down a page of code, a string in "ALL CAPS" with a dash on each end "-STRING-" is going to really stand out, which will be your cue that you're looking at an element's key. You could think of it like PEP8 in a way. If you see WhatIsThis... PEP8 says it's a class. And what_is_this... it'll be a variable or a function.
If you have an element object, to find its key, access the property .key for the element. This assumes you've got the element in a variable already.
Default Keys
If you fail to place a key on an Element, then one will be created for you automatically.
For Buttons, the text on the button is that button's key. Text elements will default to the text's string (for when events are enabled and the text is clicked)
If the element is one of the input elements (one that will cause an generate an entry in the return values dictionary) and you fail to specify one, then a number will be assigned to it beginning with the number 0. The effect will be as if the values are represented as a list even if a dictionary is used.
Menu Keys
Menu items can have keys associated with them as well. See the section on Menus for more information about these special keys. They aren't the same as Element keys. Like all elements, Menu Element have one of these Element keys. The individual menu item keys are different.
WRITE_ONLY_KEY Modifier
Sometimes you have input elements (e.g. Multiline) that you are using as an output. The contents of these elements may get very long. You don't need to "read" these elements and doing so will potentially needlessly return a lot of data.
To tell PySimpleGUI that you do not want an element to return a value when Window.read is called, add the string WRITE_ONLY_KEY to your key name.
If your Multiline element was defined like this originally:
Then to turn off return values for that element, the Multiline element would be written like this: