Iced Application Shell

A fully-featured application shell built with the iced GUI framework, providing a complete UI foundation with modals, overlays, menus, notifications, and responsive interactions.

Purpose

This application serves as a comprehensive reference implementation and reusable application shell demonstrating iced's capabilities. It provides:

• Complete UI system with overlays, modals, and menus
• Flexible theming with multiple appearance styles
• User communication via toasts, modals, and notifications
• Keyboard shortcuts for common actions
• Context menus with smart positioning
• Responsive design with dynamic window size handling
• Reference implementation for building iced applications

Why This Project?

Building GUI applications in Rust with iced requires understanding many patterns:

• State management and message passing
• Overlay and modal systems
• Cross-platform theming
• Keyboard and mouse event handling

This project demonstrates production-ready solutions to these challenges, serving as:

• 📚 Learning resource for iced developers
• 🏗️ Starting point for new applications
• 🔧 Reference implementation of common UI patterns
• 📦 Future library (see LIBRARY_CRATE.md)

Implemented Features

🎨 UI Components

Configuration Menu

• Modal window with title bar and close button
• Appearance styles: Windows XP, Windows 10, Java Swing, HTML Bootstrap, Plain HTML, Default Iced, Image-Based
• Themes: Light, Dark, Dracula, Nord, Solarized Light/Dark, Gruvbox Light/Dark, Catppuccin variants, Tokyo Night
• Font families: Sans-serif, Serif, Monospace
• Font size slider: Adjustable base font size
• Keyboard shortcuts: Cmd+K to toggle, ESC to close
• Slide-in animation from top

View Switcher

• Multiple views: Welcome, Form, Chart, Table, Settings
• Keyboard navigation: Cmd+1/2/3 to cycle views
• Slide-in animation from bottom
• Visual indicators for current view

Notifications System

• Toast notifications: Auto-dismissing messages with icons
• Modal dialogs: Alert, Confirm, Error types
• Overlay system: Blocks interaction when active
• Click blocking: Prevents interaction with underlying content
• Smart positioning: All floating elements properly layered

Context Menu

• Right-click activation: Shows at cursor position
• Smart repositioning: Stays on-screen near edges
• Dynamic window size: Adapts to window resizing
• Actions: Copy, Paste, Delete with icons
• Click-outside dismissal: Auto-closes on left click

Status Bar

• Current view indicator: Shows active view with icon
• Configuration display: Appearance style, theme, font
• Loading indicator: Visual feedback for async operations

🎯 Interaction Features

Keyboard Shortcuts

• Cmd+K - Toggle configuration menu
• Cmd+1/2/3 - Cycle through views
• ESC - Close configuration menu or context menu
• Right-click - Show context menu

Mouse Interactions

• Hover effects: Visual feedback on interactive elements
• Click blocking: Overlays prevent click-through
• Context menus: Right-click anywhere for menu
• Cursor control: Arrow cursor on overlays (not pointer)

Animations

• Smooth transitions: Config menu and view switcher slide in/out
• Toast animations: Fade in/out for notifications
• No delay on close: Instant dismissal for better UX

🎨 Theming System

Appearance Styles

• Windows XP, Windows 10, Java Swing
• HTML Bootstrap, Plain HTML
• Default Iced, Image-Based (Game)

Color Themes

• Light themes: Light, Solarized Light, Gruvbox Light, Catppuccin Latte
• Dark themes: Dark, Dracula, Nord, Solarized Dark, Gruvbox Dark, Tokyo Night, Catppuccin variants (Frappé, Macchiato, Mocha)

Typography

• Font family selection (Sans-serif, Serif, Monospace)
• Adjustable base font size (12-24px)
• Consistent typography across all components

Project Structure

├── src/
│   ├── main.rs                          # Application entry point
│   └── app/
│       ├── mod.rs                       # Main app logic and view
│       ├── state.rs                     # Application state and types
│       ├── message.rs                   # Message enum for events
│       └── components/
│           ├── mod.rs                   # Component exports
│           ├── config_menu.rs           # Configuration menu UI
│           ├── view_switcher.rs         # View switching UI
│           ├── status_bar.rs            # Status bar component
│           ├── notifications.rs         # Toasts, modals, overlays
│           ├── context_menu.rs          # Right-click context menu
│           └── tooltip.rs               # Tooltip component
├── Cargo.toml
└── README.md

Technology Stack

• Framework: iced - A cross-platform GUI library for Rust
• Language: Rust (Edition 2024)
• Features: Canvas rendering, async runtime (tokio)

