Enhanced Dockable API

The enhanced dockable module provides professional-grade three-pane windows with advanced features including cross-platform icon support, professional theming, and sophisticated user interactions.

Enhanced Professional Dockable Three-Pane Window.

This module provides a sophisticated, highly customizable three-pane window with professional theming, smooth animations, and intuitive drag-and-drop detaching/attaching functionality.

class threepanewindows.enhanced_dockable.DetachedWindow(parent, pane_side, config, content_builder, on_reattach, theme_manager, layout_instance=None, **kwargs)

Bases: Toplevel

Professional detached window for displaying pane content in a separate window.

This class creates a standalone window that can display pane content when a pane is detached from the main three-pane layout. It supports custom titlebars, theming, scrollable content, and reattachment functionality.

Initialize detached window with configuration and callbacks.

Parameters:

• parent – The parent window (usually the main application window).

• pane_side (str) – Which pane this window represents (‘left’, ‘center’, ‘right’).

• config (PaneConfig) – Configuration object defining window behavior and appearance.

• content_builder (Callable) – Function to call to build the window’s content.

• on_reattach (Callable) – Callback function to call when the window should be reattached.

• theme_manager (ThemeManager) – Theme manager for consistent styling.

• layout_instance – Reference to the main layout instance (optional).

• **kwargs – Additional keyword arguments passed to tk.Toplevel.

create_themed_scrollbar(parent, orient='vertical', command=None, **kwargs)

Create a platform-appropriate themed scrollbar for detached window.

Delegates to the main layout instance if available.

get_platform_info()

Get platform information. Delegates to layout instance if available.

refresh_theme()

Refresh the detached window with the current theme.

class threepanewindows.enhanced_dockable.DragHandle(parent, pane_side, on_detach, theme_manager, **kwargs)

Bases: Frame

Professional drag handle for detaching panes.

Initialize drag handle with parent, pane side, detach callback, and theme.

Parameters:

• pane_side (str)

• on_detach (Callable)

• theme_manager (ThemeManager)

class threepanewindows.enhanced_dockable.EnhancedDockableThreePaneWindow(master=None, left_config=None, center_config=None, right_config=None, left_builder=None, center_builder=None, right_builder=None, theme_name='light', theme=None, enable_animations=True, menu_bar=None, show_status_bar=False, show_toolbar=False, **kwargs)

Bases: Frame

Enhanced professional dockable three-pane window with theming and advanced UI.

Features: - Professional theming system - Drag-and-drop detaching - Smooth animations - Customizable pane configurations - Professional visual feedback

Initialize enhanced dockable three-pane window with configuration options.

Parameters:

• master – Parent widget (usually the root window).

• left_config (Optional[PaneConfig]) – Configuration for the left pane.

• center_config (Optional[PaneConfig]) – Configuration for the center pane.

• right_config (Optional[PaneConfig]) – Configuration for the right pane.

• left_builder (Optional[Callable]) – Function to build left pane content.

• center_builder (Optional[Callable]) – Function to build center pane content.

• right_builder (Optional[Callable]) – Function to build right pane content.

• theme_name (str) – Name of the theme to use (“light”, “dark”, “blue”, “native”).

• theme – Alternative parameter for theme_name (supports ThemeType enum).

• enable_animations (bool) – Whether to enable smooth animations.

• menu_bar (Optional[tk.Menu]) – Menu bar to attach to the parent window.

• show_status_bar (bool) – Whether to show a status bar at the bottom.

• show_toolbar (bool) – Whether to show a toolbar at the top.

• **kwargs – Additional keyword arguments passed to tk.Frame.

add_status_widget(widget)

Add a widget to the status bar.

add_toolbar_button(text, command, tooltip='')

Add a button to the toolbar.

Parameters:

• text (str) – The text to display on the button.

• command – The function to call when the button is clicked.

• tooltip (str) – Tooltip text for the button (currently unused but reserved).

clear_pane_fixed_width(pane_side)

Remove fixed width constraint from a pane.

Parameters:

pane_side (str)

clear_toolbar()

Clear all buttons from the toolbar.

create_themed_scrollbar(parent, orient='vertical', command=None, **kwargs)

Create a platform-appropriate themed scrollbar.

This method automatically chooses between custom and native scrollbars based on the current platform for optimal user experience.

Parameters:

• parent – Parent widget

