UI Components Reference

Technical reference for the GUI widgets and components in Chess Analyzer Pro.

Overview

The GUI layer (src/gui/) is built with PyQt6 and follows a modular architecture with reusable components. The main application window orchestrates multiple view pages and widgets.

Application Structure

MainWindow
├── Sidebar (Navigation)
└── QStackedWidget (Page Container)
    ├── Analysis Page
    │   ├── BoardWidget
    │   ├── EvalBarWidget
    │   ├── GraphWidget
    │   ├── MoveListPanel
    │   └── AnalysisPanel
    ├── History Page (HistoryView)
    ├── Stats Page (MetricsWidget)
    └── Settings Page (SettingsView)

Main Window (main_window.py)

The root application container.

Class: MainWindow(QMainWindow)

Responsibilities:

• Window initialization and layout
• Sidebar navigation
• Game loading orchestration
• Analysis control
• Keyboard shortcuts

Key Properties

self.games = []           # Loaded game list
self.current_game = None  # Currently active GameAnalysis
self.current_move = -1    # Currently displayed move index
self.analyzer = None      # Analyzer instance

Key Signals

Key Methods

def setup_ui(self)              # Initialize all UI components
def open_load_dialog(self)      # Open unified LoadGameDialog modal
def _on_game_ready(self, pgn)   # Handle game PGN loaded from dialog
def start_analysis(self)        # Start Stockfish analysis
def on_move_selected(self, idx) # Handle move selection
def go_first/prev/next/last()   # Navigation methods
def flip_board(self)            # Toggle board orientation

Board Components (gui/board/)

BoardWidget (board_widget.py)

Renders the interactive chess board.

Class: BoardWidget(QWidget)

class BoardWidget(QWidget):
    def __init__(self)

Features:

• SVG-based board rendering
• Custom board themes (colors)
• Custom piece themes (SVG sets)
• Move highlighting
• Best move arrows
• Check highlighting
• Board flipping

Key Methods:

def load_game(self, game_analysis)     # Load a new game
def set_position(self, move_index)      # Set board to position after move
def flip_board(self)                    # Toggle orientation
def update_board(self)                  # Refresh board rendering
def draw_overlays(self, move_index)     # Draw arrows and highlights

Theming:

# Board colors from Styles.BOARD_THEMES
colors = {
    "light": "#EEEDD2",
    "dark": "#769656"
}

# Piece SVGs loaded from assets/pieces/{theme}/
piece_files = ["wK.svg", "wQ.svg", "wR.svg", "wB.svg", "wN.svg", "wP.svg",
               "bK.svg", "bQ.svg", "bR.svg", "bB.svg", "bN.svg", "bP.svg"]

EvalBarWidget (eval_bar.py)

Vertical evaluation bar showing advantage.

Class: EvalBarWidget(QWidget)

class EvalBarWidget(QWidget):
    def __init__(self)

Features:

• White/black fill based on evaluation
• Numeric score display
• Mate score formatting
• Smooth transitions

Key Methods:

def set_eval(self, cp=None, mate=None)  # Update evaluation display

Analysis View (analysis_view.py)

The main analysis dashboard layout.

MoveListPanel

Displays the game move list with classifications.

Class: MoveListPanel(QWidget)

class MoveListPanel(QWidget):
    move_selected = pyqtSignal(int)      # Emitted when move is clicked
    lines_updated = pyqtSignal(list, bool)  # Emitted with engine lines

Features:

• Two-column move display (White | Black)
• Classification icons
• Current move highlighting
• Click-to-navigate

Key Methods:

def set_game(self, game_analysis)   # Load game moves
def refresh(self)                   # Rebuild move list
def select_move(self, index)        # Highlight and scroll to move

AnalysisPanel

Displays game statistics and AI summary.

Class: AnalysisPanel(QWidget)

class AnalysisPanel(QWidget):
    cache_toggled = pyqtSignal(bool)   # Cache toggle signal

