### Install psgtray

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Install psgtray using pip from PyPI for the stable release or from GitHub for the latest development version.

```bash
pip install --upgrade psgtray
```

```bash
pip install --upgrade https://github.com/PySimpleGUI/psgtray/zipball/main
```

--------------------------------

### Install psgtray from GitHub using PIP (Windows)

Source: https://github.com/pysimplegui/psgtray/blob/main/README.md

Install the latest version of psgtray directly from GitHub if you use 'python' on Windows.

```bash
python -m pip install --upgrade https://github.com/PySimpleGUI/psgtray/zipball/main
```

--------------------------------

### Install psgtray using PIP (Windows)

Source: https://github.com/pysimplegui/psgtray/blob/main/README.md

Use this command to install the psgtray package if you use 'python' to invoke Python on Windows.

```bash
python -m pip install --upgrade psgtray
```

--------------------------------

### Install psgtray using PIP (Linux/Mac)

Source: https://github.com/pysimplegui/psgtray/blob/main/README.md

Use this command to install the psgtray package if you use 'python3' to invoke Python on Linux or Mac.

```bash
python3 -m pip install --upgrade psgtray
```

--------------------------------

### Install psgtray from GitHub using PIP (Linux/Mac)

Source: https://github.com/pysimplegui/psgtray/blob/main/README.md

Install the latest version of psgtray directly from GitHub if you use 'python3' on Linux or Mac.

```bash
python3 -m pip install --upgrade https://github.com/PySimpleGUI/psgtray/zipball/main
```

--------------------------------

### PySimpleGUI System Tray Example

Source: https://github.com/pysimplegui/psgtray/blob/main/README.md

Demonstrates how to integrate a system tray icon with a PySimpleGUI window. The system tray event can be mapped to the window's event loop for seamless interaction. Ensure the SystemTray object is closed properly to avoid lingering icons.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

"""
    A System Tray Icon courtesy of pystray and your friends at PySimpleGUI
    
    Import the SystemTray object with this line of code:
    from psgtray import SystemTray

    Key for the system tray icon is: 
        tray = SystemTray()
        tray.key
        
    values[key] contains the menu item chosen.
    
    One trick employed here is to change the window's event to be the event from the System Tray.
    
    
    Copyright PySimpleGUI 2021
"""

def main():

    menu = ['', ['Show Window', 'Hide Window', '---', '!Disabled Item', 'Change Icon', ['Happy', 'Sad', 'Plain'], 'Exit']]
    tooltip = 'Tooltip'

    layout = [[sg.Text('My PySimpleGUI Celebration Window - X will minimize to tray')],
              [sg.T('Double clip icon to restore or right click and choose Show Window')],
              [sg.T('Icon Tooltip:'), sg.Input(tooltip, key='-IN-', s=(20,1)), sg.B('Change Tooltip')],
              [sg.Multiline(size=(60,10), reroute_stdout=False, reroute_cprint=True, write_only=True, key='-OUT-')],
              [sg.Button('Go'), sg.B('Hide Icon'), sg.B('Show Icon'), sg.B('Hide Window'), sg.Button('Exit')]]

    window = sg.Window('Window Title', layout, finalize=True, enable_close_attempted_event=True)


    tray = SystemTray(menu, single_click_events=False, window=window, tooltip=tooltip, icon=sg.DEFAULT_BASE64_ICON)
    tray.show_message('System Tray', 'System Tray Icon Started!')
    sg.cprint(sg.get_versions())
    while True:
        event, values = window.read()

        # IMPORTANT step. It's not required, but convenient. Set event to value from tray
        # if it's a tray event, change the event variable to be whatever the tray sent
        if event == tray.key:
            sg.cprint(f'System Tray Event = ', values[event], c='white on red')
            event = values[event]       # use the System Tray's event as if was from the window

        if event in (sg.WIN_CLOSED, 'Exit'):
            break

        sg.cprint(event, values)
        tray.show_message(title=event, message=values)

        if event in ('Show Window', sg.EVENT_SYSTEM_TRAY_ICON_DOUBLE_CLICKED):
            window.un_hide()
            window.bring_to_front()
        elif event in ('Hide Window', sg.WIN_CLOSE_ATTEMPTED_EVENT):
            window.hide()
            tray.show_icon()        # if hiding window, better make sure the icon is visible
            # tray.notify('System Tray Item Chosen', f'You chose {event}')
        elif event == 'Happy':
            tray.change_icon(sg.EMOJI_BASE64_HAPPY_JOY)
        elif event == 'Sad':
            tray.change_icon(sg.EMOJI_BASE64_FRUSTRATED)
        elif event == 'Plain':
            tray.change_icon(sg.DEFAULT_BASE64_ICON)
        elif event == 'Hide Icon':
            tray.hide_icon()
        elif event == 'Show Icon':
            tray.show_icon()
        elif event == 'Change Tooltip':
            tray.set_tooltip(values['-IN-'])

    tray.close()            # optional but without a close, the icon may "linger" until moused over
    window.close()

