CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-guizero

Python module to allow learners to easily create GUIs

Pending
Overview
Eval results
Files

dialogs.mddocs/

Dialog Functions

Dialog functions provide modal interfaces for user interaction including message boxes, file selection, and input prompts. All dialog functions can optionally be associated with a parent window for proper positioning and behavior.

Capabilities

Message Dialogs

Message dialogs display information to the user and wait for acknowledgment.

def warn(title, text, master=None):
    """
    Display a warning message box.
    
    Args:
        title (str): Title text for the dialog
        text (str): Warning message to display
        master (App, optional): Parent window for dialog positioning
        
    Returns:
        None
    """

def info(title, text, master=None):
    """
    Display an information message box.
    
    Args:
        title (str): Title text for the dialog
        text (str): Information message to display
        master (App, optional): Parent window for dialog positioning
        
    Returns:
        None
    """

def error(title, text, master=None):
    """
    Display an error message box.
    
    Args:
        title (str): Title text for the dialog
        text (str): Error message to display
        master (App, optional): Parent window for dialog positioning
        
    Returns:
        None
    """

Usage Example

from guizero import App, PushButton, warn, info, error

app = App()

def show_warning():
    warn("Warning", "This is a warning message!", app)

def show_info():
    info("Information", "This is an informational message.", app)

def show_error():
    error("Error", "Something went wrong!", app)

PushButton(app, text="Show Warning", command=show_warning)
PushButton(app, text="Show Info", command=show_info)  
PushButton(app, text="Show Error", command=show_error)

app.display()

Question Dialogs

Question dialogs prompt the user for responses and return their input.

def yesno(title, text, master=None):
    """
    Display a yes/no question dialog.
    
    Args:
        title (str): Title text for the dialog
        text (str): Question to ask the user
        master (App, optional): Parent window for dialog positioning
        
    Returns:
        bool: True if user clicked Yes, False if user clicked No
    """

def question(title, question, initial_value=None, master=None):
    """
    Display a text input question dialog.
    
    Args:
        title (str): Title text for the dialog
        question (str): Question or prompt text
        initial_value (str, optional): Default text in the input field
        master (App, optional): Parent window for dialog positioning
        
    Returns:
        str: User's text input, or None if cancelled
    """

Usage Example

from guizero import App, PushButton, Text, yesno, question

app = App()
result_text = Text(app, text="Results will appear here")

def ask_yes_no():
    answer = yesno("Confirm", "Do you want to continue?", app)
    result_text.value = f"You answered: {'Yes' if answer else 'No'}"

def ask_question():
    name = question("Input", "What is your name?", "Enter name here", app)
    if name:
        result_text.value = f"Hello, {name}!"
    else:
        result_text.value = "No name entered"

PushButton(app, text="Ask Yes/No", command=ask_yes_no)
PushButton(app, text="Ask Question", command=ask_question)

app.display()

File Selection Dialogs

File dialogs allow users to select files or folders from their filesystem.

def select_file(title="Select file", folder=".", filetypes=[["All files", "*.*"]], 
                save=False, master=None, filename=""):
    """
    Display a file selection dialog.
    
    Args:
        title (str): Dialog title text
        folder (str): Initial directory to open
        filetypes (list): List of file type filters as [description, pattern] pairs
        save (bool): True for save dialog, False for open dialog
        master (App, optional): Parent window for dialog positioning
        filename (str): Initial filename (for save dialogs)
        
    Returns:
        str: Selected file path, or None if cancelled
    """

def select_folder(title="Select folder", folder=".", master=None):
    """
    Display a folder selection dialog.
    
    Args:
        title (str): Dialog title text
        folder (str): Initial directory to open
        master (App, optional): Parent window for dialog positioning
        
    Returns:
        str: Selected folder path, or None if cancelled
    """

Usage Example

from guizero import App, PushButton, Text, select_file, select_folder
import os

app = App()
path_text = Text(app, text="No file selected")

