Listbox

A Listbox widget displays a list of items from which the user can select one, or it can be configured for multiple selection. The items in the listbox can be set when the listbox is created or updated while the app is running.

Examples

Simple Todo

This app shows how the items in a listbox can be added and removed during runtime.

simple_todo.py

import gooeypie as gp

def add_task(event):
    """Add the task to the task list if the Enter/Return key is pressed."""
    if event.key == "Return":
        todo_list.add_item(todo_entry.text)
        todo_entry.text = ""

def remove_task(event):
    """Remove a task when it is double-clicked."""
    todo_list.remove_selected()


app = gp.GooeyPieApp("Simple To-Do List")

# Create widgets
instruction_lbl = gp.Label(
    "Enter a task and press Enter to add it to the list.\n" \
    "Double-click a task to remove it.")
todo_entry = gp.Entry()
todo_list = gp.Listbox()

# Add event listener for entry widget to add new tasks
todo_entry.on_key_press(add_task)

# Add event listener for listbox widget to remove tasks
todo_list.on_double_click(remove_task)

app.add(instruction_lbl, 1, 1)
app.add(todo_entry, 1, 2, expand_horizontal=True)
app.add(todo_list, 1, 3, expand_horizontal=True)

todo_entry.focus()

app.run()

Pizza Order

This example demonstrates how to enable multiple selection for a listbox, allowing the user to select more than one item at a time.

pizza_order.py

import gooeypie as gp

def update_order(event):
    """Count the number of toppings selected"""
    order_lbl.text = f"You have selected {len(toppings_list.selected)} toppings."

def select_all(event):
    """Select all of the toppings!"""
    toppings_list.select_all()


# List of toppings
toppings = ["Pepperoni", "Mushrooms", "Extra Cheese", "Onions", "Ham", "Olives", "Pineapple", "Spinach", "Bacon"]

app = gp.GooeyPieApp("Pizza Order")
app.height = 400

# Create toppings listbox and allow multiple selection
toppings_list = gp.Listbox(toppings)
toppings_list.multiple_selection = True

# Add event listener for listbox widget to update order
toppings_list.on_change(update_order)

# Create select all button and output label
select_all_btn = gp.Button("Select All", select_all)
order_lbl = gp.Label("")

# Add widgets to app
app.add(toppings_list, 1, 1, expand_horizontal=True, expand_vertical=True)
app.add(select_all_btn, 1, 2)
app.add(order_lbl, 1, 3)

# Set row weights so that the listbox takes up all available space
app.set_row_weights(1, 0, 0)

app.run()

---

Creating a Listbox widget

my_listbox = gp.Listbox(items)

Parameters

• items (list of strings): Optional. The list of items to be displayed in the listbox.

Properties

Name	Type	Description
.items	list of strings	Gets or sets the list of items in the listbox. Setting this property will update the items in the listbox to match the new list.
.selected	string, or list of strings if multiple_selection is enabled	Gets or sets the currently selected item in the listbox. Setting this property will change the selected item to the one with the specified value.
.selected_index	integer, or list of integers if multiple_selection is enabled	Gets or sets the index of the currently selected item in the listbox (starting from 0). Setting this property will change the selected item to the one at the specified index.
.multiple_selection	boolean	Gets or sets whether multiple selection is enabled for the listbox. When multiple selection is enabled, the user can select more than one item from the listbox at a time. In this case, the selected property will return a list of the selected items, and the selected_index property will return a list of the indices of the selected items.
.width	integer	Gets or sets the width of the listbox in pixels.
.height	integer	Gets or sets the height of the listbox in pixels.
.disabled	boolean	Gets or sets whether the listbox is disabled. When disabled is set to True, the listbox does not respond to click events.

Methods

Name	Returns	Description
.add_item(item)	None	Adds the item to the end of the listbox.
.add_item_to_start(item)	None	Adds the item to the start of the listbox.
.add_item_at_index(item, index)	None	Adds the item at the specified index in the listbox. If index is out of bounds, the item will be added to the end of the listbox.
.remove_item_at_index(index)	string	Removes and returns the item at the specified index from the listbox.
.remove_selected()	string, or list of strings if multiple_selection is enabled	Removes the currently selected item(s) from the listbox. If no item is selected, this method does nothing.
.select_all()	None	Selects all the items in the listbox. Has no effect if multiple_selection is not enabled.
.clear()	None	Removes all the items from the listbox.

Events

This widget has no unique events. It supports the standard events listed below.

Standard events

• .on_click
• .on_double_click
• .on_right_click
• .on_middle_click
• .on_mouse_down
• .on_mouse_up
• .on_mouse_enter
• .on_mouse_leave
• .on_key_press
• .on_focus_gained
• .on_focus_lost

Styles

How to specify colors

• Colors can be specified as either a hex code (e.g. "#FF0000"), a CSS color name, or "transparent".
• When specifying a color for a style, you can provide either a single color or two colors separated by a comma. If you provide two colors, the first will be used for light mode and the second for dark mode. For example, my_widget.text_color = "steelblue", "skyblue" would specify steelblue for light mode and sky blue for dark mode.

Name	Description	Default
.style.bg_color	The background color of the listbox.	"transparent"
.style.border_color	The color of the border of the listbox.
.style.border_width	The width of the border of the listbox.	2
.style.corner_radius	The radius of the corners of the listbox.	6
.style.text_color	The color of the text of the listbox.
.style.text_disabled_color	The color of the text of the listbox when it is disabled.
.style.selected_color	The color of the background of the selected item in the listbox.
.style.unselected_color	The color of the background of the unselected items in the listbox.	"transparent"
.style.hover_color	The color of the background of the listbox items when the mouse hovers over them.
.style.font_name	The font of the text of the button. Either an installed font or a generic font name: "serif", "sans-serif", "monospace" or "system"	"system"
.style.font_size	The size of the text of the button.	12
.style.font_weight	The weight of the text of the button. Either "normal" or "bold".	"normal"
.style.font_style	The style of the text of the button. Either "normal" or "italic".	"normal"