• orient – Scrollbar orientation (“vertical” or “horizontal”)

• command – Scroll command callback

• **kwargs – Additional arguments

Returns:

Scrollbar widget (custom or native based on platform)

get_available_themes()

Get list of available theme names.

Returns:

List of theme names that can be used with switch_theme().

Return type:

list

get_center_frame()

Get the center pane content frame.

get_left_frame()

Get the left pane content frame.

get_pane_content_frame(pane_side)

Get the content frame for a specific pane.

This method provides access to the frame where pane content is displayed, useful for adding widgets or updating content dynamically.

Parameters:

pane_side (str) – Which pane to get (‘left’, ‘center’, ‘right’).

Returns:

The content frame for the specified pane, or None if not found.

Return type:

Optional[tk.Frame]

get_pane_frame(pane_side)

Get the content frame for a pane.

Parameters:

pane_side (str)

Return type:

Frame | None

get_pane_width(pane_side)

Get the current width of a pane.

Parameters:

pane_side (str)

Return type:

int

get_platform_info()

Get platform information including recommended scrollbar type.

Returns:

Dictionary containing platform details such as:

• ’platform’: Operating system name

• ’scrollbar_type’: Recommended scrollbar type for this platform

• Other platform-specific information

Return type:

Dict[str, str]

get_right_frame()

Get the right pane content frame.

get_status_text()

Get the current status bar text.

Return type:

str

get_theme_name()

Get the current theme name.

Return type:

str

hide_center_pane()

Hide the center pane.

hide_left_pane()

Hide the left pane.

hide_right_pane()

Hide the right pane.

is_pane_detached(pane_side)

Check if a pane is detached.

Parameters:

pane_side (str)

Return type:

bool

is_pane_fixed_width(pane_side)

Check if a pane has fixed width.

Parameters:

pane_side (str)

Return type:

bool

is_pane_visible(pane_side)

Check if a pane is currently visible.

Parameters:

pane_side (str) – Which pane to check (‘left’, ‘center’, ‘right’).

Returns:

True if the pane is visible (either attached or detached), False otherwise.

Return type:

bool

refresh_ui()

Refresh the entire UI (useful after theme changes).

set_pane_fixed_width(pane_side, width)

Set a pane to have a fixed width.

Parameters:

• pane_side (str)

• width (int)

set_status_text(text)

Set the status bar text (alias for update_status).

Parameters:

text (str)

set_theme(theme_name)

Change the theme.

show_center_pane()

Show the center pane if it’s hidden.

show_left_pane()

Show the left pane if it’s hidden.

show_right_pane()

Show the right pane if it’s hidden.

switch_theme(theme_name, update_status=True)

Switch to a new theme and automatically update all widgets.

Parameters:

• theme_name (str) – Name of the theme to switch to

• update_status (bool) – Whether to update the status bar with theme info

Returns:

True if theme was successfully switched, False otherwise

Return type:

bool

toggle_center_pane()

Toggle the visibility of the center pane.

toggle_left_pane()

Toggle the visibility of the left pane.

toggle_right_pane()

Toggle the visibility of the right pane.

update_status(message)

Update the status bar message.

Parameters:

message (str)

class threepanewindows.enhanced_dockable.PaneConfig(title='', icon='', window_icon='', custom_titlebar=False, custom_titlebar_shadow=True, show_in_taskbar=True, detached_height=0, detached_scrollable=True, min_width=100, max_width=500, default_width=200, resizable=True, detachable=True, closable=False, fixed_width=None)

Bases: object

Configuration for a pane in the three-pane window.

This class defines all the visual and behavioral properties for a pane, including its title, icon, sizing constraints, and interaction capabilities.

Parameters:

• title (str)

• icon (str)

• window_icon (str)

• custom_titlebar (bool)

• custom_titlebar_shadow (bool)

• show_in_taskbar (bool)

• detached_height (int)

• detached_scrollable (bool)

• min_width (int)

• max_width (int)

• default_width (int)

• resizable (bool)

• detachable (bool)

• closable (bool)

• fixed_width (int | None)

closable: bool = False

custom_titlebar: bool = False

custom_titlebar_shadow: bool = True

default_width: int = 200

detachable: bool = True

detached_height: int = 0

detached_scrollable: bool = True

fixed_width: int | None = None

icon: str = ''

max_width: int = 500

min_width: int = 100

resizable: bool = True

