pygame_gui.windows package

Submodules

pygame_gui.windows.ui_colour_picker_dialog module

class pygame_gui.windows.ui_colour_picker_dialog.UIColourChannelEditor(relative_rect: Rect | FRect | Tuple[float, float, float, float], name: str, channel_index: int, value_range: Tuple[int, int], initial_value: int, manager: IUIManagerInterface | None = None, container: IContainerLikeInterface | None = None, parent_element: UIElement | None = None, object_id: ObjectID | str | None = None, anchors: Dict[str, str | UIElement] | None = None, visible: int = 1)

Bases: UIElement

This colour picker specific element lets us edit a single colour channel (Red, Green, Blue, Hue etc.). It's bundled along with the colour picker class because I don't see much use for it outside a colour picker, but it still seemed sensible to make a class for a pattern in the colour picker that is repeated six times.

Parameters:

relative_rect -- The relative rectangle for sizing and positioning the element, relative to the anchors.
name -- Name for this colour channel, (e.g 'R:' or 'B:'). Used for the label.
channel_index -- Index for the colour channel (e.g. red is 0, blue is 1, hue is also 0, saturation is 1)
value_range -- Range of values for this channel (0 to 255 for R,G,B - 0 to 360 for hue, 0 to 100 for the rest)
initial_value -- Starting value for this colour channel.
manager -- The UI manager for the UI system. If not provided or set to None, it will try to use the first UIManager that was created by your application.
container -- UI container for this element.
parent_element -- An element to parent this element, used for theming hierarchies and events.
object_id -- A specific theming/event ID for this element.
anchors -- A dictionary of anchors used for setting up what this element's relative_rect is relative to.
visible -- Whether the element is visible by default. Warning - container visibility may override this.

hide(): In addition to the base UIElement.hide() - call hide() of the element_container - which will propagate to the sub-elements - label, entry and slider.

process_event(event: Event) → bool

Handles events that this UI element is interested in. In this case we are responding to the slider being moved and the user finishing entering text in the text entry element.

Parameters:: event -- The pygame Event to process.
Returns:: True if event is consumed by this element and should not be passed on to other elements.

set_dimensions(dimensions: Vector2 | Tuple[float, float], clamp_to_container: bool = False)

Method to directly set the dimensions of an element.

Parameters:

dimensions -- The new dimensions to set.
clamp_to_container -- Whether we should clamp the dimensions to the dimensions of the container or not.

set_position(position: Vector2 | Tuple[float, float])

Sets the absolute screen position of this channel, updating all subordinate elements at the same time.

Parameters:: position -- The absolute screen position to set.

set_relative_position(position: Vector2 | Tuple[float, float])

Sets the relative screen position of this channel, updating all subordinate elements at the same time.

Parameters:: position -- The relative screen position to set.

set_value(new_value: int)

For when we need to set the value of the colour channel from outside, usually from adjusting the colour elsewhere in the colour picker. Makes sure the new value is within the allowed range.

Parameters:: new_value -- Value to set.

show(): In addition to the base UIElement.show() - call show() of the element_container - which will propagate to the sub-elements - label, entry and slider.

class pygame_gui.windows.ui_colour_picker_dialog.UIColourPickerDialog(rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, *, initial_colour: Color = Color(0, 0, 0, 255), window_title: str = 'pygame-gui.colour_picker_title_bar', object_id: ObjectID | str = ObjectID(object_id='#colour_picker_dialog', class_id=None), visible: int = 1, always_on_top: bool = False)

Bases: UIWindow

A colour picker window that gives us a small range of UI tools to pick a final colour.

Parameters:

rect -- The size and position of the colour picker window. Includes the size of shadow, border and title bar.
manager -- The manager for the whole of the UI. If not provided or set to None, it will try to use the first UIManager that was created by your application.
initial_colour -- The starting colour for the colour picker, defaults to black.
window_title -- The title for the window, defaults to 'Colour Picker'
object_id -- The object ID for the window, used for theming - defaults to '#colour_picker_dialog'
visible -- Whether the element is visible by default.

changed_hsv_update_rgb(): Updates the RGB channels when we've altered the HSV ones.

changed_rgb_update_hsv(): Updates the HSV channels when we've altered the RGB ones.

