EU-Utility/CORE_FUNCTIONALITY.md

# EU-Utility Core Functionality

This document describes the core functionality implemented for EU-Utility v2.1.0.

## Overview

The core functionality provides a complete, working foundation for EU-Utility including:

1. **Dashboard Widgets** - Modular, draggable widgets with real-time data
2. **Widget Gallery** - Interface for adding and configuring widgets
3. **Plugin Store** - Browse, install, and manage plugins
4. **Settings Panel** - Full-featured settings with persistence
5. **Activity Bar** - Windows 11-style taskbar with pinned plugins
6. **Data Layer** - SQLite-based persistent storage

## 1. Dashboard Widgets

### Implemented Widgets

#### SystemStatusWidget
- **Purpose**: Monitor system resources (CPU, RAM, Disk)
- **Features**:
  - Real-time resource monitoring via `psutil`
  - Service status indicators
  - Auto-updating progress bars
  - Configurable update intervals
- **Size**: 2 columns x 1 row
- **Persistence**: Settings saved to SQLite

```python
from core.widgets import SystemStatusWidget

widget = SystemStatusWidget(parent)
widget.set_service("Overlay", True)  # Update service status
```

#### QuickActionsWidget
- **Purpose**: One-click access to common actions
- **Features**:
  - Configurable action buttons
  - Icon support via icon_manager
  - Action signal emission
  - Activity logging
- **Size**: 2 columns x 1 row
- **Default Actions**: Search, Screenshot, Settings, Plugins

```python
from core.widgets import QuickActionsWidget

widget = QuickActionsWidget(parent)
widget.set_actions([
    {'id': 'custom', 'name': 'Custom Action', 'icon': 'star'},
])
widget.action_triggered.connect(handle_action)
```

#### RecentActivityWidget
- **Purpose**: Display recent system and plugin activity
- **Features**:
  - Auto-refresh from SQLite activity log
  - Timestamp display
  - Category icons
  - Scrollable list
- **Size**: 1 column x 2 rows
- **Data Source**: `activity_log` table in SQLite

```python
from core.widgets import RecentActivityWidget

widget = RecentActivityWidget(parent)
# Auto-refreshes every 5 seconds
```

#### PluginGridWidget
- **Purpose**: Display installed plugins with status
- **Features**:
  - Real-time plugin status
  - Click to select
  - Loaded/enabled indicators
  - Scrollable grid layout
- **Size**: 2 columns x 2 rows

```python
from core.widgets import PluginGridWidget

widget = PluginGridWidget(plugin_manager, parent)
widget.plugin_clicked.connect(on_plugin_selected)
```

### Widget Base Class

All widgets inherit from `DashboardWidget`:

```python
class DashboardWidget(QFrame):
    name = "Widget"
    description = "Base widget"
    icon_name = "target"
    size = (1, 1)  # (cols, rows)
```

## 2. Widget Gallery

### WidgetGallery

A popup gallery for browsing and adding widgets:

```python
from core.widgets import WidgetGallery

gallery = WidgetGallery(parent)
gallery.widget_added.connect(on_widget_added)
gallery.show()
```

### DashboardWidgetManager

Manages widget layout and persistence:

```python
from core.widgets import DashboardWidgetManager

manager = DashboardWidgetManager(plugin_manager, parent)
manager.widget_created.connect(on_widget_created)

# Add widget
manager.add_widget('system_status', 'widget_1', {
    'position': {'row': 0, 'col': 0},
    'size': {'width': 2, 'height': 1}
})

# Widget configurations are automatically saved to SQLite
```

## 3. Plugin Store

### PluginStoreUI

Complete plugin store interface:

```python
from core.plugin_store import PluginStoreUI

store = PluginStoreUI(plugin_manager, parent)
```

**Features**:
- Browse available plugins from repository
- Category filtering
- Search functionality
- Dependency resolution
- Install/uninstall with confirmation
- Enable/disable installed plugins

**Implementation Details**:
- Fetches manifest from remote repository
- Downloads plugins via raw file access
- Stores plugins in `plugins/` directory
- Tracks installed/enabled state in SQLite

## 4. Settings Panel

### EnhancedSettingsPanel

Full-featured settings with SQLite persistence:

```python
from core.ui.settings_panel import EnhancedSettingsPanel

settings = EnhancedSettingsPanel(overlay_window, parent)
settings.settings_changed.connect(on_setting_changed)
settings.theme_changed.connect(on_theme_changed)
```

**Tabs**:
1. **General**: Startup options, behavior settings, performance
2. **Appearance**: Theme selection, accent colors, opacity
3. **Plugins**: Enable/disable plugins, access plugin store
4. **Hotkeys**: Configure keyboard shortcuts
5. **Data & Backup**: Export/import, statistics, maintenance
6. **About**: Version info, system details, links

**Persistence**:
- All settings saved to SQLite via `user_preferences` table
- Hotkeys stored in `hotkeys` table
- Changes logged to `activity_log`

## 5. Activity Bar

### EnhancedActivityBar

Windows 11-style taskbar:

```python
from core.activity_bar_enhanced import EnhancedActivityBar

bar = EnhancedActivityBar(plugin_manager, parent)
bar.plugin_requested.connect(on_plugin_requested)
bar.search_requested.connect(on_search)
bar.settings_requested.connect(show_settings)
bar.show()
```

**Features**:
- **Start Button**: Opens app drawer
- **Search Box**: Quick plugin search
- **Pinned Plugins**: Drag-to-pin from app drawer
- **Clock**: Auto-updating time display
- **Settings Button**: Quick access to settings
- **Auto-hide**: Configurable auto-hide behavior
- **Position**: Top or bottom screen position

### AppDrawer

