Web Analytics Made Easy - Statcounter
Skip to content

Common Parameters

Some parameters that you will see on almost all Element creation calls include:

  • key - Used with window[key], events, and in return value dictionary
  • tooltip - Hover your mouse over the element and you'll get a popup with this text
  • size - (width, height) - Usually measured in characters-wide, rows-high. Sometimes they mean pixels
  • font - Specifies the font family, size, etc.
  • colors - Color name or #RRGGBB string
  • pad - Amount of padding to put around element
  • enable_events - Turns on the element specific events
  • visible - Make elements appear and disappear
  • right_click_menu - Menu shown when the element is clicked with right mouse button
  • metadata - Data of any format you would like to save with the element
  • image - Some elements allow an image to be specified
  • expand_x and expand_y - Allows an element to expand to fill space and resize with a window that resizes
  • setting - Indicates this Element should have the initial value loaded from a setting file. Will also save to the settings file.

Aliases

Three of the most common parameters are key, size, and pad. In order shorten the number of characters in your layouts, you can use the single-letter alias k for key, s for size and p for pad.

For example, k='-ML-' is the same as key='-ML-'.

Tooltip

Tooltips are text boxes that popup next to an element if you hold your mouse over the top of it. If you want to be extra kind to your window's user, then you can create tooltips for them by setting the parameter tooltip to some text string. You will need to supply your own line breaks / text wrapping. If you don't want to manually add them, then take a look at the standard library package textwrap.

Tooltips are one of those "polish" items that really dress-up a GUI and show's a level of sophistication. Go ahead, impress people, throw some tooltips into your GUI. You can change the color of the background of the tooltip on the tkinter version of PySimpleGUI by setting TOOLTIP_BACKGROUND_COLOR to the color string of your choice. The default value for the color is:

TOOLTIP_BACKGROUND_COLOR = "#ffffe0"

Size

Info on setting default element sizes is discussed in the Window section.