Features:

• Game info header (players, ratings, result)
• Accuracy display for both sides
• Classification breakdown (counts)
• Engine analysis lines display
• AI Summary section
• Opening name display

Key Methods:

def set_game(self, game_analysis)    # Load game data
def refresh(self)                    # Update displayed stats
def generate_ai_summary(self)        # Request AI summary
def update_lines(self, lines, is_white)  # Update engine lines

AnalysisLinesWidget

Displays top engine lines for current position.

Class: AnalysisLinesWidget(QFrame)

class AnalysisLinesWidget(QFrame):
    def __init__(self)

Features:

• Shows top 3 engine variations
• Score display (CP or Mate)
• Move sequence in SAN

Key Methods:

def update_lines(self, multi_pvs, turn_color)  # Update with new analysis
def clear(self)                                 # Clear all lines

Graph Widget (graph_widget.py)

Evaluation curve visualization using Matplotlib.

Class: GraphWidget(QWidget)

class GraphWidget(QWidget):
    def __init__(self)

Features:

• Line plot of evaluation over moves
• White/black area fill
• Classification markers (scatter points)
• Hover tooltips
• Click-to-navigate (future)

Key Methods:

def plot_game(self, game_analysis)   # Draw evaluation graph
def clear(self)                      # Reset graph
def on_hover(self, event)            # Handle hover for tooltips

Visual Elements:

Metrics Widget (metrics_widget.py)

Statistics dashboard with charts.

Class: MetricsWidget(QWidget)

class MetricsWidget(QWidget):
    request_settings = pyqtSignal()    # Request navigation to settings

Features:

• Overview statistics (games, wins, accuracy)
• Results donut chart (Win/Loss/Draw)
• Termination donut chart (Checkmate/Resignation/Time)
• Accuracy trend line chart
• Performance by color (White vs Black bars)
• Opening frequency list
• AI Coach insights

Key Methods:

def refresh(self, _=None)              # Reload all statistics
def show_dashboard(self, stats)        # Render charts with stats
def show_no_data(self)                 # Show empty state
def show_setup_required(self)          # Show configuration needed state

Stats Structure:

stats = {
    "total_games": 25,
    "wins": 15,
    "losses": 8,
    "draws": 2,
    "avg_accuracy": 82.5,
    "openings": {"Sicilian Defense": 8, "Italian Game": 5, ...},
    "opening_wins": {"Sicilian Defense": 5, ...},
    "terminations": {"checkmate": 10, "resignation": 12, ...},
    "color_stats": {
        "white": {"games": 12, "wins": 8, "losses": 3, "draws": 1},
        "black": {"games": 13, "wins": 7, "losses": 5, "draws": 1}
    }
}

Views (gui/views/)

HistoryView (history_view.py)

Game history browser.

Class: HistoryView(QWidget)

class HistoryView(QWidget):
    game_selected = pyqtSignal(object)   # Emitted when game is double-clicked

Features:

• Scrollable game list
• Source icons (Chess.com, Lichess, PGN)
• Game metadata display
• Delete game option
• Export/Import CSV

Key Methods:

def refresh(self)                    # Reload game list from database
def export_to_csv(self)              # Export games to CSV
def import_from_csv(self)            # Import games from CSV

SettingsView (settings_view.py)

Settings configuration panel.

Class: SettingsView(QWidget)

class SettingsView(QWidget):
    engine_path_changed = pyqtSignal(str)   # Engine path updated
    llm_config_changed = pyqtSignal()       # LLM config updated
    usernames_changed = pyqtSignal()        # Usernames updated

Sections:

Dialogs (gui/dialogs/)

SplashScreen (splash_screen.py)

Startup splash screen.

Class: SplashScreen(QSplashScreen)

class SplashScreen(QSplashScreen):
    def __init__(self, logo_path)

Features:

• Branded logo display
• Progress bar
• Status message
• Smooth transitions