get_colour() → Color: Get the current colour :return:

process_event(event: Event) → bool

Handles events that this UI element is interested in. In this case we are responding to the colour channel elements being changed, the OK or Cancel buttons being pressed or the user clicking the mouse inside the Saturation & Value picking square.

Parameters:: event -- The pygame Event to process.
Returns:: True if event is consumed by this element and should not be passed on to other elements.

set_colour(colour: Color) → None: Set the current colour and update all the necessary elements :param colour: The colour to set :return: None

update_colour_2d_slider(): This is used to update the 2D slider from the sliders :return: None

update_current_colour_image(): Updates the 'current colour' image when the current colour has been changed.

update_saturation_value_square()

Updates the appearance of the big square that lets us visually pick the Saturation and Value of our current Hue. This is done by drawing a very small 4x4 pixel square with a pattern like so:

[black] [hue at max saturation & value] [black] [white]

And then using the smoothscale transform to enlarge it so that the colours blend smoothly from one to the other.

pygame_gui.windows.ui_confirmation_dialog module

class pygame_gui.windows.ui_confirmation_dialog.UIConfirmationDialog(rect: Rect | FRect | Tuple[float, float, float, float], action_long_desc: str, manager: IUIManagerInterface | None = None, *, window_title: str = 'pygame-gui.Confirm', action_short_name: str = 'pygame-gui.OK', blocking: bool = True, object_id: ObjectID | str = ObjectID(object_id='#confirmation_dialog', class_id=None), visible: int = 1, action_long_desc_text_kwargs: Dict[str, str] | None = None, always_on_top: bool = False)

Bases: UIWindow

A confirmation dialog that lets a user choose between continuing on a path they've chosen or cancelling. It's good practice to give a very brief description of the action they are confirming on the button they click to confirm it i.e. 'Delete' for a file deletion operation or, 'Rename' for a file rename operation.

Parameters:

rect -- The size and position of the window, includes the menu bar across the top.
action_long_desc -- Long-ish description of action. Can make use of HTML to style the text.
manager -- The UIManager that manages this UIElement. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_title -- The title of the window.
action_short_name -- Short, one or two-word description of action for button.
blocking -- Whether this window should block all other mouse interactions with the GUI until it is closed.
object_id -- A custom defined ID for fine-tuning of theming. Defaults to '#confirmation_dialog'.
visible -- Whether the element is visible by default.
action_long_desc_text_kwargs -- a dictionary of variable arguments to pass to the translated string useful when you have multiple translations that need variables inserted in the middle.

process_event(event: Event) → bool

Process any events relevant to the confirmation dialog.

We close the window when the cancel button is pressed, and post a confirmation event (UI_CONFIRMATION_DIALOG_CONFIRMED) when the OK button is pressed, and also close the window.

Parameters:: event -- a pygame.Event.
Returns:: Return True if we 'consumed' this event and don't want to pass it on to the rest of the UI.

pygame_gui.windows.ui_console_window module

class pygame_gui.windows.ui_console_window.UIConsoleWindow(rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, window_title: str = 'pygame-gui.console_title_bar', object_id: ObjectID | str = ObjectID(object_id='#console_window', class_id=None), visible: int = 1, preload_bold_log_font: bool = True, always_on_top: bool = False)

Bases: UIWindow

Create a basic console window. By default, it doesn't do anything except log commands entered into the console in the text box log. There is an event and a few methods however that allow you to hook this console window up to do whatever you would like with the entered text commands.

See the pygame GUI examples repository for an example using it to run the Python Interactive Shell.

Parameters:

rect -- A rect determining the size and position of the console window.
manager -- The UI manager. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_title -- The title displayed in the windows title bar.
object_id -- The object ID for the window, used for theming - defaults to '#console_window'
visible -- Whether the element is visible by default.

add_output_line_to_log(text_to_add: str, is_bold: bool = True, remove_line_break: bool = False, escape_html: bool = True) → None

Adds a single line of text to the log text box. This is intended as a hook to add output/responses to commands entered into the console.

Parameters:

