The Elements
Recall from the "Getting Started" section that a "layout" defines the contents of your Window and a layout is a list of lists of Elements. This section describes each of the Elements that you'll find in the tkinter port.
These are the 34 Elements you can use to build your window's layout.
You will find detailed parameter information on Elements located in the Call Reference Tab of the documentation.
"Elements" are the building blocks used to create windows. Some GUI APIs use the term "Widget" to describe these user interface building blocks. In PySimpleGUI the term Element is used so that it's clear when a PySimpleGUI Element is being referenced versus an underlying GUI Framework's Widget.
PySimpleGUI Elements are implemented using to a GUI Framework Widget, usually in a 1-to-1 manner. For example, a Text Element is implemented in tkinter using a Label Widget.
Sometimes Elements are created by combining PySimpleGUI Elements. For example, the Titlebar and MenubarCustom are Elements that are implemented by PySimpleGUI by using other elements.
KEYS - Very Important...
There is one specific concept of elements that is critical you understand when reading this description and chat concept is keys.They've been described earlier in the documentation and you'll find a complete description of keys in this section:
For now, you should understand that an Element can have a key, a unique identifier for that specific Element. A key can be an int, a string, a tuple, ...., but not a list. Any "hashable" value is allowed. They are often strings, and the PySimpleGUI coding conventions suggests string keys use the format '-KEY-'. Tuples are a very useful datatype to use for keys as well so spend some time studying this concept!
Table of Elements in Tkinter Port
Each port of PySimpleGUI has a core set of Elements as well as port-specific elements. Some port-specific elements include the Dial element in the Qt port, and the Pane element in the tkinter port.
| Element Name | Aliases | tkinter Widget | Description |
|---|---|---|---|
| Text | T, Txt | tk.Label | One or more lines of Text |
| Input | I, In, InputText | tk.Entry | Single line text input |
| Combo | DD, Drop, DropDown, InputCombo | ttk.Combobox | A "Dropdown" list that can be edited too |
| OptionMenu | InputOptionMenu | tk.OptionMenu | Like a Combo |
| Multiline | ML, MLine | tk.Text or tk.scrolledtext.ScrolledText | Multiple lines of text for input or output |
| Output | tk.Text (sorta) | Not suggested. Multiline is better choice. Re-routes stdout | |
| Radio | R, Rad | tk.Radiobutton | Radio Buttons - choose 1 from several |
| Checkbox | CB, CBox, Check | tk.Checkbutton | Checkbox - binary choice Yes/No |
| Spin | Sp | tk.Spinbox | Choose 1 by using arrows. Can manually enter also |
| Button | B, Btn | tk.Button or ttk.Button | Button - plain or with image |
| Image | Im | tk.Label | A PNG or GIF image |
| Canvas | tk.Canvas | A drawing area. Graph may be batter to use | |
| Column | Col | Combination Canvas & Frame | Embeds layouts inside layouts |
| Frame | Fr | tk.LabelFrame | A frame with a title and a border |
| Tab | tk.Frame | Container used with TabGroup | |
| TabGroup | ttk.Notebook | Holds Tabs in layouts | |
| Pane | tk.PanedWindow | Sliding columns (it's kinda weird but useful) | |
| Graph | G | tk.Canvas | A drawing area with primitives |
| Slider | Sl | tk.Scale | Slider to choose from range of choices |
| Listbox | LB, LBox | tk.Listbox | Listbox - a list of choices |
| Menu | MenuBar, Menubar | tk.Menu | A standard Menubar |
| MenubarCustom | Combined Elements | Custom colors and font for menubar | |
| ButtonMenu | BM, BMenu | tk.Menubutton | Button that shows a menu |
| Titlebar | Combined Elements | Custom colors for a titlebar | |
| ProgressBar | PBar, Prog, Progress | ttk.Progressbar | |
| Table | ttk.Treeview | A table with clickible cells and headers | |
| Tree | ttk.Treeview | A tree with collapsible sections | |
| VerticalSeparator | VSep, VSeparator | ttk.Separator | Vertical line |
| HorizontalSeparator | HSep, HSeparator | ttk.Separator | Horizontal line |
| StatusBar | SBar | tk.Label | Statusbar for bottom of window |
| Sizegrip | SGrip | ttk.Sizegrip | A grip for the bottom right corner of a window |
| Push | P, Stretch | PySimpleGUI Elements | Pushes elements horizontally |
| VPush | VP, VStretch | PySimpleGUI Elements | Pushes rows vertically |
| Sizer | Column Element | Creates a Width x Height number of pixels for padding/sizing |
The "All Elements" Demo Program
The Window shown above was created using this code that is a Demo Program named Demo_Program_All_Elements_Simple.py:
import PySimpleGUI as sg
"""
Demo - Element List
All elements shown in 1 window as simply as possible.
Copyright 2022 PySimpleGUI
"""
use_custom_titlebar = True if sg.running_trinket() else False
def make_window(theme=None):
NAME_SIZE = 23
def name(name):
dots = NAME_SIZE-len(name)-2
return sg.Text(name + ' ' + '•'*dots, size=(NAME_SIZE,1), justification='r',pad=(0,0), font='Courier 10')
sg.theme(theme)
# NOTE that we're using our own LOCAL Menu element. It can be the standard Menubar or the PySimpleGUI MenubarCustom
if use_custom_titlebar:
Menu = sg.MenubarCustom
else:
Menu = sg.Menu
treedata = sg.TreeData()
treedata.Insert("", '_A_', 'Tree Item 1', [1234], )
treedata.Insert("", '_B_', 'B', [])
treedata.Insert("_A_", '_A1_', 'Sub Item 1', ['can', 'be', 'anything'], )
layout_l = [[name('Text'), sg.Text('Text')],
[name('Input'), sg.Input(s=15)],
[name('Multiline'), sg.Multiline(s=(15,2))],
[name('Output'), sg.Output(s=(15,2))],
[name('Combo'), sg.Combo(sg.theme_list(), default_value=sg.theme(), s=(15,22), enable_events=True, readonly=True, k='-COMBO-')],
[name('OptionMenu'), sg.OptionMenu(['OptionMenu',],s=(15,2))],
[name('Checkbox'), sg.Checkbox('Checkbox')],
[name('Radio'), sg.Radio('Radio', 1)],
[name('Spin'), sg.Spin(['Spin',], s=(15,2))],
[name('Button'), sg.Button('Button')],
[name('ButtonMenu'), sg.ButtonMenu('ButtonMenu', sg.MENU_RIGHT_CLICK_EDITME_EXIT)],
[name('Slider'), sg.Slider((0,10), orientation='h', s=(10,15))],
[name('Listbox'), sg.Listbox(['Listbox', 'Listbox 2'], no_scrollbar=True, s=(15,2))],
[name('Image'), sg.Image(sg.EMOJI_BASE64_HAPPY_THUMBS_UP)],
[name('Graph'), sg.Graph((125, 50), (0,0), (125,50), k='-GRAPH-')] ]
layout_r = [[name('Canvas'), sg.Canvas(background_color=sg.theme_button_color()[1], size=(125,40))],
[name('ProgressBar'), sg.ProgressBar(100, orientation='h', s=(10,20), k='-PBAR-')],
[name('Table'), sg.Table([[1,2,3], [4,5,6]], ['Col 1','Col 2','Col 3'], num_rows=2)],
[name('Tree'), sg.Tree(treedata, ['Heading',], num_rows=3)],
[name('Horizontal Separator'), sg.HSep()],
[name('Vertical Separator'), sg.VSep()],
[name('Frame'), sg.Frame('Frame', [[sg.T(s=15)]])],
[name('Column'), sg.Column([[sg.T(s=15)]])],
[name('Tab, TabGroup'), sg.TabGroup([[sg.Tab('Tab1',[[sg.T(s=(15,2))]]), sg.Tab('Tab2', [[]])]])],
[name('Pane'), sg.Pane([sg.Col([[sg.T('Pane 1')]]), sg.Col([[sg.T('Pane 2')]])])],
[name('Push'), sg.Push(), sg.T('Pushed over')],
[name('VPush'), sg.VPush()],
[name('Sizer'), sg.Sizer(1,1)],
[name('StatusBar'), sg.StatusBar('StatusBar')],
[name('Sizegrip'), sg.Sizegrip()] ]
# Note - LOCAL Menu element is used (see about for how that's defined)
layout = [[Menu([['File', ['Exit']], ['Edit', ['Edit Me', ]]], k='-CUST MENUBAR-',p=0)],
[sg.T('PySimpleGUI Elements - Use Combo to Change Themes', font='_ 14', justification='c', expand_x=True)],
[sg.Checkbox('Use Custom Titlebar & Menubar', use_custom_titlebar, enable_events=True, k='-USE CUSTOM TITLEBAR-', p=0)],
[sg.Col(layout_l, p=0), sg.Col(layout_r, p=0)]]
window = sg.Window('The PySimpleGUI Element List', layout, finalize=True, right_click_menu=sg.MENU_RIGHT_CLICK_EDITME_VER_EXIT, keep_on_top=True, use_custom_titlebar=use_custom_titlebar)
window['-PBAR-'].update(30) # Show 30% complete on ProgressBar
window['-GRAPH-'].draw_image(data=sg.EMOJI_BASE64_HAPPY_JOY, location=(0,50)) # Draw something in the Graph Element
return window
window = make_window()
while True:
event, values = window.read()
if event == sg.WIN_CLOSED or event == 'Exit':
break
if values['-COMBO-'] != sg.theme():
sg.theme(values['-COMBO-'])
window.close()
window = make_window()
if event == '-USE CUSTOM TITLEBAR-':
use_custom_titlebar = values['-USE CUSTOM TITLEBAR-']
sg.set_options(use_custom_titlebar=use_custom_titlebar)
window.close()
window = make_window()
if event == 'Edit Me':
sg.execute_editor(__file__)
elif event == 'Version':
sg.popup_scrolled(__file__, sg.get_versions(), location=window.current_location(), keep_on_top=True, non_blocking=True)
window.close()
The code is provided here so that you can see that only 73 lines of code are required to show all 34 elements in 1 window. Normally only 1 line of code is required to show an element in your window, but this code includes logic that allows you to see the standard titlebar and menubar as well as the PySimpleGUI custom titlebar and custom menubar.
You can preview all of the PySimpleGUI Themes with this program to see how each element will appear using a particular theme. For example, this window uses the "Dark Gray 15" theme and is using a custom titlebar and a custom menubar.
Try It For Yourself
This Trinket uses the latest release of PySimpleGUI with the same basic code above.
Pseudo-Elements
Some of the Elements are implemented using a function that returns an element, often a a Column element. Some examples are TitleBar, MenubarCustom, and Push. Because these are not created using Python classes they can be possibly confusing if you are using an IDE with code completion and are looking for a class rather than a function.. All of the "Browse" buttons are Pseudo-elements. For example, BrowseFile is a function that returns a Button object.
You'll also find the term "User Defined Elements" throughout all PySimpleGUI materials including the Demo Programs. This term means the same thing. It's a function that returns one or more elements.
Container Elements
Container elements are how you embed layouts within a window. A container element "contains" rows of elements just like a Window does. Container elements include:
- Column
- Frame
- Tab
These elements can be used to expand a window's contents after the window is created and perform operations on groups of elements. See the layout section for more information on dynamic layouts.