Specifies the amount of room reserved for the Element. For elements that are character based, such a Text, it is (# characters, # rows). Sometimes it is a pixel measurement such as the Image element. And sometimes a mix like on the Slider element (characters long by pixels wide).

Some elements, Text and Button, have an auto-size setting that is on by default. It will size the element based on the contents. The result is that buttons and text fields will be the size of the string creating them. You can turn it off. For example, for Buttons, the effect will be that all buttons will be the same size in that window.

Specifying Size as an INT

Beginning in version 4.47.0 you can specify a single int as the size. This will set the size to be a single row in height (1). Writing size=10 is now the same as writing size=(10,1). A tuple is created on your behalf when you specify a size and an int. This will save a considerable amount of typing, especially for the elements where you typically have only 1 row or can only have 1 row.

Element Sizes - Non-tkinter Ports (Qt, WxPython, Web)

In non-tkinter ports you can set the specific element sizes in 2 ways. One is to use the normal size parameter like you're used to using. This will be in characters and rows.

The other way is to use a new parameter, size_px. This parameter allows you to specify the size directly in pixels. A setting of size_px=(300,200) will create an Element that is 300 x 200 pixels.

Additionally, you can also indicate pixels using the size parameter, if the size exceeds the threshold for conversion. What does that mean? It means if your width is > 20 (DEFAULT_PIXEL_TO_CHARS_CUTOFF), then it is assumed you're talking pixels, not characters. However, some of the "normally large" Elements have a cutoff value of 100. These include, for example, the Multline and Output elements.

If you're curious about the math used to do the character to pixels conversion, it's quite crude, but functional. The conversion is completed with the help of this variable:

DEFAULT_PIXELS_TO_CHARS_SCALING = (10,26)

The conversion simply takes your size[0] and multiplies by 10 and your size[1] and multiplies it by 26.

Colors

A string representing color. Anytime colors are involved, you can specify the tkinter color name such as 'lightblue' or an RGB hex value '#RRGGBB'. For buttons, the color parameter is a tuple (text color, background color)

Anytime colors are written as a tuple in PySimpleGUI, the way to figure out which color is the background is to replace the "," with the word "on". ('white', 'red') specifies a button that is "white on red". Works anywhere there's a color tuple.

Dual-Color Strings - One String with Two Colors

In the 2021 and later versions of the tkinter port, you can use a single string in some places where two colors are needed. In these situations, the two colors represent a foreground color and a background color. You can replace the tuple with a single string. The format of the string uses the word "on" as a separator of the two colors.

For example, if you want to represent a color combination that has yellow as the foreground color and blue as the background color, then the two-color string would be "yellow on blue"

The most common use for these strings is to represent button colors. They can also be used when calling any of the element "print" methods, cprint, or using the debug output's Print call.

Each of the colors can be either a hex color string with the format #RRGGBB or a named color like red or blue.

Pad

The amount of room around the element in pixels. The default value is (5,3) which means leave 5 pixels on each side of the x-axis and 3 pixels on each side of the y-axis. You can change this on a global basis using a call to SetOptions, or on an element basis.

If you want more pixels on one side than the other, then you can split the number into 2 number. If you want 200 pixels on the left side, and 3 pixels on the right, the pad would be ((200,3), 3). In this example, only the x-axis is split.

Specifying pad as an INT

Starting in version 4.47.0, it's possible to set pad to be an int rather than a tuple. If an int is specified, then the pad is set to a tuple with each position being the same as the int. This reduces the code in your layout significantly if you use values such as (0,0) for your pad. This is not an uncommon value. Now you can write pad=0 and you will get the same result as if you typed pad=(0,0)

Font

Specifies the font family, size, and style. Font families on Windows include: * Arial * Courier * Comic, * Fixedsys * Times * Verdana * Helvetica (the default I think)

The fonts will vary from system to system, however, Tk 8.0 automatically maps Courier, Helvetica and Times to their corresponding native family names on all platforms. Also, font families cannot cause a font specification to fail on Tk 8.0 and greater.

If you wish to leave the font family set to the default, you can put anything not a font name as the family. The PySimpleGUI Demo programs and documentation use the family 'Any' and sometimes '_' to demonstrate the default font.. You could use "default" if that's more clear to you.

There are 2 formats that can be used to specify a font... a string, and a tuple Tuple - (family, size, styles) String - "Family Size Styles"

To specify an underlined, Helvetica font with a size of 15 the values: ('Helvetica', 15, 'underline italics') 'Helvetica 15 underline italics'

Font Style - Valid font styles include:

  • italic
  • roman
  • bold
  • normal
  • underline
  • overstrike

An example with many styles is:

font='Courier 12 italic bold underline overstrike'

The same styles can be used with the tuple format for fonts.

Font Family List

The tkinter port has a class method Text.fonts_installed_list() that returns a sorted list of the font families you can use on your system.

Key

See the section keys that has full information about keys. Keys are one of the most fundamental and important aspects of PySimpleGUI.

Visible

To create an invisible Element, place the element in the layout like you normally would and add the parameter

visible=False.

Later when you want to make that Element visible you simply call the Element's Update method and pass in the parameter visible=True

This feature works best on Qt, but does work on the tkinter version as well. The visible parameter can also be used with the Column and Frame "container" Elements.

Note - Tkinter elements behave differently than Qt elements in how they arrange themselves when going from invisible to visible. Elements that go from visible to invisible to visible again will move to the end of the container they are in unless you "pin" them in place.

The way to deal with the potential movement of elements to use the layout helper function pin to "pin" the element to a particular location in a layout. You will need to use pin if you want your window to shrink when elements become invisible.

Qt elements tend to hold their place really well and the window resizes itself nicely. It is more precise and less clunky.

expand_x expand_y

expand_x if set to True will allow the element to expand to fill the available space in the X-direction. If the window is resized, the element will also resize in the X-direction.

expand_y if set to True will allow the element to expand to fill the available space in the Y-direction. If the window is resized, the element will also resize in the Y-direction.

Metadata

Metadata can be anything you wish to save in your element. You can specify a value when creating the element. Access and change it by using the element's metadata property. For example - window['-KEY-'].metadata

Right-click-menu

Right click menus can be added to individual elements as well as to the Window as a whole. If an element does not a right click menu set, then it will use the Window's right click menu. Setting the parameter to the value MENU_RIGHT_CLICK_DISABLED will disable the right click menu on that element. See the section on Menus for more information.

Images

Some elements have parameters that specify images. Usually there are 2 parameters you can use. One indicates a filename and the other a binary or Base64 encoded PNG/GIF. For more information see the section on Images
.

setting

The setting parameter is used to indicate the element's initial value is located in the User Settings file that's associated with this program. If no setting is found, then the value of this parameter is used as the initial value. The loading of the value happens automatically.

Saving the value is accomplished by calling Window.settings_save. See the section on User Settings for more information.