def choose_file():
    # Define file type filters
    filetypes = [
        ["Text files", "*.txt"],
        ["Python files", "*.py"],
        ["All files", "*.*"]
    ]
    
    filepath = select_file(
        title="Choose a file",
        folder=os.path.expanduser("~"),
        filetypes=filetypes,
        master=app
    )
    
    if filepath:
        path_text.value = f"Selected: {os.path.basename(filepath)}"
    else:
        path_text.value = "No file selected"

def save_file():
    filetypes = [["Text files", "*.txt"], ["All files", "*.*"]]
    
    filepath = select_file(
        title="Save file as",
        folder=os.path.expanduser("~"),
        filetypes=filetypes,
        save=True,
        filename="document.txt",
        master=app
    )
    
    if filepath:
        path_text.value = f"Save to: {os.path.basename(filepath)}"
    else:
        path_text.value = "Save cancelled"

def choose_folder():
    folderpath = select_folder(
        title="Choose a folder",
        folder=os.path.expanduser("~"),
        master=app
    )
    
    if folderpath:
        path_text.value = f"Folder: {os.path.basename(folderpath)}"
    else:
        path_text.value = "No folder selected"

PushButton(app, text="Open File", command=choose_file)
PushButton(app, text="Save File", command=save_file)
PushButton(app, text="Choose Folder", command=choose_folder)

app.display()

Color Selection Dialog

The color dialog allows users to select colors using a standard color picker interface.

def select_color(color=None, master=None):
    """
    Display a color selection dialog.
    
    Args:
        color: Initial color selection (name, hex, or RGB tuple)
        master (App, optional): Parent window for dialog positioning
        
    Returns:
        str: Selected color as hex string (#RRGGBB), or None if cancelled
    """

Usage Example

from guizero import App, PushButton, Text, Box, select_color

app = App()

# Display current color
color_display = Box(app, width=100, height=50)
color_display.bg = "white"

color_text = Text(app, text="Color: #FFFFFF")

def pick_color():
    # Start with current color
    current_color = color_display.bg
    
    selected_color = select_color(color=current_color, master=app)
    
    if selected_color:
        # Update display
        color_display.bg = selected_color
        color_text.value = f"Color: {selected_color}"

PushButton(app, text="Pick Color", command=pick_color)

app.display()

File Type Filters

The select_file function accepts a list of file type filters to limit what files are shown:

# Common file type examples
filetypes = [
    ["Text files", "*.txt"],
    ["Python files", "*.py"],  
    ["Image files", "*.png *.jpg *.gif"],
    ["All files", "*.*"]
]

# Multiple extensions for one type
filetypes = [
    ["Documents", "*.txt *.doc *.docx"],
    ["Images", "*.png *.jpg *.jpeg *.gif *.bmp"],
    ["All files", "*.*"]
]

Dialog Best Practices

Parent Window Association

Always pass the parent app/window to ensure proper dialog behavior:

# Good - dialog appears over parent window
result = yesno("Confirm", "Continue?", master=app)

# Avoid - dialog may appear anywhere on screen
result = yesno("Confirm", "Continue?")

Error Handling

Handle cases where users cancel dialogs:

def open_file():
    filepath = select_file(master=app)
    
    if filepath:
        # User selected a file
        try:
            with open(filepath, 'r') as f:
                content = f.read()
            # Process file content
        except IOError:
            error("Error", f"Could not read file: {filepath}", app)
    else:
        # User cancelled - no action needed
        pass

Input Validation

Validate user input from question dialogs:

def get_age():
    age_str = question("Input", "Enter your age:", master=app)
    
    if age_str:
        try:
            age = int(age_str)
            if age < 0:
                error("Error", "Age cannot be negative", app)
            else:
                info("Success", f"Your age is {age}", app)
        except ValueError:
            error("Error", "Please enter a valid number", app)

Platform Considerations

Dialog appearance and behavior may vary between operating systems:

  • Windows: Standard Windows dialog styling
  • macOS: Native macOS dialog appearance
  • Linux: Depends on desktop environment (GTK/Qt styling)

File path separators and default locations are handled automatically by the underlying system.

Install with Tessl CLI

npx tessl i tessl/pypi-guizero

docs

application.md

containers.md

dialogs.md

display-widgets.md

index.md

input-widgets.md

menus.md

tile.json