Key Methods:

def update_progress(self, value, message)   # Update progress and status
def finish(self, main_window)               # Close splash and show main window

LoadGameDialog (load_game_dialog.py)

Unified modal dialog for importing chess games.

Class: LoadGameDialog(QDialog)

class LoadGameDialog(QDialog):
    def __init__(self, parent=None, initial_source=0)

Features:

• Multi-tab UI for PGN file, pasted PGN, Chess.com username/URL, and Lichess username/URL.
• Asynchronous background fetching of games using background workers.
• Drag-and-drop zone for .pgn files.
• Inline game list rendering (date, result, ratings, ELO, time controls).

Key Methods:

def _switch_source(self, src_id)    # Switch active loading tab
def _set_pending(self, pgn, data)   # Handle loaded/pasted game PGN content

ShortcutHelpDialog (shortcut_help_dialog.py)

Interactive keyboard shortcuts help panel (press F1 or click Help).

Reusable Components (gui/components/)

StatCard (stat_card.py)

Reusable statistic display card.

Class: StatCard(QFrame)

class StatCard(QFrame):
    def __init__(self, title, value, icon=None)

Features:

• Title label
• Large value display
• Optional icon
• Theme-aware styling

Key Methods:

def set_value(self, value)    # Update displayed value
def set_title(self, title)    # Update title text

Styles (styles.py)

Centralized theming and styling.

Class: Styles

Color Constants:

COLOR_BACKGROUND = "#1E1E1E"
COLOR_SURFACE = "#252526"
COLOR_SURFACE_LIGHT = "#2D2D2D"
COLOR_BORDER = "#3C3C3C"
COLOR_TEXT_PRIMARY = "#FFFFFF"
COLOR_TEXT_SECONDARY = "#AAAAAA"
COLOR_ACCENT = "#4CAF50"       # Configurable

Board Themes:

BOARD_THEMES = {
    "default": {"light": "#EEEDD2", "dark": "#769656"},
    "brown": {"light": "#F0D9B5", "dark": "#B58863"},
    "blue": {"light": "#DEE3E6", "dark": "#8CA2AD"},
    "purple": {"light": "#D9D9D9", "dark": "#9F7BB8"},
    "grey": {"light": "#CCCCCC", "dark": "#666666"}
}

Classification Colors:

@staticmethod
def get_class_color(classification: str) -> str:
    colors = {
        "Brilliant": "#00CED1",  # Cyan
        "Great": "#008080",      # Teal
        "Best": "#66BB6A",       # Green
        "Excellent": "#9CCC65",  # Light Green
        "Good": "#CDDC39",       # Lime
        "Inaccuracy": "#FDD835", # Yellow
        "Mistake": "#FFA726",    # Orange
        "Blunder": "#EF5350",    # Red
        "Miss": "#AB47BC",       # Purple
        "Book": "#42A5F5"        # Blue
    }

Style Generators:

@staticmethod
def get_button_style()          # Standard button QSS
def get_input_style()           # Input field QSS
def get_label_style()           # Primary label QSS
def get_secondary_label_style() # Secondary label QSS
def get_card_style()            # Card container QSS

GUI Utilities (gui_utils.py)

Shared helper functions for creating UI elements.

Functions

def create_button(text, icon=None, primary=False) -> QPushButton

Creates a styled button with optional icon.

def create_label(text, style="primary") -> QLabel

Creates a styled label.

def get_icon_path(icon_name) -> str

Resolves path to an icon file.

Loading Widget (loading_widget.py)

Non-blocking loading overlay.

Class: LoadingOverlay(QWidget)

class LoadingOverlay(QWidget):
    def __init__(self, parent)

Features:

• Semi-transparent overlay
• Spinning animation
• Status message
• Auto-positioning

Key Methods:

def show_loading(self, message="Loading...")   # Show overlay
def hide_loading(self)                          # Hide overlay