Skip to content

Call Reference

On this page, you will find a list of all the functions and methods that are available in the library and details about them.

Window(title, width, height, font)

1.0.2 - The window object.

Parameter Latest Change Type Required Default Value Description
title 1.0.2 string This will be the window title.
width 1.0.2 integer 800 This will be the width of the window.
height 1.0.2 integer 600 This will be the height of the window.
font 1.0.2 file path (string) Roboto The font the window should use.
theme 1.2.0 light, dark or auto auto The theme of the window.
Example 
1
2
3
import pygui

window = pygui.Window("Hello World", width=800, height=600, font="./Arial.ttf")

Window.start()

1.0.2 - Start the window. This will make the window visible and wait for the user to close it. This will return when the user closes the window.

Example 

1
2
3
4
5
import pygui

window = pygui.Window("Hello World")

window.start()
Example Image

Window.frame(title, width, height)

1.0.2 - Add a frame to the window.

Parameter Latest Change Type Required Default Value Description
title 1.0.2 string This will be the frame's title.
width 1.0.2 integer Minimum Possible This will be the frame's width.
height 1.0.2 integer Minimum Possible This will be the frame's height.
position 1.5.0 tuple of ints 0, 0 This will be the position of the frame.
Example 

1
2
3
4
5
6
7
8
9
import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    pass

window.start()
Example Image

Tip

Although width and height are not required, they are recommended to be set. If they are not set, the frame will be as small as possible. Which will make it difficult to interact with the frame. A good way to find good widths and heights is to resize the frame to your liking. Then you can go into the imgui.ini file and see the width and height of the frame.

Window.menu(category, title, keys)

1.0.2 - Add a menu button to the top of the window.

Parameter Latest Change Type Required Default Value Description
category 1.0.2 string The button category to put this button under. If the category does not exist it will be added to the top bar of the screen.
title 1.0.2 string The button to be added to the category.
keys 1.0.2 string The keys that will be used to activate the button. Look below for usable keys.

Usable key names are:

  • Ctrl
  • Shift
  • Alt
  • Any key name from A to Z
  • Any key name from 0 to 9
Example 

1
2
3
4
5
6
7
8
9
import pygui

window = pygui.Window("Hello World")

@window.menu("File", "Quit", keys=["Ctrl", "Q"])
def quit_program():
    exit(0)

window.start()
Example Image

Elements(state)

1.0.2 - The elements object.

Warning

This should not be used directly. When passing a function into the frame decorator, the function passed will get the elements object as the first argument.

Elements.text(text, text_color, center, wrap_text)

1.0.2 - Add text to the frame.

Parameter Latest Change Type Required Default Value Description
text 1.0.2 string This will be the text to be added.
text_color 1.2.0 HEX (int like 0xFF0000), RGB or RGBA (tuple like (255, 0, 0, 1)) None (auto) The color of the text.
center 1.0.2 boolean False Wether or not the text should be centered.
wrap_text 1.0.2 boolean True Wether or not the text should be wrapped.
font_size 1.3.0 float or integer 48 The font size of the text.

Warning

Center and wrap cannot be used together (yet). If both are enabled the text will not be centered.

Warning

Font size uses the imgui.set_window_font_scale function to scale. This means that with big font sizes, the text will be a bit blurry.

Example

Let's add some text to the frame.

1
2
3
4
5
6
7
8
9
import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    elements.text("Hello World!")

window.start()
Example

Elements.button(text, text_color, wrap_text)

1.0.2 - Add a button to the frame.

Parameter Latest Change Type Required Default Value Description
text 1.0.2 string This will be the text on the button.
text_color 1.2.0 HEX (int like 0xFF0000), RGB or RGBA (tuple like (255, 0, 0, 1)) None (auto) The color of the text.
wrap_text 1.0.2 boolean True Wether or not the text should be wrapped

Returns a decorator. The function passed into the decorator will get called when the button is clicked.

Example

Let's add a button to the frame.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    @elements.button("Hello World!")
    def hello_world_button():
        print("Hello World!")

window.start()
Example Image

When you click the button Hello World! will be printed!

Elements.button_event(key, time_limit, delay)

1.1.0 - Add an element to the frame for time_limit seconds after a button is clicked.

Parameter Latest Change Type Required Default Value Description
key 1.1.0 string The button's key.
time_limit 1.1.0 seconds (integer) 10 The amount of time the elements should be rendered after the button is pressed.
delay 1.4.0 seconds (integer) 0 Make this function only get called after delay number of seconds.

Returns a decorator. The function passed into the decorator will get called constantly for time_limit seconds, after delay seconds.

Example

Let's make a button that will terminate the program after 3 seconds.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    @elements.button("Terminate the program", key="terminate")
    def terminate():
        pass

    @elements.button_event("terminate", time_limit=1, delay=0)
    def terminate_event():
        elements.text("The program will terminate in 3 seconds!")

    @elements.button_event("terminate", time_limit=1, delay=1)
    def terminate_event_two():
        elements.text("The program will terminate in 2 seconds!")

    @elements.button_event("terminate", time_limit=1, delay=2)
    def terminate_event_three():
        elements.text("The program will terminate in 1 second!")

    @elements.button_event("terminate", time_limit=1, delay=3)
    def terminate_event_exit():
        exit(0)

