Icon System

Icon management, serving, and fallback system

Overview

The Icon System provides comprehensive icon management, including icon file lookup, serving via HTTP, and emoji fallbacks for FreeWorld OS.

Status: ✅ Complete - Icon management, serving, and fallback system fully implemented

Components

IconManager

Location: system/icon-manager.js

The main icon management class that handles icon paths, lookup, and serving.

Key Features:

  • Multiple Icon Paths: Searches multiple directories for icons
  • Size Variants: Supports 64x64, scalable, and default sizes
  • Format Support: PNG, ICO, SVG, JPG, JPEG
  • Name Variants: Tries multiple naming conventions (lowercase, uppercase, capitalized)
  • Caching: Caches icon paths for performance
  • Emoji Fallbacks: Falls back to emoji if icon file not found

Icon Directories

The system searches for icons in the following directories (in order of priority):

  • usr/share/icons/64x64/ - Main icon directory (64x64 pixels)
  • usr/share/icons/scalable/ - SVG icons (scalable)
  • usr/share/icons/default/ - Default icon directory
  • icons/ - Root level icons directory

Methods:

// Get icon path (file system path)
getIconPath(iconName, iconType = 'application', size = 64) → string

// Get icon URL (for web display)
getIconURL(iconName, iconType = 'application', size = 64) → string

// Get icon file content
getIconFileContent(iconPath) → Buffer|null

// Get MIME type for icon file
getIconMimeType(iconPath) → string

// Register additional icon directory
addIconPath(iconPath)

File Type Icon Mappings

Location: system/file-type-icons.js

Maps file extensions and types to specific icon file names.

Icon Mappings:

  • ArchiveIcon → Archive files (.zip, .rar, .7z, .tar, .gz)
  • PostItNote → Text files (.txt, .md, .log, .readme)
  • Mail → Email files (.eml, .msg, .mbox)
  • ThisPC → System files (.sys, .dll, .drv)
  • Trashcan → Trash (empty)
  • TrashcanFull → Trash (full)
  • driveicondark → Drives

Icon File Structure

Directory Layout

usr/
  share/
    icons/
      64x64/          # 64x64 pixel icons
        ArchiveIcon.png
        ArchiveIcon.ico
        PostItNote.png
        PostItNote.ico
        Mail.png
        Mail.ico
        ThisPC.png
        ThisPC.ico
        Trashcan.png
        Trashcan.ico
        TrashcanFull.png
        TrashcanFull.ico
        driveicondark.png
        driveicondark.ico
        wanderer.png
        folder.png
        file.png
      scalable/       # SVG icons (scalable)
        *.svg
      default/        # Default icons
        *.png
        *.ico
icons/                # Root level icons
  *.png
  *.ico

Supported Formats

  • PNG - Portable Network Graphics (recommended)
  • ICO - Windows Icon Format
  • SVG - Scalable Vector Graphics
  • JPG/JPEG - JPEG images

Naming Conventions

The system tries multiple naming variants when looking for icons:

  • Lowercase: archiveicon.png
  • Original case: ArchiveIcon.png
  • Capitalized: Archiveicon.png
  • Uppercase: ARCHIVEICON.png
  • With type suffix: ArchiveIcon_application.png

Icon Lookup Process

When requesting an icon, the system follows this process:

  1. Check Cache: First checks if icon path is cached
  2. Search Directories: Searches each icon directory in priority order
  3. Try Size Variants: Tries 64x64, scalable, and default sizes
  4. Try Name Variants: Tries different naming conventions
  5. Try Extensions: Tries .png, .ico, .svg, .jpg, .jpeg
  6. Emoji Fallback: Returns emoji if no icon file found

Default Icons

The system provides emoji fallbacks for common icon types:

  • folder → 📁
  • file → 📄
  • application → ⚙️
  • trash → 🗑️
  • trash-full → 🗑️
  • wanderer → 📁
  • ArchiveIcon → 📦
  • PostItNote → 📄
  • Mail → ✉️
  • ThisPC → 🖥️
  • Trashcan → 🗑️
  • TrashcanFull → 🗑️
  • driveicondark → 💾

HTTP Icon Serving

The GUI server provides an HTTP endpoint for serving icon files:

Icon Endpoint

GET /icons/*

Example:
GET /icons/usr/share/icons/64x64/ArchiveIcon.png

Response:
Content-Type: image/png
[Icon file content]

MIME Types

The system automatically detects MIME types based on file extension:

  • .png → image/png
  • .ico → image/x-icon
  • .svg → image/svg+xml
  • .jpg / .jpeg → image/jpeg
  • Default → application/octet-stream

Integration

Desktop Icons

Desktop icons use the IconManager to get icon URLs:

const iconManager = new IconManager();
const wandererIcon = iconManager.getIconURL('wanderer', 'application', 64);
const trashIcon = iconManager.getIconURL('Trashcan', 'trash', 64);

File Browser

The file browser uses icons from the FileTypeRegistry, which in turn uses IconManager:

const fileTypeRegistry = new FileTypeRegistry();
const iconURL = fileTypeRegistry.getIconURL('.txt');
// Returns: '/icons/usr/share/icons/64x64/PostItNote.png' or emoji

File Type Associations

File type associations map extensions to icon names, which are then resolved by IconManager:

// File type registry maps .txt → PostItNote
// IconManager resolves PostItNote → /icons/usr/share/icons/64x64/PostItNote.png

Usage Examples

Get Icon URL

const IconManager = require('./icon-manager');

const iconManager = new IconManager();
const iconURL = iconManager.getIconURL('ArchiveIcon', 'file', 64);
// Returns: '/icons/usr/share/icons/64x64/ArchiveIcon.png' or emoji

Get Icon Path

const iconPath = iconManager.getIconPath('wanderer', 'application', 64);
// Returns: 'usr/share/icons/64x64/wanderer.png' or emoji

Add Custom Icon Directory

iconManager.addIconPath('/custom/icons');
// Now searches /custom/icons first

Get Icon File Content

const iconPath = iconManager.getIconPath('ArchiveIcon', 'file', 64);
const content = iconManager.getIconFileContent(iconPath);
// Returns: Buffer with icon file content or null

Trash Icon Switching

The system automatically switches between empty and full trash icons:

const trashCount = trashSystem.getCount();
if (trashCount > 0) {
    iconURL = iconManager.getIconURL('TrashcanFull', 'trash', 64);
} else {
    iconURL = iconManager.getIconURL('Trashcan', 'trash', 64);
}

Icon Caching

The IconManager caches icon paths to improve performance:

  • Cache key format: iconName:iconType:size
  • Cache stores resolved icon paths or emoji fallbacks
  • Cache persists for the lifetime of the IconManager instance

Adding New Icons

To add a new icon to the system:

  1. Place the icon file in usr/share/icons/64x64/
  2. Use a descriptive name (e.g., MyApp.png)
  3. The system will automatically find it using name variants
  4. For file type associations, update file-type-icons.js

Related Documentation