show_in_taskbar: bool = True

title: str = ''

window_icon: str = ''

class threepanewindows.enhanced_dockable.PaneHeader(parent, config, pane_side, on_detach, on_close, theme_manager, **kwargs)

Bases: Frame

Professional pane header with title, icon, and controls.

Initialize pane header with configuration and callbacks.

Parameters:

• config (PaneConfig)

• pane_side (str)

• on_detach (Callable)

• on_close (Callable | None)

• theme_manager (ThemeManager)

refresh_theme()

Refresh the header with the current theme.

threepanewindows.enhanced_dockable.get_recommended_icon_formats()

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.enhanced_dockable.validate_icon_path(icon_path)

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]

EnhancedDockableThreePaneWindow

class threepanewindows.EnhancedDockableThreePaneWindow(master=None, left_config=None, center_config=None, right_config=None, left_builder=None, center_builder=None, right_builder=None, theme_name='light', theme=None, enable_animations=True, menu_bar=None, show_status_bar=False, show_toolbar=False, **kwargs)

Bases: Frame

Enhanced professional dockable three-pane window with theming and advanced UI.

Features: - Professional theming system - Drag-and-drop detaching - Smooth animations - Customizable pane configurations - Professional visual feedback

Initialize enhanced dockable three-pane window with configuration options.

Parameters:

• master – Parent widget (usually the root window).

• left_config (Optional[PaneConfig]) – Configuration for the left pane.

• center_config (Optional[PaneConfig]) – Configuration for the center pane.

• right_config (Optional[PaneConfig]) – Configuration for the right pane.

• left_builder (Optional[Callable]) – Function to build left pane content.

• center_builder (Optional[Callable]) – Function to build center pane content.

• right_builder (Optional[Callable]) – Function to build right pane content.

• theme_name (str) – Name of the theme to use (“light”, “dark”, “blue”, “native”).

• theme – Alternative parameter for theme_name (supports ThemeType enum).

• enable_animations (bool) – Whether to enable smooth animations.

• menu_bar (Optional[tk.Menu]) – Menu bar to attach to the parent window.

• show_status_bar (bool) – Whether to show a status bar at the bottom.

• show_toolbar (bool) – Whether to show a toolbar at the top.

• **kwargs – Additional keyword arguments passed to tk.Frame.

add_status_widget(widget)

Add a widget to the status bar.

add_toolbar_button(text, command, tooltip='')

Add a button to the toolbar.

Parameters:

• text (str) – The text to display on the button.

• command – The function to call when the button is clicked.

• tooltip (str) – Tooltip text for the button (currently unused but reserved).

clear_pane_fixed_width(pane_side)

Remove fixed width constraint from a pane.

Parameters:

pane_side (str)

clear_toolbar()

Clear all buttons from the toolbar.

create_themed_scrollbar(parent, orient='vertical', command=None, **kwargs)

Create a platform-appropriate themed scrollbar.

This method automatically chooses between custom and native scrollbars based on the current platform for optimal user experience.

Parameters:

• parent – Parent widget

• orient – Scrollbar orientation (“vertical” or “horizontal”)

• command – Scroll command callback

• **kwargs – Additional arguments

Returns:

Scrollbar widget (custom or native based on platform)

get_available_themes()

Get list of available theme names.

Returns:

List of theme names that can be used with switch_theme().

Return type:

list

get_center_frame()

Get the center pane content frame.

get_left_frame()

Get the left pane content frame.

get_pane_content_frame(pane_side)

Get the content frame for a specific pane.

This method provides access to the frame where pane content is displayed, useful for adding widgets or updating content dynamically.

Parameters:

pane_side (str) – Which pane to get (‘left’, ‘center’, ‘right’).

Returns:

The content frame for the specified pane, or None if not found.

Return type:

Optional[tk.Frame]

get_pane_frame(pane_side)

Get the content frame for a pane.

Parameters:

pane_side (str)

Return type:

Frame | None

get_pane_width(pane_side)

Get the current width of a pane.

Parameters:

pane_side (str)

Return type:

int

get_platform_info()

Get platform information including recommended scrollbar type.

Returns:

Dictionary containing platform details such as:

• ’platform’: Operating system name

• ’scrollbar_type’: Recommended scrollbar type for this platform

• Other platform-specific information

Return type:

Dict[str, str]

get_right_frame()

Get the right pane content frame.

