Image Studio GUI Module

The image_studio module provides the main GUI application class and related components for the GUI Image Studio application.

Enhanced Image Studio GUI for gui_image_studio package using threepanewindows. A visual tool for developers to design images/icons and generate embedded code. Features detachable left and right panels with fixed width. FUNCTIONALITY IS IDENTICAL TO THE ORIGINAL - ONLY THE UI LAYOUT USES THREEPANEWINDOWS.

class gui_image_studio.image_studio.EnhancedImageDesignerGUI

Bases: object

Main GUI application for image design and code generation.

setup_button_styles()

Setup custom button styles for prominent display.

setup_ui()

Setup the enhanced user interface with threepanewindows.

build_left_panel(parent)

Build the left panel with tools and image management.

build_center_panel(parent)

Build the center panel with the drawing canvas.

build_right_panel(parent)

Build the right panel with properties and code generation.

setup_menu()

Setup the menu bar.

setup_left_panel(parent)

Setup the left panel with tools and image management.

setup_center_panel(parent)

Setup the center panel with the drawing canvas.

setup_right_panel(parent)

Setup the right panel with properties and code generation.

setup_bindings()

Setup event bindings.

select_tool(tool)

Select a drawing tool.

update_tool_cursor(tool)

Update the canvas cursor based on the selected tool and user settings.

get_cursor_fallback_options(tool)

Get fallback cursor options based on tool, platform, and handedness.

load_cursor_settings()

Load cursor settings from file.

save_cursor_settings()

Save cursor settings to file.

reset_cursor_settings()

Reset cursor settings to defaults.

open_cursor_settings()

Open the cursor settings dialog.

choose_color()

Open color chooser dialog.

new_image()

Create a new blank image.

load_image()

Load an image from file.

duplicate_image()

Duplicate the selected image.

delete_image()

Delete the selected image.

update_image_list()

Update the image list display.

update_ui_state()

Update UI elements based on current state.

update_preview(event=None)

Update the live preview based on current settings.

generate_preview(framework, usage_type)

Generate visual preview for the selected framework and usage type.

preview_buttons(preview_images, framework)

Preview images as buttons.

preview_icons(preview_images, framework)

Preview images as icons.

preview_backgrounds(preview_images, framework)

Preview images as backgrounds.

preview_sprites(preview_images, framework)

Preview images as game sprites.

preview_ui_elements(preview_images, framework)

Preview images as UI elements.

preview_general(preview_images, framework)

Preview images in general layout.

clear_canvas()

Clear the current canvas.

reset_zoom()

Reset zoom to 100%.

fit_to_window()

Fit image to window size.

show_quick_start()

Show quick start guide.

show_tools_help()

Show drawing tools help.

show_code_help()

Show code generation help.

show_shortcuts()

Show keyboard shortcuts.

show_tips()

Show tips and tricks.

show_troubleshooting()

Show troubleshooting guide.

show_about()

Show about dialog.

get_quick_start_content()

Get quick start guide content.

get_tools_help_content()

Get drawing tools help content.

get_code_help_content()

Get code generation help content.

get_shortcuts_content()

Get keyboard shortcuts content.

get_tips_content()

Get tips and tricks content.

get_troubleshooting_content()

Get troubleshooting content.

get_about_content()

Get about dialog content.

select_image(name)

Select an image for editing.

update_canvas()

Update the canvas display.

show_canvas_instructions()

Show instructions on empty canvas.

on_image_select(event)

Handle image selection from listbox.

on_name_change(event)

Handle image name change.

on_canvas_click(event)

Handle canvas click events.

on_canvas_drag(event)

Handle canvas drag events.

on_canvas_release(event)

Handle canvas release events.

on_canvas_motion(event)

Handle canvas motion events for shape preview and pixel highlighting.

update_shape_preview(x1, y1, x2, y2)

Update the preview shape on canvas.

clear_preview()

Clear the preview shape from canvas.

update_pixel_highlight(x, y)

Highlight the pixel that will be affected by drawing tools.

clear_pixel_highlight()

Clear the pixel highlight from canvas.

draw_on_image(x, y)

Draw on the current image.

draw_shape(x1, y1, x2, y2)

Draw a shape on the current image.

add_text(x, y)

Add text to the current image.

draw_line_on_image(x1, y1, x2, y2)

Draw a line on the current image.

resize_image()

Resize the current image.

zoom_in()

Zoom in on the canvas.

zoom_out()

Zoom out on the canvas.

zoom_fit()

Fit image to canvas.

toggle_grid()

Toggle grid display.

draw_grid(display_size)

Draw grid on canvas.

