System Tray¶

This module provides system tray functionality for Kivy applications using the core.system_tray components.

Classes Overview¶

The system tray implementation consists of three main classes:

TrayIcon: Main system tray icon management
TrayMenu: Container for menu items
TrayMenuItem: Individual menu entries

Basic Usage¶

Creating a Simple System Tray¶

from kivy.core.system_tray import TrayIcon, TrayMenu, TrayMenuItem

# Approach 1: Using internal menu
system_tray = TrayIcon()
system_tray.create()

main_menu = system_tray.menu
main_menu.add_item(TrayMenuItem(label="File"))
main_menu.add_item(TrayMenuItem(label="Exit"))

# Approach 2: External menu creation
main_menu = TrayMenu()
main_menu.add_item(TrayMenuItem(label="File"))
main_menu.add_item(TrayMenuItem(label="Exit"))

system_tray = TrayIcon(menu=main_menu).create()

Advanced Features¶

Creating Submenus¶

# Create submenu
options_submenu = TrayMenu()
options_submenu.add_item(TrayMenuItem(label="General"))
options_submenu.add_item(TrayMenuItem(label="Security"))

# Add to main menu
main_menu.add_item(
    TrayMenuItem(
        label="Options",
        type="submenu",
        menu=options_submenu
    )
)

Inline Menu Creation¶

For complex menus, you can use inline creation:

system_tray = TrayIcon(
    menu=TrayMenu(
        items=[
            TrayMenuItem(label="File"),
            TrayMenuItem(type="separator"),
            TrayMenuItem(
                label="Options",
                type="submenu",
                menu=TrayMenu(
                    items=[
                        TrayMenuItem(label="General"),
                        TrayMenuItem(label="Security"),
                    ]
                )
            ),
        ]
    )
).create()

Classes Reference¶

TrayIcon¶

class kivy.core.system_tray.TrayIcon(menu=None)¶

Main system tray icon manager.

Parameters:: menu (TrayMenu or None) – Optional TrayMenu instance

create()¶

Initialize and display the system tray icon.

Returns:: TrayIcon instance for method chaining
Return type:: TrayIcon

menu¶

Internal menu reference. Available after create() is called.

Type:: TrayMenu

TrayMenu¶

class kivy.core.system_tray.TrayMenu(items=None)¶

Container for menu items.

Parameters:: items (list or None) – List of TrayMenuItem instances

add_item(item)¶

Add a menu item to the menu.

Parameters:: item (TrayMenuItem) – Menu item to add

TrayMenuItem¶

TrayMenuItem(label=None, type="button", callback=None, enabled=True,

checked=False, menu=None)

Individual menu entry.

Parameters:

label (str or None) – Display text for the menu item
type (str) – Item type (“button”, “checkbox”, “separator”, “submenu”)
callback (callable or None) – Function to call when clicked (only for ‘button’ and ‘checkbox’)
enabled (bool) – Whether the item is clickable/enabled
checked (bool) – Whether the checkbox item is checked (only for ‘checkbox’)
menu (TrayMenu or None) – Submenu for submenu items (only for ‘submenu’)

Note

All properties (label, enabled, checked, callback) can be changed dynamically after the item is created, and the visual menu will update immediately.

Dynamic Properties¶

The components are designed to be fully dynamic. You can change properties on the fly and the system tray will update instantly:

# Change tray icon image and tooltip
system_tray.icon = "new_icon.png"
system_tray.tooltip = "Syncing (45%)"

# Change a specific menu item
meu_botao.label = "Cancel Sync"
meu_botao.enabled = False

# Toggle a checkbox item
meu_checkbox.checked = False

Initialization with Lists¶

You can directly pass a python list of TrayMenuItem objects when creating a TrayIcon or a TrayMenu, and they will automatically be parsed:

system_tray = TrayIcon(
    icon_path="icon.png",
    menu=[
        TrayMenuItem("Enable VPN", type="checkbox", checked=True),
        TrayMenuItem(type="separator"),
        TrayMenuItem("Exit", callback=lambda: exit())
    ]
).create()

Best Practices¶

Menu Structure: Keep menus simple and intuitive
Separators: Use separators to group related items
Method Chaining: TrayIcon.create() returns self for chaining
Memory Management: Store tray reference to prevent garbage collection

Examples¶

Complete Application Example¶

from kivy.app import App
from kivy.uix.label import Label
from kivy.core.system_tray import TrayIcon, TrayMenu, TrayMenuItem

class MyApp(App):
    def build(self):
        # Create system tray
        self.setup_tray()
        return Label(text="App with System Tray")

    def setup_tray(self):
        main_menu = TrayMenu()
        main_menu.add_item(TrayMenuItem(label="Show App"))
        main_menu.add_item(TrayMenuItem(type="separator"))
        main_menu.add_item(TrayMenuItem(label="Exit"))

        self.system_tray = TrayIcon(menu=main_menu).create()

MyApp().run()

Version

Quick search

Table Of Contents