The Windowing APIs - Custom Windows

The final part of the Windowing APIs is the one that's used to make "Custom Windows"... A "Custom Window" is just that, a window that is customized to be exactly as you want it to be. You can use any combination of Elements arranged in any configuration.

These are the heart of the PySimpleGUI library. The elements are objects that you'll use to create your window and can also use them to add to your window at runtime. Code that's utilizing these API calls is easy to identify by looking for the creation of a Window object.

The majority of the PySimpleGUI documentation, Demo Programs, and educational materials are focused on this topic of creating your application using the elements and Window object.

The One-Shot and Persistent Window Design Patterns

For applications that have only 1 window active at a time, there are 2 basic design patterns:

1. One-Shot Window - The window is displayed, one event is read, and the window is closed
2. Persistent Window - The window stays open, persists, until the user takes some action to close the window or exit your application

The difference in the design patterns - Persistent Windows have an "Event Loop" . One-Shot Windows don't use an event loop while Persistent Windows do.

One-Shot Window (Long Format)

Both One-Shot examples shown create this window

This code is the more descriptive and lengthy way writing a One-Shot Windows. Notice these parts of the program:

• PySimpleGUI is imported
• A layout is created
• A Window is created
• window.read() is called
• The window is closed

import PySimpleGUI as sg

layout = [[sg.Text('This is our one-shot window')],
          [sg.Button('Ok')]]

window = sg.Window('Title', layout)

event, values = window.read()

window.close()

One-Shot Window (Compact Format)

Through the magic of Python's chaining feature and an additional close parameter, the same One-Show Window can be written in 2 lines of code, one of which is the import. Don't blink.

import PySimpleGUI as sg

event, values = sg.Window('Title', [[sg.Text('This is our 1-line window')], [sg.Button('Ok')]]).read(close=True)

Persistent Window

The Persistent Window is likely the Window you'll be developing as most applications are designed for the user to interact with them over an extended period of time versus the short, single-event, One-Shot window.

Window Closed Event

Always check for a Window Closed event immediately following your window.read() call. If event == sg.WIN_CLOSED then assume the values variable will have a value that's not usable. It may be None or some other value. Don't try to use the values variable until you've checked to see if the event variable is not sg.WIN_CLOSED. You also can't use the event variable until this check.

import PySimpleGUI as sg

layout = [[sg.Text('This is our persistent window')],
          [sg.Button('1'), sg.Button('2'), sg.Button('Exit')]]

window = sg.Window('Title', layout)

while True:         # The Event Looop
    event, values = window.read()
    if event == sg.WIN_CLOSED or event == 'Exit':
        break

    if event == '1':
        sg.popup('You clicked 1')
    elif event == '2':
        sg.popup('You clicked 2')

window.close()

Try It For Yourself

Here's a One-Shot Window to try out

And this is a Persistent Window

One Window or More Than One

You're not limited to a single window running at one time using PySimpleGUI. You can easily have numerous windows executing in parallel, cooperating to produce a sophisticated application if that's your goal.

The simple architecture and syntax of PySimpleGUI doesn't change when going from 1 to 2 windows. Instead of reading events from a single window, you read events from all active windows.

Try It For Yourself