Development Status

✅ Core Shell Complete - The application shell is fully functional with all core UI components implemented.

Note: While the core shell is feature-complete and stable, this is an active development project. See TODO for planned enhancements.

Design Documents

This project includes detailed design documents for planned features:

• 📋 Menu System Proposal - Top menu bar and inspector panel
• 📱 Responsiveness - Responsive layout system
• 📦 Library Crate - Extracting reusable components
• 🔌 Shell API - View trait and shell query system
• ⚙️ Shell Configuration - Configuration management

These documents serve as both planning artifacts and implementation guides.

TODO

Priority Features

1. Top Menu Bar - See MENU_SYSTEM_PROPOSAL.md

   • Implement native menu bar (File, Edit, View, Window, Help)
   • Add menu message handlers
   • Test cross-platform behavior (macOS, Windows, Linux)
   • Add keyboard shortcuts for menu items

2. Responsiveness - See RESPONSIVENESS.md

   • Implement responsive layout system (Mobile, Tablet, Desktop)
   • Add breakpoint detection and layout mode switching
   • Create responsive font sizes and spacing
   • Adjust components for different screen sizes
   • Test on various window sizes and devices

3. Library Crate - See LIBRARY_CRATE.md

   • Extract shell components into reusable library
   • Define public API for shell components
   • Create documentation and examples
   • Publish as separate crate

4. Shell API & Configuration - See SHELL_API.md and SHELL_CONFIG.md

   • Implement ShellQuery for read-only state access
   • Implement ShellCommands for message builders
   • Create View trait for standardized view interface
   • Add ViewRegistry for managing view instances
   • Implement configuration persistence

Shell Refinement

• Implement static-component/dynamic-pointer tooltip ✅
• Reposition view switcher for better visual appearance
• Adjust spacing, text fonts, and other UI elements for final polishing
• Improve initial welcome page with better help hints and instructions

Future Components

• Side Panel/Inspector - See MENU_SYSTEM_PROPOSAL.md
• Add markdown reader view component
• Add code editor component with syntax highlighting (keyword coloring)
• Add sample form view with various controls:
  • Dropdown/select menus
  • Sliders
  • File selector
  • Text inputs
  • Checkboxes and radio buttons
  • Date pickers
• Add more appearance styles and themes
• Add audio/video player component

Getting Started

Prerequisites

• Rust 1.75+ (with 2024 edition support)
• Cargo

Building

# Clone the repository
git clone <repository-url>
cd icedapp2

# Build the project (debug)
cargo build

# Build optimized release
cargo build --release

# Run the application
cargo run --release

Usage

Once running, you can:

1. Open Configuration Menu: Press Cmd+K or click the gear icon
2. Switch Views: Press Cmd+1/2/3 or use the view switcher
3. Show Context Menu: Right-click anywhere in the window
4. Test Notifications: Click the demo buttons to show toasts and modals
5. Change Themes: Open config menu and select different appearance styles and themes
6. Adjust Typography: Use the font family picker and size slider in config menu

Development

# Check code
cargo check

# Format code
cargo fmt

# Run clippy lints
cargo clippy

# Build documentation
cargo doc --open

Project Status

🚧 Work in Progress - This is an active development project for learning and experimentation.

• ✅ Core shell components are functional and tested
• 🔄 API design and library extraction in progress
• 📋 See TODO for planned features

Contributions: Not accepting external contributions at this time, but feedback and suggestions are welcome via issues!

License: BSD-3-Clause

Key Implementation Details

Overlay System

• Single unified overlay blocks all interaction when active
• Modals and menus appear above overlay without adding extra shadows
• Click blocking prevents interaction with underlying content
• Arrow cursor on overlays (not pointer hand)

Context Menu Positioning

• Dynamically repositions to stay on-screen
• Uses window resize events to track window dimensions
• Calculates position based on cursor location and menu size
• Maintains full menu size, never shrinks

Animation System

• Smooth slide-in animations for config menu and view switcher
• Instant close on user action (no animation delay)
• Toast fade in/out animations
• Controlled via Instant timestamps and animation subscriptions

Event Handling

• Keyboard shortcuts via event subscription
• Mouse events (cursor movement, clicks, right-clicks)
• Window resize events for responsive positioning
• Message-based architecture for clean state updates

Acknowledgments

• Built with iced by Héctor Ramón
• Demonstrates production-ready patterns for iced applications

---

Note: This application shell provides a complete foundation for building iced applications with professional UI patterns, theming, and user interactions.