Developer Guide: GUI Internals

This document provides technical details about the implementation of the Graphical User Interface (GUI) for developers.

Framework

The GUI is built using PySide6, which provides Python bindings for the Qt framework.

Main Window (`gui/main_window.py`)

The MainWindow class is the central component of the GUI application. It is responsible for:

Defining the main application window structure and layout using PySide6 widgets.
Arranging the Preset Editor panel (left) and the Unified Hierarchical View (right).
Setting up the menu bar, including the "View" menu for toggling the Log Console.
Connecting user interactions (button clicks, drag-and-drop events, edits in the Unified View) to corresponding methods (slots) within the MainWindow or other handler classes.
Managing the display of application logs in the UI console using a custom QtLogHandler.
Interacting with background handlers (ProcessingHandler, PredictionHandler, LLMPredictionHandler) via Qt signals and slots to ensure thread-safe updates to the UI during long-running operations.
Accumulating prediction results from either the PredictionHandler (for rule-based presets) or LLMPredictionHandler (for LLM interpretation) for multiple input sources before updating the UnifiedViewModel.
Receiving the initial SourceRule hierarchy from the appropriate prediction handler (rule_hierarchy_ready or llm_prediction_ready signals) and calling the UnifiedViewModel's update_rules_for_sources method to populate the view model.
Sending the final, potentially user-modified, SourceRule list to main.py to initiate processing via the ProcessingEngine.
Handling the selection in the processing preset dropdown (self.preset_selector), distinguishing between standard presets and the special "- LLM Interpretation -" value.
Initializing and managing the self.llm_processing_queue (a deque) when LLM interpretation is selected, adding items to be processed by the LLM.
Implementing the _start_llm_prediction method to initiate the LLM prediction process for the queued items by calling _process_next_llm_item.
Implementing the _process_next_llm_item method, which takes the next item from the llm_processing_queue, prepares the necessary data, and starts the LLMPredictionHandler thread to process that single item.
Connecting signals from the LLMPredictionHandler instance:
- llm_prediction_ready signal to a slot (e.g., _on_llm_prediction_ready) that receives the generated SourceRule, updates the UnifiedViewModel (via update_rules_for_sources), and calls _process_next_llm_item to continue processing the queue.
- llm_status_update signal to a slot (e.g., _on_llm_status_update) to display LLM processing status messages in the status bar.
- finished signal to handle thread cleanup.

Threading and Background Tasks

To keep the UI responsive during intensive operations like asset processing and rule prediction, the GUI utilizes background threads managed by QThread.

ProcessingHandler (gui/processing_handler.py): This class is designed to run in a separate QThread. It manages the execution of the main asset processing pipeline using the ProcessingEngine for multiple assets concurrently using concurrent.futures.ProcessPoolExecutor. It submits individual asset processing tasks to the pool, passing the relevant SourceRule object and Configuration instance to the ProcessingEngine. It monitors task completion and communicates progress, status updates, and results back to the MainWindow on the main UI thread using Qt signals. It also handles the execution of optional Blender scripts via subprocess calls after processing.
PredictionHandler (gui/prediction_handler.py): Runs in a QThread when a rule-based preset is selected. Generates the initial SourceRule hierarchy based on preset rules and emits rule_hierarchy_ready.
LLMPredictionHandler (gui/llm_prediction_handler.py): Runs in a QThread when "- LLM Interpretation -" is selected. Communicates with the LLM API, parses the response, generates the SourceRule hierarchy for a single input item at a time, and emits llm_prediction_ready and llm_status_update.

Communication (Signals and Slots)

Communication between the main UI thread (MainWindow) and the background threads (ProcessingHandler, PredictionHandler, LLMPredictionHandler) relies heavily on Qt's signals and slots mechanism. This is a thread-safe way for objects in different threads to communicate.

Background handlers emit signals to indicate events (e.g., progress updated, file status changed, task finished, prediction ready, LLM status update).
The MainWindow connects slots (methods) to these signals. When a signal is emitted, the connected slot is invoked on the thread that owns the receiving object (the main UI thread for MainWindow), ensuring UI updates happen safely. Key signals/slots related to LLM integration:
- LLMPredictionHandler.llm_prediction_ready(source_id, source_rule_list) -> MainWindow._on_llm_prediction_ready(source_id, source_rule_list) (updates model via update_rules_for_sources, processes next queue item)
- LLMPredictionHandler.llm_status_update(message) -> MainWindow._on_llm_status_update(message) (updates status bar)
- LLMPredictionHandler.finished -> MainWindow._on_llm_thread_finished (handles thread cleanup)

Preset Editor

The GUI includes an integrated preset editor panel. This allows users to interactively create, load, modify, and save preset .json files directly within the application. The editor typically uses standard UI widgets to display and edit the key fields of the preset structure.

Unified Hierarchical View (`gui/unified_view_model.py`, `gui/delegates.py`)

Unified Hierarchical View (`gui/unified_view_model.py`, `gui/delegates.py`, `gui/main_window.py`)

The core of the GUI's rule editing interface is the Unified Hierarchical View, implemented using a QTreeView with a custom model and delegates. This view is managed within the MainWindow.