if __name__ == '__main__':
    main()

```

--------------------------------

### Multiple System Tray Icons with Independent Handling

Source: https://context7.com/pysimplegui/psgtray/llms.txt

This example shows how to run multiple system tray icons simultaneously, each with its own menu and event key for independent handling within a single PySimpleGUI window.

```python
import PySimpleGUI as sg
from psgtray import SystemTray
import time

menu1 = ['', ['Tray 1 Action', 'Exit']]
menu2 = ['', ['Tray 2 Action', 'Exit']]

layout = [[sg.Text('Multiple Tray Icons Demo')],
          [sg.Multiline(size=(50, 10), key='-LOG-', autoscroll=True)],
          [sg.Button('Exit')]]
window = sg.Window('Multi-Tray Demo', layout, finalize=True)

# Create two separate tray icons
tray1 = SystemTray(menu1, window=window, tooltip='Tray Icon 1',
                   icon=sg.DEFAULT_BASE64_ICON, key='-TRAY1-')
tray2 = SystemTray(menu2, window=window, tooltip='Tray Icon 2',
                   icon=sg.EMOJI_BASE64_HAPPY_JOY, key='-TRAY2-')

time.sleep(0.5)  # Brief delay when starting multiple trays
tray2.show_message('Ready', 'Both tray icons are active')

while True:
    event, values = window.read()

    # Handle events from either tray
    if event in (tray1.key, tray2.key):
        tray_source = 'Tray 1' if event == tray1.key else 'Tray 2'
        tray_event = values[event]
        window['-LOG-'].print(f'{tray_source}: {tray_event}')
        event = tray_event

    if event in (sg.WIN_CLOSED, 'Exit'):
        break

    if event == 'Tray 1 Action':
        tray1.show_message('Tray 1', 'Action from Tray Icon 1')
    elif event == 'Tray 2 Action':
        tray2.show_message('Tray 2', 'Action from Tray Icon 2')

# Close both trays
tray1.close()
tray2.close()
window.close()
```

--------------------------------

### Hidden Window System Tray Application

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Example of creating a pure system tray application where the window is never visible to the user, useful for background services.

```APIDOC
## Hidden Window System Tray Application

### Description
Create a pure system tray application where the window is never visible to the user. This pattern is useful for background services or utilities that only need tray interaction.

### Method
POST (or equivalent for dynamic update)

### Endpoint
SystemTray object initialization and usage

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import PySimpleGUI as sg
from psgtray import SystemTray

menu = ['', [
    'Action 1',
    'Action 2',
    '---',
    'Settings', ['Option A', 'Option B'],
    'Exit'
]]

window = sg.Window('Hidden Window Tray App', layout=[[]], size=(1,1), no_titlebar=True, transparent_color=sg.theme_background_color(), alpha_channel=0)
tray = SystemTray(menu, window=window, tooltip='My Hidden App', icon=sg.DEFAULT_BASE64_ICON)

while True:
    event, values = window.read()
    if event == tray.key:
        event = values[event]
    if event in (sg.WIN_CLOSED, 'Exit'):
        break
    # Handle other menu events here

tray.close()
window.close()
```

### Response
#### Success Response (200)
None (application runs in the background)

#### Response Example
None
```

--------------------------------

