Cross-Platform Icon Support

ThreePaneWindows provides comprehensive cross-platform icon support for detached windows, with automatic format detection and fallback mechanisms to ensure your icons display correctly on Windows, macOS, and Linux.

Overview

The enhanced dockable window system supports multiple icon formats and automatically selects the best method for displaying icons based on the current platform and file format. This ensures consistent behavior across different operating systems while providing optimal performance.

Supported Icon Formats

Windows

Primary: .ico (Windows Icon format) - Best support, multiple sizes
Secondary: .png, .bmp, .gif - Good support via PhotoImage

macOS

Primary: .png - Best support, native format
Secondary: .gif, .bmp - Good support
Limited: .ico - May work but not recommended

Linux

Primary: .png, .xbm - Best support
Secondary: .gif, .bmp - Good support
Limited: .ico - May work depending on distribution

Basic Usage

Simple Icon Configuration

from threepanewindows.enhanced_dockable import PaneConfig

# Using a cross-platform PNG icon
config = PaneConfig(
    title="My Panel",
    window_icon="icons/panel_icon.png"  # Will work on all platforms
)

# Using platform-specific icons
config = PaneConfig(
    title="My Panel",
    window_icon="icons/panel_icon.ico"  # Best on Windows
)

Icon Validation and Recommendations

from threepanewindows.enhanced_dockable import (
    get_recommended_icon_formats,
    validate_icon_path
)

# Get recommended formats for current platform
formats = get_recommended_icon_formats()
print(f"Recommended formats: {formats}")

# Validate an icon path
is_valid, message = validate_icon_path("my_icon.png")
print(f"Valid: {is_valid}, Message: {message}")

Advanced Usage

Platform-Specific Icon Selection

import platform
import os
from threepanewindows.enhanced_dockable import PaneConfig

def get_platform_icon():
    """Get the best icon for the current platform."""
    system = platform.system()

    if system == "Windows" and os.path.exists("icons/app.ico"):
        return "icons/app.ico"
    elif os.path.exists("icons/app.png"):
        return "icons/app.png"
    else:
        return ""  # No icon

config = PaneConfig(window_icon=get_platform_icon())

Complete Cross-Platform Setup

import os
import platform
from threepanewindows.enhanced_dockable import (
    EnhancedDockableThreePaneWindow,
    PaneConfig,
    validate_icon_path
)

def setup_cross_platform_icons():
    """Setup icons with cross-platform compatibility."""

    # Define icon paths for different platforms
    icon_paths = {
        "Windows": "icons/app.ico",
        "Darwin": "icons/app.png",  # macOS
        "Linux": "icons/app.png"
    }

    # Get the best icon for current platform
    system = platform.system()
    icon_path = icon_paths.get(system, "icons/app.png")

    # Validate the icon
    is_valid, message = validate_icon_path(icon_path)
    if not is_valid:
        print(f"Icon validation failed: {message}")
        icon_path = ""  # Use no icon

    # Create pane configuration
    left_config = PaneConfig(
        title="File Explorer",
        icon="📁",  # Unicode icon for header
        window_icon=icon_path,  # File icon for detached window
        detachable=True
    )

    return left_config

Icon Resolution Strategy

The system uses the following strategy for setting window icons:

Check file existence: Verify the icon file exists
Format detection: Determine file format from extension
Primary method: Try the best method for the format:
- .ico files: Use iconbitmap() first
- Other formats: Use iconphoto() with PhotoImage
Fallback: If primary method fails, try alternative methods
Graceful degradation: Continue without icon if all methods fail

Best Practices

Use PNG for Cross-Platform Compatibility

# Recommended - works everywhere
config = PaneConfig(window_icon="icons/my_icon.png")

Provide Multiple Formats

import platform
import os

def get_platform_icon():
    """Get the best icon for the current platform."""
    system = platform.system()

    if system == "Windows" and os.path.exists("icons/app.ico"):
        return "icons/app.ico"
    elif os.path.exists("icons/app.png"):
        return "icons/app.png"
    else:
        return ""  # No icon

config = PaneConfig(window_icon=get_platform_icon())

Icon Size Recommendations

Windows .ico: Include multiple sizes (16x16, 32x32, 48x48)
PNG files: Use 32x32 or 48x48 for best results
Avoid very large icons: They may not display properly in title bars

Unicode Icons

You can also use Unicode emoji or symbols as icons:

config = PaneConfig(
    title="Tools",
    icon="🔧",  # This appears in headers
    window_icon=""  # No file icon needed
)

Troubleshooting

Icons Not Appearing

Check file path: Ensure the icon file exists and path is correct
Check format: Use recommended formats for your platform
Check console: Look for warning messages about icon loading
Test with PNG: Try a simple PNG file to verify basic functionality

Platform-Specific Issues

Windows

.ico files work best
Ensure icon files are not corrupted
Some antivirus software may block icon loading

macOS

PNG files work best
.ico files may not work on older macOS versions
Check file permissions

Linux

PNG and XBM work best
Icon support varies by window manager
Some distributions may have limited format support

Migration from Old Code

If you have existing code using only .ico files:

Before (Windows-only)

config = PaneConfig(window_icon="app.ico")

After (Cross-platform)

# Option 1: Use PNG for universal compatibility
config = PaneConfig(window_icon="app.png")

# Option 2: Use platform detection
import platform
icon = "app.ico" if platform.system() == "Windows" else "app.png"
config = PaneConfig(window_icon=icon)

# Option 3: Let the system handle it
config = PaneConfig(window_icon="app.ico")  # Will fallback gracefully

The enhanced system will automatically handle format compatibility and provide appropriate fallbacks.

API Reference

Icon Utility Functions

threepanewindows.get_recommended_icon_formats()[source]

Get recommended icon formats for the current platform.

Returns:

List of file extensions in order of preference for the: current platform. For example, Windows returns [‘.ico’, ‘.png’], while Linux/macOS return [‘.png’, ‘.ico’].

Return type:

List[str]

threepanewindows.validate_icon_path(icon_path)[source]

Validate an icon path for cross-platform compatibility.

Parameters:

icon_path (str) – Path to the icon file to validate.

Returns:

A tuple containing:

bool: True if the icon path is valid and supported, False otherwise
str: Descriptive message about the validation result

Return type:

Tuple[bool, str]

PaneConfig Icon Fields

PaneConfig.icon: Icon (emoji or text) displayed in the panel header.

PaneConfig.window_icon: Path to icon file for detached windows. Supports .ico, .png, .gif, .bmp, .xbm formats with automatic cross-platform optimization.