Core Elements

GET

The GET function retrieves a widget by its ID for dynamic updates.

GET(id='widget-id')

Example:

widget = GET(id='-my-widget-')
widget.value(42)

Popup

The Popup creates a modal or non-modal dialog window for displaying content or gathering input.

Popup(title='Popup Title', widgets=[[widget1], [widget2, widget3]])

Key Attributes:

• title (str): Title of the popup window.

• widgets (list): Nested list of widgets to display inside the popup.

• size (tuple): Width and height of the popup.

• modal (bool): If True, disables interaction with the parent window.

• center (bool): Centers the popup on the screen.

• move (tuple): Position (x, y) to place the popup.

• margin (tuple | int): Inner margin of the popup content area.

• spacing (int): Spacing between widgets inside the popup.

Example:

Popup(
    title='Settings',
    widgets=[
        [Text(value='Adjust your settings')],
        [Button(value='Close', func=lambda: print('Popup closed'))]
    ],
    size=(300, 200),
    modal=True
)

Folder

The Folder dialog allows users to select a directory.

Folder(caption='Select Folder', directory='/path/to/start')

Key Attributes:

• caption (str): Title of the folder selection dialog.

• directory (str): Initial directory to display.

Example:

folder = Folder(caption='Choose a Directory')
print(f'Selected Folder: {folder}')

File

The File dialog enables selecting or saving files.

File.open(caption='Open File', filter='*.txt')

Key Attributes:

• caption (str): Title of the file dialog.

• filter (str): File type filter (e.g., *.txt).

• directory (str): Initial directory to display.

• type (str): single or multi for selecting one or multiple files.

Example:

file = File()
selected_file = file.open(caption='Open Text File', filter='Text Files (*.txt)')
print(f'Selected File: {selected_file}')

Toolbar

The Toolbar provides a customizable bar for tool buttons.

Toolbar(name='Main Toolbar', tool_items=[button1, button2])

Key Attributes:

• name (str): Name of the toolbar.

• tool_items (list): List of buttons or actions.

• movable (bool): Allows the toolbar to be moved.

• position (str): Position on the window (top, bottom, left, right).

Example:

Toolbar(
    name='Main Toolbar',
    tool_items=[
        Button(value='Save', func=lambda: print('Saved')),
        Button(value='Open', func=lambda: print('Opened'))
    ],
    position='top'
)

Titlebar

The Titlebar allows customization of the window’s title bar. To display the title bar, the window’s frame must be set to False. Window(frame=False)

Titlebar(title='My Application')

Key Attributes:

• title (str): Text displayed in the title bar.

• widgets (list): Additional widgets to include in the title bar.

• background_color (str): Background color of the title bar.

• text_color (str): Color of the title text.

• alignment (str): Alignment of the title text (left, center, right).

Example:

Titlebar(
     title='Custom Titlebar',
     widgets=[Button(value='Help', func=lambda: print('Help clicked'))],
     background_color='gray',
     text_color='white',
     alignment=center
)

MenuBar

The MenuBar provides a menu system for the window.

MenuBar(menu_items=[menu1, menu2])

Note

MenuBar was previously named Menubar. The old lowercase alias menubar is still supported for backwards compatibility.

Key Attributes:

• menu_items (list): A list of menus and their actions.

Example:

MenuBar(
    menu_items=[
        ['File', [item(label='Open', func=lambda: print('File Opened'))]],
        ['Edit', [item(label='Copy', func=lambda: print('Copied'))]]
    ]
)

Statusbar

The Statusbar displays messages and widgets at the bottom of the window.

Statusbar()

Key Attributes:

• message (str): Temporary status message.

• add (widget): Adds a widget to the status bar.

Example:

status = Statusbar()
status.message('Ready', time=5)

Highlight

The Highlight widget is used for syntax highlighting.

Highlight(widget_id='-widget_id-')

Key Attributes:

• widget_id (str): Referencing widget to apply the syntax highlighting to.

• synthax (dict): A dictionary of syntax patterns to highlight. You can use regex using the r() function.

Example:

synthax = {
    r(['rgb',"rgba"]): {
        'color': 'rgb(155, 102, 197)'
    },
}

Highlight(widget_id='-widget_id-', synthax)

TabWidget

The TabWidget allows you to organize content into multiple tabs, enabling efficient navigation between different views or sections. Each tab() now accepts an id parameter for dynamic updates.

TabWidget(tabs=[tab1, tab2], current=0)

Key Attributes:

• tabs (list): A list of tabs, each defined using the tab() function.

• current (int): The index of the tab to display initially.

• id (str): Assigns an identifier for dynamic tab updates.

• tab_changed (function): A callback function triggered when the current tab is changed.

• closable (bool): Allows tabs to be closed by the user.

• close_requested (function): Callback triggered when a tab close button is clicked.

Example:

TabWidget(
    tabs=[
        tab(layout='Content of Tab 1', name='Tab 1', id='tab-1'),
        tab(layout='Content of Tab 2', name='Tab 2', id='tab-2')
    ],
    current=0,
    tab_changed=lambda index: print(f"Switched to Tab {index}")
)

ScrollArea

The ScrollArea widget creates a scrollable container, allowing users to navigate through large or overflowing content.

ScrollArea(widgets=layout)

Key Attributes:

• widgets (list): A list of widgets to display within the scrollable area.

• id (str): Identifier for dynamic updates.

• contain (bool): Enables resizing of child widgets to fit within the scrollable area.

Example:

layout = Box([
     [Text(value='This is a long text inside a scrollable area.')],
     [Image(source='example.png')]
])

ScrollArea(
     widgets=layout,
     id='-scrollable-section-',
     contain=True
)

ColorPicker

The ColorPicker widget provides a popup for selecting colors.

ColorPicker(title='Pick a Color', current='#FF5733')

Key Attributes:

• title (str): Title of the color picker popup.

• current (str): The initial color in hex format (e.g., #FFFFFF).

• color_selected (function): Callback function executed when a color is selected.

• modal (bool): Determines if the popup is modal.

Example:

def on_color_select(color):
    print(f"Selected Color: {color}")

ColorPicker(
    title='Choose Background Color',
    current='#FFFFFF',
    color_selected=on_color_select
)

cursor

The cursor element overrides the mouse cursor for the window or a specific widget. Supports built-in cursor types and custom image cursors.

cursor(type='pointer')

Key Attributes:

• type (str): A built-in cursor type string (e.g., 'pointer', 'crosshair', 'wait').

• image (str): Path to a custom cursor image file.

• size (int): Size of the custom cursor image in pixels. Defaults to 20.

Example:

# Built-in cursor type
cursor(type='crosshair')

# Custom image cursor
cursor(image='path/to/cursor.png', size=24)

font

The font helper loads an external font file and makes it available for use in CSS stylesheets applied to the window.

font(href='path/to/font.ttf')

Key Attributes:

• href (str): Path to the font file (e.g., .ttf, .otf, .woff).

Example:

font(href='fonts/MyCustomFont.ttf')

window.run("""
    Button {
        font-family: MyCustomFont;
    }
""")