### SystemTray Class Constructor

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Create a system tray icon with a customizable menu, tooltip, and event handling. The SystemTray class runs in a background thread and sends events to a specified PySimpleGUI window.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

# Define the tray menu structure
# Format: ['', [menu_items...]] where menu_items can include submenus
menu = ['', [
    'Show Window',
    'Hide Window',
    '---',              # Separator line
    '!Disabled Item',   # Prefix with ! to disable
    'Change Icon', ['Happy', 'Sad', 'Plain'],  # Submenu
    'Exit'
]]

# Create a PySimpleGUI window (required for event handling)
layout = [[sg.Text('My Application')],
          [sg.Button('Exit')]]
window = sg.Window('My App', layout, finalize=True, enable_close_attempted_event=True)

# Create the system tray icon
tray = SystemTray(
    menu=menu,                          # Menu data structure
    icon=sg.DEFAULT_BASE64_ICON,        # Icon as file path or base64 bytes
    tooltip='My Application',           # Hover tooltip text
    single_click_events=False,          # Set True to receive single-click events
    window=window,                       # Target window for events
    key='-TRAY-'                         # Custom event key (default: '-TRAY-')
)
```

--------------------------------

### Create Hidden Window System Tray Application

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Develop a system tray application without a visible window, suitable for background services. This pattern uses only tray interactions.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

menu = ['', [
    'Action 1',
    'Action 2',
    '---',
    'Settings', ['Option A', 'Option B'],
    'Exit'
]]
```

--------------------------------

### Create a Hidden Window for System Tray

Source: https://context7.com/pysimplegui/psgtray/llms.txt

This snippet demonstrates how to create a hidden, fully transparent window that is required for system tray event handling. The window is hidden immediately after creation.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

# Define the menu for the system tray
menu = ['', ['Action 1', 'Action 2', 'Option A', 'Option B', 'Exit']]

# Create a hidden window (required for event handling)
layout = [[sg.Text('Hidden Window')]]
window = sg.Window('Background App', layout, finalize=True,
                   enable_close_attempted_event=True,
                   alpha_channel=0)  # Fully transparent
window.hide()  # Hide immediately

tray = SystemTray(menu, window=window, tooltip='Background Service',
                  icon=sg.DEFAULT_BASE64_ICON, key='-TRAY-')
tray.show_message('Started', 'Background service is running')

while True:
    event, values = window.read()

    if event == tray.key:
        event = values[event]

    if event in (sg.WIN_CLOSED, 'Exit'):
        break

    if event == 'Action 1':
        tray.show_message('Action 1', 'Performing Action 1...')
        # Perform background task
    elif event == 'Action 2':
        tray.show_message('Action 2', 'Performing Action 2...')
    elif event == 'Option A':
        tray.set_tooltip('Option A selected')
    elif event == 'Option B':
        tray.set_tooltip('Option B selected')

tray.close()
window.close()
```

--------------------------------

### change_icon() - Dynamic Icon Updates

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Allows changing the system tray icon at runtime. Icons can be specified as file paths or base64-encoded byte strings.

```APIDOC
## change_icon()

### Description
Allows changing the system tray icon at runtime. Icons can be specified as file paths or base64-encoded byte strings.

### Method
POST (or equivalent for dynamic update)

### Endpoint
SystemTray object method

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **icon_data** (str | bytes) - Required - The new icon data, either a file path or a base64-encoded string.

### Request Example
```python
tray.change_icon(sg.EMOJI_BASE64_HAPPY_JOY)
tray.change_icon('/path/to/custom_icon.png')
```

### Response
#### Success Response (200)
None (operation is performed)

#### Response Example
None
```

--------------------------------

### hide_icon() and show_icon() - Toggle Icon Visibility

Source: https://context7.com/pysimplegui/psgtray/llms.txt

These methods control the visibility of the system tray icon, allowing it to be hidden temporarily and shown again later.

```APIDOC
## hide_icon() and show_icon()

### Description
These methods control the visibility of the system tray icon, allowing it to be hidden temporarily and shown again later.

### Method
POST (or equivalent for dynamic update)