apply_blur()

Apply blur filter to current image.

apply_sharpen()

Apply sharpen filter to current image.

apply_emboss()

Apply emboss filter to current image.

apply_rotation(*args)

Apply rotation to current image based on rotation scale.

preview_code()

Preview the generated embedded code.

generate_code_file()

Generate the embedded code file.

export_images()

Export images to a folder.

toggle_left_panel()

Toggle left panel visibility.

toggle_right_panel()

Toggle right panel visibility.

reset_panel_layout()

Reset panel layout to default.

run()

Run the application.

class gui_image_studio.image_studio.ImageSizeDialog(parent)

Bases: object

Dialog for creating new images with custom size.

setup_ui()

Setup the dialog UI.

create()

Create the image.

cancel()

Cancel the dialog.

class gui_image_studio.image_studio.CodePreviewWindow(parent, code_content, framework, usage_type='general')

Bases: object

Window for previewing generated code.

setup_ui(code_content)

Setup the preview window UI.

generate_enhanced_code(base_code)

Generate enhanced code with usage examples.

get_usage_examples()

Get usage examples based on framework and usage type.

copy_to_clipboard(content)

Copy content to clipboard.

class gui_image_studio.image_studio.HelpWindow(parent, title, content)

Bases: object

Window for displaying help content.

setup_ui(content)

Setup the help window UI.

insert_formatted_content(content)

Insert content with basic formatting.

center_window()

Center the window on the screen.

print_content()

Print the help content.

copy_content()

Copy all content to clipboard.

class gui_image_studio.image_studio.CursorSettingsDialog(parent, app)

Bases: object

Dialog for configuring cursor settings.

setup_ui()

Set up the cursor settings dialog UI.

setup_general_tab(parent)

Set up the general settings tab.

setup_tools_tab(parent)

Set up the tool cursors tab.

setup_custom_tab(parent)

Set up the custom cursors tab.

setup_available_tab(parent)

Set up the available cursors tab.

get_available_cursors()

Get list of available cursors for the platform.

update_cursor_preview(tool)

Update the cursor preview for a specific tool.

draw_cursor_preview(canvas, cursor_name)

Draw a visual representation of the cursor.

draw_arrow_cursor(canvas)

Draw arrow cursor representation.

draw_crosshair_cursor(canvas)

Draw crosshair cursor representation.

draw_dotbox_cursor(canvas)

Draw dotbox cursor representation.

draw_pencil_cursor(canvas)

Draw pencil cursor representation.

draw_spraycan_cursor(canvas)

Draw spraycan cursor representation.

draw_xterm_cursor(canvas)

Draw xterm cursor representation.

draw_plus_cursor(canvas)

Draw plus cursor representation.

draw_hand_cursor(canvas)

Draw hand cursor representation.

draw_watch_cursor(canvas)

Draw watch cursor representation.

draw_target_cursor(canvas)

Draw target cursor representation.

draw_tcross_cursor(canvas)

Draw tcross cursor representation.

refresh_custom_list()

Refresh the custom cursors list.

test_cursor(tool)

Test the cursor for a specific tool.

test_specific_cursor(cursor)

Test a specific cursor.

test_current_cursor()

Test the cursor for the currently selected tool.

add_custom_cursor()

Add a new custom cursor.

edit_custom_cursor()

Edit the selected custom cursor.

delete_custom_cursor()

Delete the selected custom cursor.

reset_to_defaults()

Reset all settings to defaults.

apply_settings()

Apply the current settings.

ok()

Apply settings and close dialog.

cancel()

Close dialog without applying changes.

class gui_image_studio.image_studio.CustomCursorDialog(parent, settings_dialog, cursor_name=None)

Bases: object

Dialog for creating/editing custom cursors.

setup_ui()

Set up the custom cursor dialog UI.

load_cursor_data()

Load existing cursor data for editing.

update_preview(event=None)

Update the cursor preview.

browse_file()

Browse for a cursor file.

test_cursor()

Test the custom cursor.

save_cursor()

Save the custom cursor.

cancel()

Cancel and close dialog.

class gui_image_studio.image_studio.CursorTestWindow(parent, app, cursor)

Bases: object

Window for testing cursors interactively.

setup_ui()

Set up the cursor test window UI.

apply_cursor()

Apply the test cursor to the main canvas.

restore_cursor()

Restore the original cursor.

apply_to_tool()

Apply this cursor to the current tool.

close_window()

Close the test window and restore original cursor.

gui_image_studio.image_studio.main()

Main entry point for the Enhanced Image Studio GUI.

Main Application Class

ImageStudio

The main GUI application class that provides a complete image editing interface.