window.start()

When you click the button Hello World! will be added to the frame for the next 10 seconds!

Warning

Operations like opening files should never be done in the button_event function. This should be done in the button function.

Elements.checkbox(label, default_value, key)

1.0.2 - Add a checkbox to the frame.

Parameter Latest Change Type Required Default Value Description
label 1.0.2 string This text will appear after the checkbox.
default_value 1.0.2 boolean If the checkbox should be checked by default.
key 1.0.2 string or None None What the value will be saved under in the state.

Returns whether or not the checkbox is checked.

Example

Let's add a checkbox to the frame.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    checked = elements.checkbox("Check Me", True)
    elements.text(f"Current State: {checked}")

window.start()
Example Image

Elements.color_picker(label, default_value, alpha, key)

1.0.2 - Add a color picker to the frame.

Parameter Latest Change Type Required Default Value Description
label 1.0.2 string This text will appear after the color picker.
default_value 1.0.2 HEX (int like 0xFF0000), RGB or RGBA (tuple like (255, 0, 0, 1)) The default color of the color picker.
alpha 1.0.2 boolean False If a color is allowed to have an alpha value.
key 1.0.2 string or None None What the value will be saved under in the state.

Returns the color selected as an RGB or RGBA tuple.

Example

Let's add a color picker to the frame.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    color = elements.color_picker("Pick a color", 0x008080)
    elements.text(f"You picked: {color}", text_color=color)

window.start()
Image Example

Elements.combo(label, default_value, choices, key, wrap_text)

1.3.0 - Add a combo box to the frame.

Parameter Latest Change Type Required Default Value Description
label 1.3.0 string This text will appear after the combo.
default_value 1.3.0 index (integer) The default value of the combo. Should be an index of the choices.
choices 1.3.0 list of strings The choices that should be displayed.
key 1.3.0 string or None None What the value will be saved under in the state.
wrap_text 1.3.0 boolean True Wether or not the text should be wrapped.

Returns the index of the selected choice.

Example

Let's add a combo box to the frame.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import pygui

window = pygui.Window("Hello World", width=1600, height=1200)

@window.frame("Hello World", width=1400, height=900)
def hello_world(elements: pygui.Elements):
    choices = ["Option 1", "Option 2", "Option 3"]
    selected = elements.combo("Select an option", 0, choices)
    elements.text(f"You selected: {choices[selected]}")

window.start()
Example Image

Elements.input_int(label, default_value, minimum, maximum, key, wrap_text)

1.0.2 - Add an input to the frame that only accepts integers.

Parameter Latest Change Type Required Default Value Description
label 1.0.2 string This text will appear after the input.
default_value 1.0.2 integer 0 The default value of the input.
minimum 1.0.2 integer negative infinity The minimum value of the input.
maximum 1.0.2 integer positive infinity The maximum value of the input.
key 1.0.2 string or None None What the value will be saved under in the state.
wrap_text 1.0.2 boolean True Wether or not the text should be wrapped.
Example

Let's add an input to the frame.

import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    value = elements.input_int("What is your favorite number?", 7)
    elements.text(f"You picked: {value}")

window.start()
Example Image

Elements.input_float(label, default_value, minimum, maximum, key, wrap_text)

1.6.0 - Add an input to the frame that only accepts floats.

Parameter Latest Change Type Required Default Value Description
label 1.6.0 string This text will appear after the input.
default_value 1.6.0 float 0 The default value of the input.
minimum 1.6.0 float negative infinity The minimum value of the input.
maximum 1.6.0 float positive infinity The maximum value of the input.
key 1.6.0 string or None None What the value will be saved under in the state.
wrap_text 1.6.0 boolean True Wether or not the text should be wrapped.
Example

Let's add an input to the frame.

import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    value = elements.input_float("3.5 + 4", 7.5)
    elements.text(f"You picked: {value}")

window.start()
Example Image

Elements.input_text(label, default_value, key, wrap_text, max_length)

1.0.2 - Add an input to the frame.

Parameter Latest Change Type Required Default Value Description
label 1.0.2 string This text will appear after the input.
default_value 1.0.2 string empty string The default value of the input.
key 1.0.2 string or None None What the value will be saved under in the state.
wrap_text 1.0.2 boolean True Wether or not the text should be wrapped.
max_length 1.0.2 integer 255 The maximum amount of characters that can be in the input.
Example

Let's add an input to the frame.

import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    value = elements.input_text("Enter text", "Hello World!")
    elements.text(f"You picked: {value}")

window.start()
Example Image

Elements.state

1.0.2 - This element stores the values of some objects.

  • You can use the state for getting the value of objects before their definition.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    elements.text(f"You picked: {elements.state.get("favorite")}")
    value = elements.input_int("What is your favorite number?", 7, key="favorite")

window.start()
  • You can use the state for setting an object's state.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import pygui

window = pygui.Window("Hello World")

@window.frame("Hello World", width=700, height=450)
def hello_world(elements: pygui.Elements):
    value = elements.input_int("What is your favorite number?", 7, key="favorite")
    @elements.button("Add 2")
    def add_2():
        elements.state["favorite"] += 2

window.start()