Window Object

Window call reference

Unless your PySimpleGUI program is limited to popups, then it will have a Window object if you're showing a window. Like the Elements, there are a lot of parameters that can be used when creating a Window, and like the Elements, they're almost all optional. The only required parameter is the window's title.

This section touches on some of the more important Window parameters and features but is by no means exhausting.

Typical Use Cases

Usually you will create a layout, then a window object that uses the layout. From here there are 3 choices. Your window can be used:

1. As a one-shot window
2. As a persistent window
3. One among several windows running simultaneously

One-shot and persistent windows were discussed in the Getting Started - Windowing APIs section at the beginning of this document. Both of these types of windows use the Window method Window.read.

If you are running several windows simultaneously, then the best way to do this is using the read_all_windows call. If can be done in a more manual, polling manner, by reading each window using the timeout parameter, but this is an inefficient method.

Default Values

Some of the default settings for windows can be changed on a global basis. This enables you to have application-wide defaults and saves you from having to specify the same option in every Window you create.

The set_options function call is what you'll use to change these default values.

Modal Windows (only applied to tkinter port currently)

By default windows are not modal. Popups are modal by default.

When a window is modal it means if there are other windows already open, you must close the modal window in order to interact with the other windows.

The reason popup windows have modal set to True by default is so that if your window opens a popup, then the user will not become confused and try to interact with your original window while the popup is open.

Give It a Try

The best way for you to see the difference is to interact with a pair of popup windows.

Popular Options

These are a few of the more popular options that can be set when creating the window.

Window Size

Do not explicitly set the size of your window when creating it unless you have a special reason to do so. It's best to allow PySimpleGUI to determine the size for you.

If you hard-code a size, then you risk that size not being large enough on some else's machine. Maybe the window looks great at 400 x 300 pixels on your machine, but on another person's computer, running a different operating system, that size cuts off all of the buttons along the bottom of your window.

Setting an absolute size also means having to possibly change it every time you make a change to your window. If you want extra room than your layout is generating, then add elements to your layout, add padding to elements, or add to your window's margins. There are many ways to manipulate the size of your window without setting an absolute size.

Window Location

Location options include:

• Default (None, None) - Window is centered on primary display
• Any (x,y) location you would like - set location parameter to (x,y) tuple
• The default location determined by the OS - set location parameter to None
• Relative location - specify an offset from the location the window would normally be placed using the relative_location parameter

By default, PySimpleGUI computes the exact center of your window and centers the window on the screen. You can use the set_options function to set the default location for all windows created including popups.

Multiple Monitors and Linux

The auto-centering (default) location for your PySimpleGUI window may not be correct if you have multiple monitors on a Linux system. On Windows multiple monitors appear to work ok as the primary monitor the tkinter utilizes and reports on.

Linux users with multiple monitors that have a problem when running with the default location will need to specify the location the window should be placed when creating the window by setting the location parameter.

Element Default Settings

Some parameter set defaults for the elements within the window. element_padding is an example of one of these parameters. If an element doesn't have a padding parameter set explicitly, then this value will be the default used.

Right click menus are another example of one of these element settings. Set the right click menu for the window and each element within the window will have that same right click menu.

No Titlebar

This setting is unusual and incredibly useful. Not only do you get an interesting looking window, but the side effect of having no entry on your taskbar means your program "runs in the background".

Here's a good example of a window with no titlebar.

You'll find many examples of them in the Demo Programs. They begin with the words "Demo_Desktop_Widget" because they resemble windows used by programs like "Rainmeter".

Should you wish to create cool looking windows that are clean with no windows titlebar, use the no_titlebar option when creating the window.

Be sure an provide your user an "exit" button, a right click menu with an exit option or some other means to exit the program. On Windows, the keys Alt+F4 will kill one of these windows if you're desperate.

If you want to be able to move these windows you can set the grab_anywhere parameter to True.

It's easy to lose these windows since they don't appear on your taskbar. It's easy to accidentally move another window in front of your window with no titlebar.

NOTE: This option has caused some problems depending on the operating system and version of tkinter. For example, combining keep_on_top with grab_anywhere had some difficulties working correctly on some Raspberry Pi systems.

Grab Anywhere

This is a feature unique to PySimpleGUI.

Setting grab_anywhere to True means you can move the window by "grabbing" onto any element (clicking on, holding down the mouse and dragging).

Control+Left Button = Grab Anywhere

If you use the control key with your mouse, then it's the same as enabling Grab Anywhere. Holding control while clicking and dragging will move any PySimpleGUI window. This is very handy should your titlebar be accidentally moved out of view.

Always on top

To keep a window on top of all other windows on the screen, set keep_on_top to True.

This feature has occasionally had some problems on some operating systems and specific versions of tkinter.

Focus

PySimpleGUI will set a default focus location for you. This generally means the first input field. You can set the focus to a particular element. If you are going to set the focus yourself, then you should turn off the automatic focus by setting use_default_focus=False in your Window call.

Closing Windows

When you are completely done with a window, you should close so that the tkinter resources, are properly cleaned up.

If you wish to do this in 1 line of code, here's your line:

If you are using threads in your application, then deleting the window object is also recommended. del window will delete your window.

If you want your window to close after a single read call, you can set the close parameter to True when calling window.read(). This is demonstrated in the one-shot window design pattern.

Actually Creating The Window

Creating a Window object, by default, does not build your window using the GUI framework. Your window is not built and displayed until you do one of these:

• Call window.read()
• Finalize your window

To finalize your window, set the finalize parameter to True when creating the Window object.

IMPORTANT - If you want to modify any of the elements prior to calling window.read then you will need to finalize it.

An example of when you may want to perform an operation prior to reading the window is if you want to call the bind method for any elements or for the window itself.

Reading Windows

Once your Window is created, then you'll want to eventually "read" the window. You can learn how to do this in Reading Windows section.