Initialization:

import tkinter as tk
from gui_image_studio import ImageStudio

root = tk.Tk()
app = ImageStudio(root)
app.pack(fill=tk.BOTH, expand=True)
root.mainloop()

Key Features:

• Professional image editing interface

• Real-time preview capabilities

• Undo/redo functionality

• Theme support (light/dark)

• Plugin architecture

• Batch processing tools

• Animation timeline (for GIFs)

Main Components:

• Canvas Area: Central image display and editing area

• Tool Palette: Left sidebar with editing tools

• Properties Panel: Right sidebar with tool settings

• Menu Bar: Standard application menus

• Status Bar: Information and progress display

• Timeline: Animation frame management (when applicable)

Methods:

load_image

Load an image into the editor.

Parameters:

• file_path (str, optional): Path to image file. If None, opens file dialog.

Example:

# Load specific file
app.load_image("photo.jpg")

# Open file dialog
app.load_image()

save_image

Save the current image.

Parameters:

• file_path (str, optional): Path for saving. If None, opens save dialog.

• quality (int, optional): JPEG quality (1-100, default 95)

Example:

# Save to specific file
app.save_image("output.png")

# Open save dialog
app.save_image()

apply_filter

Apply a filter to the current image.

Parameters:

• filter_name (str): Name of the filter to apply

• parameters (dict, optional): Filter-specific parameters

Example:

# Apply blur filter
app.apply_filter("blur", {"radius": 2.0})

# Apply tint
app.apply_filter("tint", {"color": "#FF6B6B", "opacity": 0.3})

undo

Undo the last operation.

Example:

app.undo()

redo

Redo the last undone operation.

Example:

app.redo()

set_theme

Change the application theme.

Parameters:

• theme_name (str): Theme name (“light”, “dark”, or custom theme)

Example:

app.set_theme("dark")

GUI Components

ToolPalette

Left sidebar containing editing tools.

Available Tools:

• Selection Tools: Rectangle, ellipse, lasso, magic wand

• Drawing Tools: Brush, pencil, eraser, fill bucket

• Transform Tools: Move, rotate, scale, crop

• Filter Tools: Quick access to common filters

Usage:

# Access current tool
current_tool = app.tool_palette.current_tool

# Set tool programmatically
app.tool_palette.set_tool("brush")

PropertiesPanel

Right sidebar showing tool properties and image information.

Sections:

• Tool Properties: Settings for the current tool

• Image Information: Size, format, color mode

• History: Recent operations

• Layers: Layer management (if supported)

Usage:

# Get image info
info = app.properties_panel.get_image_info()
print(f"Size: {info['size']}, Format: {info['format']}")

ImageCanvas

Central canvas area for image display and editing.

Features:

• Zoom and pan capabilities

• Real-time editing preview

• Grid and ruler overlays

• Selection visualization

• Multi-layer support

Usage:

# Zoom operations
app.canvas.zoom_in()
app.canvas.zoom_out()
app.canvas.fit_to_window()

# Get canvas state
zoom_level = app.canvas.get_zoom_level()
selection = app.canvas.get_selection()

Timeline

Animation timeline for GIF editing (shown when working with animated images).

Features:

• Frame-by-frame editing

• Timing adjustment

• Onion skinning

• Playback controls

Usage:

# Timeline operations (when animation is loaded)
app.timeline.add_frame()
app.timeline.delete_frame(frame_index)
app.timeline.set_frame_duration(frame_index, 100)  # 100ms

Event System

The ImageStudio class uses an event-driven architecture for communication between components.

Event Types:

• image_loaded: Fired when a new image is loaded

• image_modified: Fired when the image is changed

• tool_changed: Fired when the active tool changes

• selection_changed: Fired when the selection changes

Event Handling:

def on_image_loaded(event_data):
    print(f"Image loaded: {event_data['file_path']}")

# Subscribe to events
app.subscribe("image_loaded", on_image_loaded)

# Fire custom events
app.fire_event("custom_event", {"data": "value"})

Customization

Custom Tools

Create custom tools by extending the base Tool class:

from gui_image_studio.image_studio import Tool

class CustomTool(Tool):
    def __init__(self):
        super().__init__("Custom Tool", "custom_icon.png")

    def on_mouse_down(self, x, y):
        # Handle mouse down event
        pass

    def on_mouse_drag(self, x, y):
        # Handle mouse drag event
        pass

    def on_mouse_up(self, x, y):
        # Handle mouse up event
        pass

# Register the tool
app.tool_palette.register_tool(CustomTool())

Custom Filters

Create custom filters:

from gui_image_studio.image_studio import Filter