text_to_add -- The single line of text to add to the log.
is_bold -- Determines whether the output is shown in bold or not. Defaults to True.
remove_line_break -- Set this to True to remove the automatic line break at the end of the line of text. Sometimes you might want to add some output all on a single line (e.g. a console style 'progress bar')
escape_html -- Determines whether to escape any HTML in this line of text. Defaults to True, as most people won't be expecting every > or < to be processed as HTML.

clear_log(): Clear the console log, re-starting with a fresh, empty console with no old commands.

process_event(event: Event) → bool

See if we need to handle an event passed down by the UI manager. Returns True if the console window dealt with this event.

Parameters:: event -- The event to handle

restore_default_prefix() → None: Restore the console log prefix to its default value (which is: '> ')

set_log_prefix(prefix: str) → None

Set the prefix to add before commands when they are displayed in the log. This defaults to '> '.

Parameters:: prefix -- A string that is prepended to commands before they are added to the log text box.

set_logged_commands_escape_html(should_escape: bool) → None

Sets whether commands should have any HTML characters escaped before being added to the log. This is because the log uses an HTML Text box and most of the time we don't want to assume that every entered > or < is part of an HTML tag.

By default, HTML is escaped for commands added to the log.

Parameters:: should_escape -- A bool to switch escaping HTML on commands on or off.

pygame_gui.windows.ui_file_dialog module

class pygame_gui.windows.ui_file_dialog.UIFileDialog(rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None, window_title: str = 'pygame-gui.file_dialog_title_bar', allowed_suffixes: Set[str] | None = None, initial_file_path: str | None = None, object_id: ObjectID | str = ObjectID(object_id='#file_dialog', class_id=None), allow_existing_files_only: bool = False, allow_picking_directories: bool = False, visible: int = 1, always_on_top: bool = False)

Bases: UIWindow

A dialog window for handling file selection operations. The dialog will let you pick a file from a file system but won't do anything with it once you have, the path will just be returned leaving it up to the rest of the application to decide what to do with it.

Parameters:

rect -- The size and position of the file dialog window. Includes the size of shadow, border and title bar.
manager -- The manager for the whole of the UI. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_title -- The title for the window, defaults to 'File Dialog'
initial_file_path -- The initial path to open the file dialog at.
object_id -- The object ID for the window, used for theming - defaults to '#file_dialog'
visible -- Whether the element is visible by default.

process_event(event: Event) → bool

Handles events that this UI element is interested in. There are a lot of buttons in the file dialog.

Parameters:: event -- The pygame Event to process.
Returns:: True if event is consumed by this element and should not be passed on to other elements.

update_current_file_list(): Updates the currently displayed list of files and directories. Usually called when the directory path has changed.

pygame_gui.windows.ui_message_window module

class pygame_gui.windows.ui_message_window.UIMessageWindow(rect: Rect | FRect | Tuple[float, float, float, float], html_message: str, manager: IUIManagerInterface | None = None, *, window_title: str = 'pygame-gui.message_window_title_bar', object_id: ObjectID | str = ObjectID(object_id='#message_window', class_id=None), visible: int = 1, html_message_text_kwargs: Dict[str, str] | None = None, always_on_top: bool = False)

Bases: UIWindow

A simple popup window for delivering text-only messages to users.

Parameters:

rect -- The size and position of the window, includes the menu bar across the top.
html_message -- The message itself. Can make use of HTML (a subset of) to style the text.
manager -- The UIManager that manages this UIElement. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_title -- The title of the window.
object_id -- A custom defined ID for fine-tuning of theming. Defaults to '#message_window'.
visible -- Whether the element is visible by default.

process_event(event: Event) → bool

Process any events relevant to the message window. In this case we just close the window when the dismiss button is pressed.

Parameters:: event -- a pygame.Event.
Returns:: Return True if we 'consumed' this event and don't want to pass it on to the rest of the UI.

Module contents

class pygame_gui.windows.UIColourPickerDialog(rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, *, initial_colour: Color = Color(0, 0, 0, 255), window_title: str = 'pygame-gui.colour_picker_title_bar', object_id: ObjectID | str = ObjectID(object_id='#colour_picker_dialog', class_id=None), visible: int = 1, always_on_top: bool = False)

Bases: UIWindow

A colour picker window that gives us a small range of UI tools to pick a final colour.

Parameters:

