GUI events

Some of the UI Elements produce a pygame.Event when they are interacted with. These events all follow a common structure that looks something like this:

  • 'type' : An id for the specific event that has happened. e.g. 'pygame_gui.UI_BUTTON_PRESSED'

  • 'ui_element' : The UI element that fired this event.

  • 'ui_object_id' : The most unique ID that applies to the UI element that fired this event. e.g. 'hud_window.#sell_button'

Though some of the events also have additional data relevant to that event.

Event list

A list of all the different events by element.

UIButton - UI_BUTTON_PRESSED

Fired when a user presses a button by clicking on it with a mouse, and releasing the mouse button while still hovering over it.

  • 'type' : pygame_gui.UI_BUTTON_PRESSED

  • 'ui_element' : The UIButton that fired this event.

  • 'ui_object_id' : The most unique ID for the button that fired this event.

  • 'mouse_button'The mouse button that did the pressing (pygame.BUTTON_LEFT etc).

    You have to enable button events for buttons other than the left mouse button which is enabled by default.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_BUTTON_PRESSED:
3          if event.ui_element == test_button:
4              print('Test button pressed')

UIButton - UI_BUTTON_START_PRESS

Fired when a user first presses down a button by clicking on it with a mouse. This is fired before you release the mouse button.

  • 'type' : pygame_gui.UI_BUTTON_START_PRESS

  • 'ui_element' : The UIButton that fired this event.

  • 'ui_object_id' : The most unique ID for the button that fired this event.

  • 'mouse_button'The mouse button that did the pressing (pygame.BUTTON_LEFT etc).

    You have to enable button events for buttons other than the left mouse button which is enabled by default.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_BUTTON_PRESSED:
3          if event.ui_element == test_button:
4              print('Test button pressed')

UIButton - UI_BUTTON_DOUBLE_CLICKED

Fired when a user double clicks on a button by left clicking on it with a mouse, then left clicking on it again quickly.

  • 'type' : pygame_gui.UI_BUTTON_DOUBLE_CLICKED

  • 'ui_element' : The UIButton that fired this event.

  • 'ui_object_id' : The most unique ID for the button that fired this event.

  • 'mouse_button'The mouse button that did the pressing (pygame.BUTTON_LEFT etc).

    You have to enable button events for buttons other than the left mouse button which is enabled by default.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_BUTTON_DOUBLE_CLICKED:
3          if event.ui_element == test_button:
4              print('Test button pressed')

UIButton - UI_BUTTON_ON_HOVERED

Fired when a user starts hovering over a button with the mouse.

  • 'type' : pygame_gui.UI_BUTTON_ON_HOVERED

  • 'ui_element' : The UIButton that fired this event.

  • 'ui_object_id' : The most unique ID for the button that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_BUTTON_ON_HOVERED:
3          if event.ui_element == test_button:
4              print('Test button hovered')

UIButton - UI_BUTTON_ON_UNHOVERED

Fired when a user stops hovering over a button with the mouse.

  • 'type' : pygame_gui.UI_BUTTON_ON_UNHOVERED

  • 'ui_element' : The UIButton that fired this event.

  • 'ui_object_id' : The most unique ID for the button that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_BUTTON_ON_UNHOVERED:
3          if event.ui_element == test_button:
4              print('Test button unhovered')

UICheckBox - UI_CHECK_BOX_CHECKED

Fired when a user checks a checkbox by clicking on it with a mouse or pressing space/enter while it has focus.

  • 'type' : pygame_gui.UI_CHECK_BOX_CHECKED

  • 'ui_element' : The UICheckBox that fired this event.

  • 'ui_object_id' : The most unique ID for the checkbox that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_CHECK_BOX_CHECKED:
3          if event.ui_element == test_checkbox:
4              print('Checkbox checked')

UICheckBox - UI_CHECK_BOX_UNCHECKED

Fired when a user unchecks a checkbox by clicking on it with a mouse or pressing space/enter while it has focus.

  • 'type' : pygame_gui.UI_CHECK_BOX_UNCHECKED

  • 'ui_element' : The UICheckBox that fired this event.

  • 'ui_object_id' : The most unique ID for the checkbox that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_CHECK_BOX_UNCHECKED:
3          if event.ui_element == test_checkbox:
4              print('Checkbox unchecked')