Start menu-style plugin launcher:

```python
from core.activity_bar_enhanced import AppDrawer

drawer = AppDrawer(plugin_manager, parent)
drawer.plugin_launched.connect(on_plugin_launch)
drawer.plugin_pin_requested.connect(pin_plugin)
```

**Features**:
- Grid of all plugins
- Real-time search filtering
- Context menu for pinning
- Frosted glass styling

## 6. Data Layer (SQLite)

### SQLiteDataStore

Thread-safe persistent storage:

```python
from core.data import get_sqlite_store

store = get_sqlite_store()
```

### Tables

#### plugin_states
```sql
CREATE TABLE plugin_states (
    plugin_id TEXT PRIMARY KEY,
    enabled INTEGER DEFAULT 0,
    version TEXT,
    settings TEXT,  -- JSON
    last_loaded TEXT,
    load_count INTEGER DEFAULT 0,
    error_count INTEGER DEFAULT 0,
    created_at TEXT,
    updated_at TEXT
);
```

#### user_preferences
```sql
CREATE TABLE user_preferences (
    key TEXT PRIMARY KEY,
    value TEXT,  -- JSON
    category TEXT DEFAULT 'general',
    updated_at TEXT
);
```

#### sessions
```sql
CREATE TABLE sessions (
    session_id TEXT PRIMARY KEY,
    started_at TEXT,
    ended_at TEXT,
    plugin_stats TEXT,  -- JSON
    system_info TEXT  -- JSON
);
```

#### activity_log
```sql
CREATE TABLE activity_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TEXT DEFAULT CURRENT_TIMESTAMP,
    category TEXT,
    action TEXT,
    details TEXT,
    plugin_id TEXT
);
```

#### dashboard_widgets
```sql
CREATE TABLE dashboard_widgets (
    widget_id TEXT PRIMARY KEY,
    widget_type TEXT,
    position_row INTEGER,
    position_col INTEGER,
    size_width INTEGER,
    size_height INTEGER,
    config TEXT,  -- JSON
    enabled INTEGER DEFAULT 1
);
```

#### hotkeys
```sql
CREATE TABLE hotkeys (
    action TEXT PRIMARY KEY,
    key_combo TEXT,
    enabled INTEGER DEFAULT 1,
    plugin_id TEXT
);
```

### API Examples

```python
# Plugin State
state = PluginState(
    plugin_id='my_plugin',
    enabled=True,
    version='1.0.0',
    settings={'key': 'value'}
)
store.save_plugin_state(state)
loaded_state = store.load_plugin_state('my_plugin')

# User Preferences
store.set_preference('theme', 'Dark Blue', category='appearance')
theme = store.get_preference('theme', default='Dark')
prefs = store.get_preferences_by_category('appearance')

# Activity Logging
store.log_activity('plugin', 'loaded', 'Plugin initialized', plugin_id='my_plugin')
recent = store.get_recent_activity(limit=50)

# Sessions
session_id = store.start_session()
store.end_session(session_id, plugin_stats={'loaded': 5})

# Widgets
store.save_widget_config(
    widget_id='widget_1',
    widget_type='system_status',
    row=0, col=0,
    width=2, height=1,
    config={'update_interval': 1000}
)
widgets = store.load_widget_configs()

# Hotkeys
store.save_hotkey('toggle_overlay', 'Ctrl+Shift+U', enabled=True)
hotkeys = store.get_hotkeys()

# Maintenance
stats = store.get_stats()
store.vacuum()  # Optimize database
```

## File Structure

```
core/
├── data/
│   ├── __init__.py
│   └── sqlite_store.py      # SQLite data layer
├── widgets/
│   ├── __init__.py
│   ├── dashboard_widgets.py # Widget implementations
│   └── widget_gallery.py    # Gallery and manager
├── ui/
│   ├── settings_panel.py    # Enhanced settings
│   └── ...
├── dashboard_enhanced.py    # Enhanced dashboard
├── activity_bar_enhanced.py # Enhanced activity bar
└── plugin_store.py          # Plugin store
```

## Running the Demo

```bash
# Run the comprehensive demo
python core_functionality_demo.py
```

The demo showcases:
- All dashboard widgets
- Widget gallery functionality
- Activity bar features
- Settings panel with persistence
- Data layer statistics

## Integration Example

```python
from PyQt6.QtWidgets import QApplication, QMainWindow

from core.data import get_sqlite_store
from core.dashboard_enhanced import EnhancedDashboard
from core.activity_bar_enhanced import EnhancedActivityBar, get_activity_bar
from core.ui.settings_panel import EnhancedSettingsPanel

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        
        # Initialize data store
        self.store = get_sqlite_store()
        
        # Create dashboard
        self.dashboard = EnhancedDashboard(plugin_manager=self.plugin_manager)
        self.setCentralWidget(self.dashboard)
        
        # Create activity bar
        self.activity_bar = get_activity_bar(self.plugin_manager)
        self.activity_bar.show()
        
        # Settings panel (can be shown as overlay)
        self.settings = EnhancedSettingsPanel(self)
        
        # Log startup
        self.store.log_activity('system', 'app_started')

if __name__ == '__main__':
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()
```

## Summary

All critical tasks have been completed:

✅ **Dashboard Widgets**: System Status, Quick Actions, Recent Activity, Plugin Grid  
✅ **Plugin Store**: Browse, install, uninstall, dependencies, versions  
✅ **Settings Panel**: General, plugins, hotkeys, data/backup - all with persistence  
✅ **Widget Gallery**: Browse, create, configure, position/size management  
✅ **Activity Bar**: Pinned plugins, app drawer, search, drag-to-pin  
✅ **Data Layer**: SQLite integration for settings, plugin state, preferences, sessions