class CustomFilter(Filter):
    def __init__(self):
        super().__init__("Custom Filter", "custom_filter")

    def apply(self, image, parameters=None):
        # Apply custom processing
        processed_image = self.process_image(image, parameters)
        return processed_image

# Register the filter
app.register_filter(CustomFilter())

Custom Themes

Create custom themes:

custom_theme = {
    "name": "custom_theme",
    "colors": {
        "bg_primary": "#2B2B2B",
        "bg_secondary": "#3C3C3C",
        "fg_primary": "#FFFFFF",
        "fg_secondary": "#CCCCCC",
        "accent": "#007ACC",
        "border": "#555555"
    },
    "fonts": {
        "default": ("Segoe UI", 9),
        "heading": ("Segoe UI", 12, "bold"),
        "monospace": ("Consolas", 9)
    }
}

app.register_theme(custom_theme)
app.set_theme("custom_theme")

Configuration

Application Settings

Configure the application behavior:

# Set default settings
app.settings.update({
    "auto_save": True,
    "auto_save_interval": 300,  # 5 minutes
    "max_undo_levels": 50,
    "default_quality": 95,
    "show_grid": False,
    "grid_size": 10
})

Keyboard Shortcuts

Customize keyboard shortcuts:

# Default shortcuts
shortcuts = {
    "Ctrl+O": "open_file",
    "Ctrl+S": "save_file",
    "Ctrl+Z": "undo",
    "Ctrl+Y": "redo",
    "Ctrl++": "zoom_in",
    "Ctrl+-": "zoom_out",
    "Ctrl+0": "fit_to_window"
}

app.set_shortcuts(shortcuts)

Performance Considerations

Memory Management

• Large images are automatically tiled for display

• Undo history is limited to prevent memory issues

• Temporary files are cleaned up automatically

Threading

• Long operations run in background threads

• Progress indicators show operation status

• UI remains responsive during processing

Optimization Tips

# Optimize for large images
app.settings["tile_size"] = 512  # Smaller tiles for large images
app.settings["preview_quality"] = "fast"  # Faster preview rendering

# Optimize for performance
app.settings["real_time_preview"] = False  # Disable for complex operations
app.settings["max_image_size"] = (4096, 4096)  # Limit maximum image size

Error Handling

The ImageStudio class provides comprehensive error handling:

Common Exceptions:

• ImageStudioError: Base exception for application errors

• UnsupportedFormatError: Unsupported image format

• InsufficientMemoryError: Not enough memory for operation

• OperationCancelledError: User cancelled operation

Error Handling Example:

try:
    app.load_image("large_image.jpg")
except gui_image_studio.UnsupportedFormatError:
    print("Image format not supported")
except gui_image_studio.InsufficientMemoryError:
    print("Not enough memory to load image")
except Exception as e:
    print(f"Unexpected error: {e}")

Error Recovery:

The application includes automatic error recovery:

• Corrupted files are handled gracefully

• Memory errors trigger cleanup and retry

• UI state is preserved during errors

• Auto-save prevents data loss

Integration Examples

Embedding in Existing Applications

import tkinter as tk
from gui_image_studio import ImageStudio

class MyApplication:
    def __init__(self):
        self.root = tk.Tk()
        self.setup_ui()

    def setup_ui(self):
        # Create main frame
        main_frame = tk.Frame(self.root)
        main_frame.pack(fill=tk.BOTH, expand=True)

        # Add other components
        toolbar = tk.Frame(main_frame)
        toolbar.pack(side=tk.TOP, fill=tk.X)

        # Embed ImageStudio
        self.image_studio = ImageStudio(main_frame)
        self.image_studio.pack(fill=tk.BOTH, expand=True)

        # Connect to events
        self.image_studio.subscribe("image_loaded", self.on_image_loaded)

    def on_image_loaded(self, event_data):
        # Handle image loaded event
        print(f"Image loaded in embedded editor: {event_data['file_path']}")

Plugin Development

from gui_image_studio.image_studio import Plugin

class MyPlugin(Plugin):
    def __init__(self):
        super().__init__("My Plugin", "1.0.0")

    def initialize(self, app):
        # Add menu items
        app.add_menu_item("Plugins", "My Plugin", self.run_plugin)

        # Add toolbar button
        app.add_toolbar_button("My Plugin", "plugin_icon.png", self.run_plugin)

    def run_plugin(self):
        # Plugin functionality
        current_image = self.app.get_current_image()
        if current_image:
            processed = self.process_image(current_image)
            self.app.set_current_image(processed)

# Register plugin
app.register_plugin(MyPlugin())