get_status_text()

Get the current status bar text.

Return type:

str

get_theme_name()

Get the current theme name.

Return type:

str

hide_center_pane()

Hide the center pane.

hide_left_pane()

Hide the left pane.

hide_right_pane()

Hide the right pane.

is_pane_detached(pane_side)

Check if a pane is detached.

Parameters:

pane_side (str)

Return type:

bool

is_pane_fixed_width(pane_side)

Check if a pane has fixed width.

Parameters:

pane_side (str)

Return type:

bool

is_pane_visible(pane_side)

Check if a pane is currently visible.

Parameters:

pane_side (str) – Which pane to check (‘left’, ‘center’, ‘right’).

Returns:

True if the pane is visible (either attached or detached), False otherwise.

Return type:

bool

refresh_ui()

Refresh the entire UI (useful after theme changes).

set_pane_fixed_width(pane_side, width)

Set a pane to have a fixed width.

Parameters:

• pane_side (str)

• width (int)

set_status_text(text)

Set the status bar text (alias for update_status).

Parameters:

text (str)

set_theme(theme_name)

Change the theme.

show_center_pane()

Show the center pane if it’s hidden.

show_left_pane()

Show the left pane if it’s hidden.

show_right_pane()

Show the right pane if it’s hidden.

switch_theme(theme_name, update_status=True)

Switch to a new theme and automatically update all widgets.

Parameters:

• theme_name (str) – Name of the theme to switch to

• update_status (bool) – Whether to update the status bar with theme info

Returns:

True if theme was successfully switched, False otherwise

Return type:

bool

toggle_center_pane()

Toggle the visibility of the center pane.

toggle_left_pane()

Toggle the visibility of the left pane.

toggle_right_pane()

Toggle the visibility of the right pane.

update_status(message)

Update the status bar message.

Parameters:

message (str)

PaneConfig

class threepanewindows.PaneConfig(title='', icon='', window_icon='', custom_titlebar=False, custom_titlebar_shadow=True, show_in_taskbar=True, detached_height=0, detached_scrollable=True, min_width=100, max_width=500, default_width=200, resizable=True, detachable=True, closable=False, fixed_width=None)

Bases: object

Configuration for a pane in the three-pane window.

This class defines all the visual and behavioral properties for a pane, including its title, icon, sizing constraints, and interaction capabilities.

Parameters:

• title (str)

• icon (str)

• window_icon (str)

• custom_titlebar (bool)

• custom_titlebar_shadow (bool)

• show_in_taskbar (bool)

• detached_height (int)

• detached_scrollable (bool)

• min_width (int)

• max_width (int)

• default_width (int)

• resizable (bool)

• detachable (bool)

• closable (bool)

• fixed_width (int | None)

closable: bool = False

custom_titlebar: bool = False

custom_titlebar_shadow: bool = True

default_width: int = 200

detachable: bool = True

detached_height: int = 0

detached_scrollable: bool = True

fixed_width: int | None = None

icon: str = ''

max_width: int = 500

min_width: int = 100

resizable: bool = True

show_in_taskbar: bool = True

title: str = ''

window_icon: str = ''

Cross-Platform Icon Support

The enhanced dockable window supports cross-platform icon display for detached windows with automatic format detection and fallback mechanisms.

Supported Icon Formats

• Windows: .ico (primary), .png, .bmp, .gif (secondary)

• macOS: .png (primary), .gif, .bmp (secondary), .ico (limited)

• Linux: .png, .xbm (primary), .gif, .bmp (secondary), .ico (limited)

Icon Resolution Strategy

1. Check file existence

2. Detect format from extension

3. Use best method for format (iconbitmap for .ico, iconphoto for others)

4. Fallback to alternative methods if primary fails

5. Continue without icon if all methods fail

Example Usage

from threepanewindows.enhanced_dockable import (
    PaneConfig,
    get_recommended_icon_formats,
    validate_icon_path
)

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

# Validate icon before use
is_valid, message = validate_icon_path("icons/app.png")
if is_valid:
    config = PaneConfig(
        title="My Panel",
        icon="🔧",                    # Unicode icon for header
        window_icon="icons/app.png"   # File icon for detached window
    )

Icon Utility Functions

threepanewindows.enhanced_dockable.get_recommended_icon_formats()

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.enhanced_dockable.validate_icon_path(icon_path)

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]