### Endpoint
SystemTray object method

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
tray.hide_icon()
tray.show_icon()
```

### Response
#### Success Response (200)
None (operation is performed)

#### Response Example
None
```

--------------------------------

### set_tooltip() - Update Tooltip Text

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Changes the tooltip text that appears when hovering over the system tray icon.

```APIDOC
## set_tooltip()

### Description
Changes the tooltip text that appears when hovering over the system tray icon.

### Method
POST (or equivalent for dynamic update)

### Endpoint
SystemTray object method

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tooltip_text** (str) - Required - The new tooltip text.

### Request Example
```python
tray.set_tooltip('New tooltip text')
```

### Response
#### Success Response (200)
None (operation is performed)

#### Response Example
None
```

--------------------------------

### Toggle System Tray Icon Visibility

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Use hide_icon() and show_icon() to control the system tray icon's visibility. This allows the icon to be temporarily hidden and then revealed later.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

menu = ['', ['Toggle Visibility', 'Exit']]
layout = [[sg.Text('Icon Visibility Demo')], [sg.Button('Hide Icon'), sg.Button('Show Icon'), sg.Button('Exit')]]
window = sg.Window('Visibility Demo', layout, finalize=True)
tray = SystemTray(menu, window=window, tooltip='Visibility Demo', icon=sg.DEFAULT_BASE64_ICON)

icon_visible = True

while True:
    event, values = window.read()
    if event == tray.key:
        event = values[event]

    if event in (sg.WIN_CLOSED, 'Exit'):
        break

    if event == 'Hide Icon':
        tray.hide_icon()
        icon_visible = False
        print('Icon hidden')

    if event == 'Show Icon':
        tray.show_icon()
        icon_visible = True
        print('Icon visible')

    if event == 'Toggle Visibility':
        if icon_visible:
            tray.hide_icon()
            icon_visible = False
        else:
            tray.show_icon()
            icon_visible = True

tray.close()
window.close()
```

--------------------------------

### Update System Tray Tooltip Text

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Use set_tooltip to change the tooltip text displayed on hover. This method can be called to update the tooltip dynamically based on application events or user input.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

menu = ['', ['Update Status', 'Exit']]
layout = [[sg.Text('Enter new tooltip:')], [sg.Input(key='-TOOLTIP-', size=(30, 1))], [sg.Button('Set Tooltip'), sg.Button('Exit')]]
window = sg.Window('Tooltip Demo', layout, finalize=True)
tray = SystemTray(menu, window=window, tooltip='Initial Tooltip', icon=sg.DEFAULT_BASE64_ICON)

status_count = 0

while True:
    event, values = window.read()
    if event == tray.key:
        event = values[event]

    if event in (sg.WIN_CLOSED, 'Exit'):
        break

    if event == 'Set Tooltip':
        new_tooltip = values['-TOOLTIP-']
        if new_tooltip:
            tray.set_tooltip(new_tooltip)
            tray.show_message('Tooltip Updated', f'New tooltip: {new_tooltip}')

    if event == 'Update Status':
        status_count += 1
        tray.set_tooltip(f'Status updates: {status_count}')

tray.close()
window.close()
```

--------------------------------

### Change System Tray Icon Dynamically

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Use change_icon to update the system tray icon at runtime. Icons can be file paths or base64 strings. Ensure PySimpleGUI and psgtray are imported.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

menu = ['', ['Happy Icon', 'Sad Icon', 'Default Icon', 'Exit']]
layout = [[sg.Text('Icon Change Demo')]]
window = sg.Window('Demo', layout, finalize=True)
tray = SystemTray(menu, window=window, tooltip='Icon Demo', icon=sg.DEFAULT_BASE64_ICON)

while True:
    event, values = window.read()
    if event == tray.key:
        event = values[event]

    if event in (sg.WIN_CLOSED, 'Exit'):
        break

    # Change icon based on menu selection
    if event == 'Happy Icon':
        tray.change_icon(sg.EMOJI_BASE64_HAPPY_JOY)
    elif event == 'Sad Icon':
        tray.change_icon(sg.EMOJI_BASE64_FRUSTRATED)
    elif event == 'Default Icon':
        tray.change_icon(sg.DEFAULT_BASE64_ICON)

    # Can also use a file path
    # tray.change_icon('/path/to/custom_icon.png')