rect -- The size and position of the colour picker window. Includes the size of shadow, border and title bar.
manager -- The manager for the whole of the UI. If not provided or set to None, it will try to use the first UIManager that was created by your application.
initial_colour -- The starting colour for the colour picker, defaults to black.
window_title -- The title for the window, defaults to 'Colour Picker'
object_id -- The object ID for the window, used for theming - defaults to '#colour_picker_dialog'
visible -- Whether the element is visible by default.

changed_hsv_update_rgb(): Updates the RGB channels when we've altered the HSV ones.

changed_rgb_update_hsv(): Updates the HSV channels when we've altered the RGB ones.

get_colour() → Color: Get the current colour :return:

process_event(event: Event) → bool

Handles events that this UI element is interested in. In this case we are responding to the colour channel elements being changed, the OK or Cancel buttons being pressed or the user clicking the mouse inside the Saturation & Value picking square.

Parameters:: event -- The pygame Event to process.
Returns:: True if event is consumed by this element and should not be passed on to other elements.

set_colour(colour: Color) → None: Set the current colour and update all the necessary elements :param colour: The colour to set :return: None

update_colour_2d_slider(): This is used to update the 2D slider from the sliders :return: None

update_current_colour_image(): Updates the 'current colour' image when the current colour has been changed.

update_saturation_value_square()

Updates the appearance of the big square that lets us visually pick the Saturation and Value of our current Hue. This is done by drawing a very small 4x4 pixel square with a pattern like so:

[black] [hue at max saturation & value] [black] [white]

And then using the smoothscale transform to enlarge it so that the colours blend smoothly from one to the other.

class pygame_gui.windows.UIConfirmationDialog(rect: Rect | FRect | Tuple[float, float, float, float], action_long_desc: str, manager: IUIManagerInterface | None = None, *, window_title: str = 'pygame-gui.Confirm', action_short_name: str = 'pygame-gui.OK', blocking: bool = True, object_id: ObjectID | str = ObjectID(object_id='#confirmation_dialog', class_id=None), visible: int = 1, action_long_desc_text_kwargs: Dict[str, str] | None = None, always_on_top: bool = False)

Bases: UIWindow

A confirmation dialog that lets a user choose between continuing on a path they've chosen or cancelling. It's good practice to give a very brief description of the action they are confirming on the button they click to confirm it i.e. 'Delete' for a file deletion operation or, 'Rename' for a file rename operation.

Parameters:

rect -- The size and position of the window, includes the menu bar across the top.
action_long_desc -- Long-ish description of action. Can make use of HTML to style the text.
manager -- The UIManager that manages this UIElement. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_title -- The title of the window.
action_short_name -- Short, one or two-word description of action for button.
blocking -- Whether this window should block all other mouse interactions with the GUI until it is closed.
object_id -- A custom defined ID for fine-tuning of theming. Defaults to '#confirmation_dialog'.
visible -- Whether the element is visible by default.
action_long_desc_text_kwargs -- a dictionary of variable arguments to pass to the translated string useful when you have multiple translations that need variables inserted in the middle.

process_event(event: Event) → bool

Process any events relevant to the confirmation dialog.

We close the window when the cancel button is pressed, and post a confirmation event (UI_CONFIRMATION_DIALOG_CONFIRMED) when the OK button is pressed, and also close the window.

Parameters:: event -- a pygame.Event.
Returns:: Return True if we 'consumed' this event and don't want to pass it on to the rest of the UI.

class pygame_gui.windows.UIConsoleWindow(rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None = None, window_title: str = 'pygame-gui.console_title_bar', object_id: ObjectID | str = ObjectID(object_id='#console_window', class_id=None), visible: int = 1, preload_bold_log_font: bool = True, always_on_top: bool = False)

Bases: UIWindow

Create a basic console window. By default, it doesn't do anything except log commands entered into the console in the text box log. There is an event and a few methods however that allow you to hook this console window up to do whatever you would like with the entered text commands.

See the pygame GUI examples repository for an example using it to run the Python Interactive Shell.

Parameters:

rect -- A rect determining the size and position of the console window.
manager -- The UI manager. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_title -- The title displayed in the windows title bar.
object_id -- The object ID for the window, used for theming - defaults to '#console_window'
visible -- Whether the element is visible by default.