UITextBox - UI_TEXT_BOX_LINK_CLICKED

Fired when a user clicks on a HTML link in a text box.

  • 'type' : pygame_gui.UI_TEXT_BOX_LINK_CLICKED,

  • 'link_target' : The 'href' parameter of the clicked link.

  • 'ui_element' : The UITextBox that fired this event.

  • 'ui_object_id' : The most unique ID for the text box that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_TEXT_BOX_LINK_CLICKED:
3          print(event.link_target)

UITextEntryLine - UI_TEXT_ENTRY_CHANGED

Fired when a user changes the text in a text entry element by entering of deleting text. Not fired when set_text() is used.

  • 'type' : pygame_gui.UI_TEXT_ENTRY_CHANGED,

  • 'text' : The user entered text in the text entry line.

  • 'ui_element' : The UITextEntryLine that fired this event.

  • 'ui_object_id' : The most unique ID for the text entry line that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_TEXT_ENTRY_CHANGED:
3         print("Changed text:", event.text)

UITextEntryLine - UI_TEXT_ENTRY_FINISHED

Fired when a user presses the enter key with a text entry element active for entry.

  • 'type' : pygame_gui.UI_TEXT_ENTRY_FINISHED,

  • 'text' : The user entered text in the text entry line.

  • 'ui_element' : The UITextEntryLine that fired this event.

  • 'ui_object_id' : The most unique ID for the text entry line that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_TEXT_ENTRY_FINISHED:
3          print("Entered text:", event.text)

UIDropDownMenu - UI_DROP_DOWN_MENU_CHANGED

Fired when a user selects an option in a drop down menu.

  • 'type' : pygame_gui.UI_DROP_DOWN_MENU_CHANGED,

  • 'text' : The text of the selected option.

  • 'selected_option_id' : The ID of the selected option, if no ids were specified this will be the same as 'text'.

  • 'ui_element' : The UIDropDownMenu that fired this event.

  • 'ui_object_id' : The most unique ID for the drop down menu that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_DROP_DOWN_MENU_CHANGED:
3          print("Selected option:", event.text)

UIHorizontalSlider - UI_HORIZONTAL_SLIDER_MOVED

Fired when a user moves a horizontal slider by pressing an arrow button or dragging the sliding button.

  • 'type' : pygame_gui.UI_HORIZONTAL_SLIDER_MOVED

  • 'value' : The current value the slider is set to.

  • 'ui_element' : The UIHorizontalSlider that fired this event.

  • 'ui_object_id' : The most unique ID for the button that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_HORIZONTAL_SLIDER_MOVED:
3          if event.ui_element == test_slider:
4              print('current slider value:', event.value)

UISelectionList - UI_SELECTION_LIST_NEW_SELECTION

Fired when a user selects a new item in a selection list.

  • 'type' : pygame_gui.UI_SELECTION_LIST_NEW_SELECTION,

  • 'text' : The text of the selected item.

  • 'ui_element' : The UISelectionList that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_SELECTION_LIST_NEW_SELECTION:
3         if event.ui_element == test_selection_list:
4             print("Selected item:", event.text)

UISelectionList - UI_SELECTION_LIST_DROPPED_SELECTION

Fired when a user un-selects an item, dropping it from a selection list.

  • 'type' : pygame_gui.UI_SELECTION_LIST_DROPPED_SELECTION,

  • 'text' : The text of the dropped item.

  • 'ui_element' : The UISelectionList that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2      if event.type == pygame_gui.UI_SELECTION_LIST_DROPPED_SELECTION:
3          if event.ui_element == test_selection_list:
4              print("Dropped item:", event.text)

UISelectionList - UI_SELECTION_LIST_DOUBLE_CLICKED_SELECTION

Fired when a user double clicks on an item in a selection list.

  • 'type' : pygame_gui.UI_SELECTION_LIST_DOUBLE_CLICKED_SELECTION,

  • 'text' : The text of the double clicked item.

  • 'ui_element' : The UISelectionList that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_SELECTION_LIST_DOUBLE_CLICKED_SELECTION:
3         if event.ui_element == test_selection_list:
4             print("Double clicked item:", event.text)

UIWindow - UI_WINDOW_CLOSE

Fired when a window is closed.

  • 'type' : pygame_gui.UI_WINDOW_CLOSE,

  • 'ui_element' : The UIWindow that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_WINDOW_CLOSE:
