Locating & Changing Elements
In your event loop, you'll likely want to work with the elements contained in the window. Maybe you want to change the color of the text or get the metadata for an element. Changing an element is a 2 step process. First you need to locate the elements and then you can call the element's update or some other class method.
Look for this pattern in PySimpleGUI code to find where elements are being modified:
Locating Elements
Before you can change something about an element, you'll first need to locate it. To retrieve an element in the window:
Older versions used the method
FindElement
or the shortened version
Element
or even shorter (version 4.1+)
Elem
You'll find the pattern window.Element(key) in older code. All of code after about 4.0 uses the shortened window[key] notation.
If you want to locate an element in a way that will not show an error message if the element is not found, then you can use the Window.find_element call and set the parameter silent_on_error=True.
This will stop the error popup window from showing and will return the value None if no matching key is found.
Key Errors
In Python, specifying a bad key for a dictionary lookup results in KeyError being raised that likely results in your program crashing. As discussed previously if you are running a PySimpleGUI application that has no console, then exceptions that cause Python to exit result in your window disappearing with nothing else to help you understand what just happened.
Take this simple dictionary lookup as an example.
If running on a console, you would see an error that looks something like this:
Traceback (most recent call last):
File "C:/Users/mike/AppData/Roaming/JetBrains/PyCharm2020.2/scratches/scratch_679.py", line 15, in <module>
print(my_dictionary['c'])
KeyError: 'c'
While these error messages are sometimes difficult for beginners to understand, you have a starting point to help you debug. You're given the file and line number of the error at least.
PySimpleGUI tries to catch some errors and present them to you in a friendly way. You can learn more PySimpleGUI's displaying of errors in the section on Error Handling
Key Error Popup
When you've specified a key that doesn't match any of the keys in your window, you'll be shown a Key Error popup such as this one:
Key Guessing
The default action for key lookups is to try and guess the key you meant so that you can continue to run your program as you are debugging it. In the error message above, notice the line that says:
Closest match = -OUT-
You will find the key that was searched for in the line above this line and in the example shown, the key being searched for was -OU T-. The error is there's an extra space in the key.
The closest match means a key was found that may be the key you meant and PySimpleGUI will continue executing with the assumption you meant that key. Closing the error popup will cause your program to continue running with the element having the "Closest match" being returned to your code.
If no match is found, then the popup error message will have the match information line:
Closest match = None
Error Element
If no element with a matching key is found and the key guess algorithm fails to find a close match, then PySimpleGUI needs to give you something as a return value. The logical choice for an error condition would be to return the value None. The problem with returning None is that you are likely to attempt to use this value as if it were an element. Most of the time an element lookup is performed so that you can call the element's update method.
If you try to call an update method on a value of None, then your program will crash with an error:
Since you've already been warned via the popup message that you've got a bad key, it's safe to attempt to allow your program to run further with the assumption that you'll go back and fix your misspelled key. So that you can continue to execute your code, you will be returned an ErrorElement.
An ErrorElement is a dummy element that is a real element, based on the Element class. It has an update method. If you attempt to call ErrorElement.update, then an error message is displayed on stdout warning you that you're trying to use an ErrorElement.
update - Element Class Method
One of the ways PySimpleGUI simplifies working with elements is that modifying an element is usually done through a single method named update. The idea is that you'll be able to easily find where elements are being modified and you'll be able to easily find what can be changed in an element.
There are class methods in addition to the element's update method that can change an element, but the update call is the primary way to make changes to an element.
Finalize or Read Required
Before you can call an element's update method, one of two things must happen. You must either call window.read or set the parameter finalize=True when you create the window. You may find old PySimpleGUI programs that call the Window.finalize method. This is the same as setting the finalize parameter to True when you create the window.
The reason for this requirement is that PySimpleGUI does not build the window using the GUI framework until you call Window.read for the first time or you set the parameter finalize=True. Without a window being created, it's not possible to modify it.
Each Element's update Is Different
The parameters used for Text.update are different than Radio.update. You will want to check the element's update parameters in the SDK call reference, or use the docstrings along with your IDE to see the parameters.
Code Completion Help
If you break apart the lookup from the call to update, then you can get your IDE to help you with parameters. Here's how to add code completion to your code by breaking apart the operation. Your typical update call, as mentioned earlier, looks like this:
You can break apart this statement into these 2 line of code:
The magic that makes it all work is the "type comment" that is on the line of code that does the element lookup. This comment tells the IDE that the variable elem will contain a sg.Text object. After the lookup line of code, anytime you use the variable elem in your IDE, the code completion provided will be as if this variable had a Text object.
In PyCharm, typing elem. and then typing Control + Space, you'll be shown this code completion dialog:
Notice that the choices are limited to objects of type Element or type Text.
If I type the word update, then I am shown the documentation for the Text.update call in the PyCharm user interface. This is the same information that is shown in the SDK call reference in the documentation.
SDK API Call Reference In PySimpleGUI
You can use the built-in SDK call reference utility to see the documentation for all of the elements' class methods, including the update method. There are numerous ways to open this utility including:
- Opening the Home Window and clicking the "SDK Reference" button
- Calling
sg.main_sdk_help() - Typing
sdkhelpfrom the command line.
Here is the documentation for the Text.update method as shown in this utility.
get Class Method
It's normal in many GUI libraries to call a "get" type of function to retrieve the value for a widget. While many of the elements have a get method, you normally will not need to call it in order to get the current value for elements that are "input-style" elements.
When you call window.read, the values dictionary has the value that each of these elements. Use the values dictionary instead of calling the get method. If you have a function that changes the value of an element such that the value will no longer match the values dictionary, then this is an example of when calling the get method to ensure you have the absolute latest value makes sense.