add_output_line_to_log(text_to_add: str, is_bold: bool = True, remove_line_break: bool = False, escape_html: bool = True) → None

Adds a single line of text to the log text box. This is intended as a hook to add output/responses to commands entered into the console.

Parameters:

text_to_add -- The single line of text to add to the log.
is_bold -- Determines whether the output is shown in bold or not. Defaults to True.
remove_line_break -- Set this to True to remove the automatic line break at the end of the line of text. Sometimes you might want to add some output all on a single line (e.g. a console style 'progress bar')
escape_html -- Determines whether to escape any HTML in this line of text. Defaults to True, as most people won't be expecting every > or < to be processed as HTML.

clear_log(): Clear the console log, re-starting with a fresh, empty console with no old commands.

process_event(event: Event) → bool

See if we need to handle an event passed down by the UI manager. Returns True if the console window dealt with this event.

Parameters:: event -- The event to handle

restore_default_prefix() → None: Restore the console log prefix to its default value (which is: '> ')

set_log_prefix(prefix: str) → None

Set the prefix to add before commands when they are displayed in the log. This defaults to '> '.

Parameters:: prefix -- A string that is prepended to commands before they are added to the log text box.

set_logged_commands_escape_html(should_escape: bool) → None

Sets whether commands should have any HTML characters escaped before being added to the log. This is because the log uses an HTML Text box and most of the time we don't want to assume that every entered > or < is part of an HTML tag.

By default, HTML is escaped for commands added to the log.

Parameters:: should_escape -- A bool to switch escaping HTML on commands on or off.

class pygame_gui.windows.UIFileDialog(rect: Rect | FRect | Tuple[float, float, float, float], manager: IUIManagerInterface | None, window_title: str = 'pygame-gui.file_dialog_title_bar', allowed_suffixes: Set[str] | None = None, initial_file_path: str | None = None, object_id: ObjectID | str = ObjectID(object_id='#file_dialog', class_id=None), allow_existing_files_only: bool = False, allow_picking_directories: bool = False, visible: int = 1, always_on_top: bool = False)

Bases: UIWindow

A dialog window for handling file selection operations. The dialog will let you pick a file from a file system but won't do anything with it once you have, the path will just be returned leaving it up to the rest of the application to decide what to do with it.

Parameters:

rect -- The size and position of the file dialog window. Includes the size of shadow, border and title bar.
manager -- The manager for the whole of the UI. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_title -- The title for the window, defaults to 'File Dialog'
initial_file_path -- The initial path to open the file dialog at.
object_id -- The object ID for the window, used for theming - defaults to '#file_dialog'
visible -- Whether the element is visible by default.

process_event(event: Event) → bool

Handles events that this UI element is interested in. There are a lot of buttons in the file dialog.

Parameters:: event -- The pygame Event to process.
Returns:: True if event is consumed by this element and should not be passed on to other elements.

update_current_file_list(): Updates the currently displayed list of files and directories. Usually called when the directory path has changed.

class pygame_gui.windows.UIMessageWindow(rect: Rect | FRect | Tuple[float, float, float, float], html_message: str, manager: IUIManagerInterface | None = None, *, window_title: str = 'pygame-gui.message_window_title_bar', object_id: ObjectID | str = ObjectID(object_id='#message_window', class_id=None), visible: int = 1, html_message_text_kwargs: Dict[str, str] | None = None, always_on_top: bool = False)

Bases: UIWindow

A simple popup window for delivering text-only messages to users.

Parameters:

rect -- The size and position of the window, includes the menu bar across the top.
html_message -- The message itself. Can make use of HTML (a subset of) to style the text.
manager -- The UIManager that manages this UIElement. If not provided or set to None, it will try to use the first UIManager that was created by your application.
window_title -- The title of the window.
object_id -- A custom defined ID for fine-tuning of theming. Defaults to '#message_window'.
visible -- Whether the element is visible by default.

process_event(event: Event) → bool

Process any events relevant to the message window. In this case we just close the window when the dismiss button is pressed.

Parameters:: event -- a pygame.Event.
Returns:: Return True if we 'consumed' this event and don't want to pass it on to the rest of the UI.