tray.close()
window.close()
```

--------------------------------

### show_message() - Display Notification Balloons

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Display notification balloons or toast messages from the system tray icon using the show_message method. This is useful for alerting users when the main window is hidden.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

menu = ['', ['Notify', 'Exit']]
layout = [[sg.Text('Notification Demo')]]
window = sg.Window('Demo', layout, finalize=True)
tray = SystemTray(menu, window=window, tooltip='Notifier', icon=sg.DEFAULT_BASE64_ICON)

# Show a welcome notification
tray.show_message(
    title='Application Started',
    message='The application is now running in the system tray.'
)

while True:
    event, values = window.read()
    if event == tray.key:
        event = values[event]

    if event in (sg.WIN_CLOSED, 'Exit'):
        break

    if event == 'Notify':
        tray.show_message(
            title='Custom Notification',
            message='This is a notification balloon from the system tray!'
        )

tray.close()
window.close()
```

--------------------------------

### close() - Clean Shutdown

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Properly shuts down the system tray icon and its background thread. Calling close prevents the icon from lingering in the tray after the application exits.

```APIDOC
## close()

### Description
Properly shuts down the system tray icon and its background thread. Calling close prevents the icon from lingering in the tray after the application exits.

### Method
POST (or equivalent for dynamic update)

### Endpoint
SystemTray object method

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
tray.close()
```

### Response
#### Success Response (200)
None (operation is performed)

#### Response Example
None
```

--------------------------------

### Process Tray Events in Event Loop

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Process system tray events within the main PySimpleGUI event loop. Tray events are identified by the tray's key, and menu selections are found in the values dictionary. Handle double-click and single-click events as needed.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

menu = ['', ['Show Window', 'Hide Window', 'Exit']]
layout = [[sg.Text('System Tray Demo')], [sg.Button('Exit')]]
window = sg.Window('Demo', layout, finalize=True, enable_close_attempted_event=True)
tray = SystemTray(menu, window=window, tooltip='Demo App', icon=sg.DEFAULT_BASE64_ICON)

while True:
    event, values = window.read()

    # Check if this is a tray event
    if event == tray.key:
        # Extract the actual menu selection from values
        tray_event = values[event]
        print(f'Tray event: {tray_event}')
        event = tray_event  # Optionally reassign for unified handling

    if event in (sg.WIN_CLOSED, 'Exit'):
        break

    # Handle double-click on tray icon
    if event == sg.EVENT_SYSTEM_TRAY_ICON_DOUBLE_CLICKED:
        window.un_hide()
        window.bring_to_front()

    # Handle single-click (only if single_click_events=True)
    if event == sg.EVENT_SYSTEM_TRAY_ICON_ACTIVATED:
        print('Icon was single-clicked')

    if event == 'Show Window':
        window.un_hide()
        window.bring_to_front()
    elif event == 'Hide Window':
        window.hide()
        tray.show_icon()

tray.close()
window.close()
```

--------------------------------

### Clean Shutdown of System Tray Icon

Source: https://context7.com/pysimplegui/psgtray/llms.txt

Call close() to properly shut down the system tray icon and its background thread. This prevents the icon from lingering after the application exits.

```python
import PySimpleGUI as sg
from psgtray import SystemTray

menu = ['', ['Exit']]
layout = [[sg.Text('Press Exit or close window')], [sg.Button('Exit')]]
window = sg.Window('Close Demo', layout, finalize=True, enable_close_attempted_event=True)
tray = SystemTray(menu, window=window, tooltip='Close Demo', icon=sg.DEFAULT_BASE64_ICON)

while True:
    event, values = window.read()
    if event == tray.key:
        event = values[event]

    # Handle both window close and Exit button/menu
    if event in (sg.WIN_CLOSED, 'Exit'):
        break

    # Minimize to tray instead of closing
    if event == sg.WIN_CLOSE_ATTEMPTED_EVENT:
        window.hide()
        tray.show_message('Minimized', 'Application minimized to tray')
        continue

# Clean shutdown - always call close() for proper cleanup
tray.close()
window.close()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.