3         if event.ui_element == window:
4             print("Window closed")

UIWindow - UI_WINDOW_MOVED_TO_FRONT

Fired when a UI window is moved to the top of the stack. This happens when they are newly created and when they are clicked on by a user.

  • 'type' : pygame_gui.UI_WINDOW_MOVED_TO_FRONT,

  • 'ui_element' : The UIWindow that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_WINDOW_MOVED_TO_FRONT:
3         if event.ui_element == window:
4             print("Window moved to front")

UIWindow - UI_WINDOW_RESIZED

Fired when a window is resized.

  • 'type' : pygame_gui.UI_WINDOW_RESIZED,

  • 'ui_element' : The UIWindow that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

  • 'external_size' : The total size of the window including title bar, borders & shadows.

  • 'internal_size' : The size inside the window where other elements are place (excluding title bar, borders & shadows).

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_WINDOW_RESIZED:
3         if event.ui_element == window:
4             print("Window resized")

UIConfirmationDialog - UI_CONFIRMATION_DIALOG_CONFIRMED

Fired when the 'confirm' button is chosen in a confirmation dialog.

  • 'type' : pygame_gui.UI_CONFIRMATION_DIALOG_CONFIRMED,

  • 'ui_element' : The UIConfirmationDialog that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_CONFIRMATION_DIALOG_CONFIRMED:
3         if event.ui_element == confirmation_dialog:
4             print("Confirming action.")

UIFileDialog - UI_FILE_DIALOG_PATH_PICKED

Fired when a path has been chosen in a file dialog.

  • 'type' : pygame_gui.UI_FILE_DIALOG_PATH_PICKED

  • 'text' : The path picked.

  • 'ui_element' : The UIFileDialog that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_FILE_DIALOG_PATH_PICKED:
3         if event.ui_element == file_dialog:
4             print("Path picked:", event.text)

UIColourPickerDialog - UI_COLOUR_PICKER_COLOUR_PICKED

Fired when a colour has been chosen in a colour picker dialog.

  • 'type' : pygame_gui.UI_COLOUR_PICKER_COLOUR_PICKED

  • 'colour' : The colour picked.

  • 'ui_element' : The UIColourPickerDialog that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_COLOUR_PICKER_COLOUR_PICKED:
3         if event.ui_element == colour_picker:
4             print("Colour picked:", event.colour)

UIColourChannelEditor - UI_COLOUR_PICKER_COLOUR_CHANNEL_CHANGED

Fired when a colour channel element has had it's value changed. This event is used by the colour picker dialog.

  • 'type' : pygame_gui.UI_COLOUR_PICKER_COLOUR_CHANNEL_CHANGED

  • 'value' : The current value of the channel.

  • 'channel_index' : The index of this colour channel in the colour (R=0, G=1, B=2 etc).

  • 'ui_element' : The UIColourChannelEditor that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_COLOUR_PICKER_COLOUR_CHANNEL_CHANGED:
3         if event.ui_element == colour_channel:
4             print("Colour channel value:", event.value)

UIConsoleWindow - UI_CONSOLE_COMMAND_ENTERED

Fired when a command is entered into a console window. Usually by typing it in and pressing enter.

  • 'type' : pygame_gui.UI_CONSOLE_COMMAND_ENTERED

  • 'command' : The entered command.

  • 'ui_element' : The UIConsoleWindow that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_CONSOLE_COMMAND_ENTERED:
3         if event.ui_element == debug_console:
4             if event.command == 'godmode':
5                 print("Entering godmode")
6                 player.enable_collision = False

UITextBox - UI_TEXT_EFFECT_FINISHED

Fired when a command is entered into a console window. Usually by typing it in and pressing enter.

  • 'type' : pygame_gui.UI_TEXT_EFFECT_FINISHED

  • 'effect' : The type of the effect that ended.

  • 'ui_element' : The UITextBox that fired this event.

  • 'ui_object_id' : The most unique ID for the element that fired this event.

Example usage:

1 for event in pygame.event.get():
2     if event.type == pygame_gui.UI_TEXT_EFFECT_FINISHED:
3         if event.ui_element == dialog_box:
4             if event.effect == pygame_gui.TEXT_EFFECT_FADE_OUT:
5                 print("Dialog faded out")