Unified View Model (gui/unified_view_model.py): This class implements a QAbstractItemModel to expose the structure of a list of SourceRule objects (Source -> Asset -> File) to the QTreeView. It holds the SourceRule data that is the single source of truth for the GUI's processing rules. It provides data and flags for display in multiple columns and supports inline editing of specific rule attributes (e.g., asset type, item type override, target asset name override) by interacting with delegates.
- Column Order and Resizing: The view currently displays the following columns in order: Name, Target Asset, Supplier, Asset Type, Item Type. The "Target Asset" column is set to stretch to fill available space, while other columns resize to their contents. The previous "Status" and "Output Path" columns have been removed.
- Direct Model Restructuring: The setData method now includes logic to directly restructure the underlying SourceRule hierarchy when the target_asset_name_override field of a FileRule is edited. This involves moving the FileRule to a different AssetRule (creating a new one if necessary) and removing the old AssetRule if it becomes empty. This replaces the previous mechanism of re-running prediction after an edit.
- Row Coloring: Row background colors are dynamically determined based on the asset_type (for AssetRules) and item_type or item_type_override (for FileRules), using the color metadata defined in the ASSET_TYPE_DEFINITIONS and FILE_TYPE_DEFINITIONS dictionaries sourced from the configuration loaded by configuration.py (which includes data from config/app_settings.json). SourceRule rows have a fixed color.
Delegates (gui/delegates.py): This module contains custom QStyledItemDelegate implementations used by the QTreeView to provide inline editors for specific data types or rule attributes.
- ComboBoxDelegate: Used for selecting from predefined lists (e.g., allowed asset types, allowed file types sourced from the configuration loaded by configuration.py).
- LineEditDelegate: Used for free-form text editing (e.g., target asset name override).
- SupplierSearchDelegate: A new delegate used for the "Supplier" column. It provides a QLineEdit with auto-completion suggestions loaded from config/suppliers.json. It also handles adding new, unique supplier names entered by the user to the list and saving the updated list back to the JSON file.

The appropriate prediction handler (PredictionHandler or LLMPredictionHandler) generates the initial SourceRule hierarchy (either for all sources at once or one source at a time for LLM). The MainWindow receives this via a signal (rule_hierarchy_ready or llm_prediction_ready) and calls the UnifiedViewModel's update_rules_for_sources(source_id, source_rule_list) method. This method updates the model's internal data structure with the new or updated SourceRule object(s) for the given source_id and emits the necessary signals (dataChanged, layoutChanged) to refresh the QTreeView display. Edits made in the view directly modify the attributes of the underlying rule objects in the SourceRule hierarchy held by the model, with the UnifiedViewModel handling the necessary model restructuring and signal emission for view updates.

Data Flow Diagram (GUI Rule Management):

graph LR
    A[User Input (Drag/Drop, Preset Select)] --> B(MainWindow);
    B -- Selects Preset/LLM --> B;
    B -- Starts --> C{Prediction Handler (Rule or LLM)};
    C -- rule_hierarchy_ready / llm_prediction_ready --> B;
    B -- Calls update_rules_for_sources(source_id, rules) --> D(UnifiedViewModel);
    D -- Emits dataChanged/layoutChanged --> E(QTreeView - Unified View);
    B -- Sets Model --> E;
    E -- Displays Data from --> D;
    E -- Uses Delegates from --> F(Delegates);
    F -- Interact with --> D;
    User -- Edits Rules via --> E;
    E -- Updates Data in --> D;
    B -- Triggers Processing with Final SourceRule List --> G(main.py / ProcessingHandler);

Application Styling

The application style is explicitly set to 'Fusion' in gui/main_window.py to provide a more consistent look and feel across different operating systems. A custom QPalette is also applied to the application to adjust default colors within the 'Fusion' style.

Logging

A custom QtLogHandler is used to redirect log messages from the standard Python logging module to a text area or console widget within the GUI, allowing users to see detailed application output and errors.

Cancellation

The GUI provides a "Cancel" button to stop ongoing processing. The ProcessingHandler implements logic to handle cancellation requests. This typically involves setting an internal flag and attempting to shut down the ProcessPoolExecutor. However, it's important to note that this does not immediately terminate worker processes that are already executing; it primarily prevents new tasks from starting and stops processing results from completed futures once the cancellation flag is checked.

GUI Configuration Editor (`gui/config_editor_dialog.py`)

A dedicated dialog, implemented in gui/config_editor_dialog.py, provides a graphical interface for editing the core application settings stored in config/app_settings.json.

Functionality: This dialog loads the current content of config/app_settings.json and presents it in a tabbed layout (e.g., "General", "Output & Naming") using standard GUI widgets mapped to the JSON structure. It supports editing basic fields, tables for definitions (FILE_TYPE_DEFINITIONS, ASSET_TYPE_DEFINITIONS), and a list/detail view for merge rules (MAP_MERGE_RULES). The definitions tables include dynamic color editing features.
Limitations: Currently, editing complex fields like IMAGE_RESOLUTIONS or the full details of MAP_MERGE_RULES via the UI is not fully supported.
Integration: The MainWindow is responsible for creating and displaying an instance of this dialog when the user selects the "Edit" -> "Preferences..." menu option.
Persistence: Changes saved via this editor are written directly to the config/app_settings.json file, ensuring they persist across application sessions. However, the Configuration class loads settings at application startup, so a restart is required for changes made in the editor to take effect in the application's processing logic.

These key components work together to provide the tool's functionality, separating concerns and utilizing concurrency for performance and responsiveness. The Unified Hierarchical View centralizes rule management in the GUI, and the SourceRule object serves as a clear data contract passed to the processing engine.

13 KiB Raw Blame History