Configuration

Learn how to configure and customize Launcher to match your preferences.

Configuration Overview

Launcher stores configuration in multiple locations:

User Preferences: SQLite database (~/.local/share/cloud.ivanbotty.Launcher/)
Extension Config: YAML files in resources directory
Runtime Settings: Environment variables
System Integration: Desktop files and GSettings

User Preferences

Accessing Preferences

Via UI: Click the preferences/settings icon in Launcher
Keyboard Shortcut: Press Ctrl+,
From Menu: Main menu → Preferences

General Settings

Application Behavior

# These settings are stored in SQLite database

startup_behavior:
  launch_on_login: false        # Auto-start with desktop session
  show_wizard_on_first_run: true  # Show welcome wizard
  minimize_to_tray: false       # Minimize to system tray

window_settings:
  remember_position: true       # Remember window position
  remember_size: true           # Remember window size
  default_width: 600            # Default window width (pixels)
  default_height: 400           # Default window height (pixels)
  always_on_top: false          # Keep window on top

theme_settings:
  follow_system_theme: true     # Use system theme
  prefer_dark_mode: false       # Force dark mode (if not following system)

Search Behavior

search_settings:
  instant_search: true          # Search as you type (no delay)
  search_delay_ms: 0            # Delay before search triggers (ms)
  max_results: 50               # Maximum results to display
  fuzzy_matching: true          # Enable fuzzy search
  case_sensitive: false         # Case-sensitive search
  search_descriptions: true     # Search in app descriptions (slower)

results_display:
  show_icons: true              # Display application icons
  icon_size: 64                 # Icon size in pixels
  show_descriptions: true       # Show app descriptions (extended mode)
  highlight_matches: true       # Highlight search matches

View Preferences

Compact Mode

compact_mode:
  grid_columns: 4               # Number of columns
  item_spacing: 10              # Spacing between items (pixels)
  show_labels: true             # Show application names
  icon_size: 48                 # Icon size for compact mode

Extended Mode

extended_mode:
  show_descriptions: true       # Show full descriptions
  show_categories: true         # Display app categories
  show_metadata: true           # Show additional metadata
  icon_size: 64                 # Icon size for extended mode
  row_height: 80                # Height of each row (pixels)

Keyboard Shortcuts

keyboard_shortcuts:
  # Global shortcuts (system-wide)
  toggle_launcher: "Super+Space"    # Open/close Launcher
  
  # Application shortcuts (when Launcher is open)
  navigate_up: "Up"                 # Move selection up
  navigate_down: "Down"             # Move selection down
  activate: "Return"                # Launch selected app
  close_window: "Escape"            # Close Launcher
  toggle_view: "Tab"                # Switch compact/extended
  preferences: "Ctrl+comma"         # Open preferences
  refresh: "F5"                     # Refresh application list
  
  # Search shortcuts
  select_all: "Ctrl+a"              # Select all search text
  copy: "Ctrl+c"                    # Copy selected text
  paste: "Ctrl+v"                   # Paste text
  clear_search: "Ctrl+u"            # Clear search field

Extension Configuration

Managing Extensions

Access extension settings through:

Preferences → Extensions tab
Extensions configuration file

Extension Settings File

Location: cloud/ivanbotty/Launcher/resources/extensions.yaml

extensions:
  - name: "Application Search"
    id: "app_search"
    enabled: true
    priority: 1
    description: "Search and launch installed applications"
    handler: "cloud.ivanbotty.Launcher.handlers.applications_handler.ApplicationsHandler"
    service: "cloud.ivanbotty.Launcher.services.applications_service.ApplicationsService"
    icon: "system-search"
    settings:
      search_paths:
        - "/usr/share/applications"
        - "~/.local/share/applications"
      cache_duration: 3600  # seconds

  - name: "Math Calculator"
    id: "math_calc"
    enabled: true
    priority: 2
    description: "Evaluate mathematical expressions"
    handler: "cloud.ivanbotty.Launcher.handlers.math_handler.MathHandler"
    service: "cloud.ivanbotty.Launcher.services.math_service.MathService"
    icon: "accessories-calculator"
    settings:
      decimal_places: 2
      angle_mode: "radians"  # radians or degrees
      
  - name: "Command Runner"
    id: "command"
    enabled: false
    priority: 3
    description: "Execute shell commands"
    handler: "cloud.ivanbotty.Launcher.handlers.command_handler.CommandHandler"
    service: "cloud.ivanbotty.Launcher.services.command_service.CommandService"
    icon: "utilities-terminal"
    settings:
      allowed_commands: []  # Empty = allow all (use with caution)
      history_size: 100
      show_output: true

  - name: "AI Assistant"
    id: "ai_assistant"
    enabled: false
    priority: 4
    description: "AI-powered natural language queries"
    handler: "cloud.ivanbotty.Launcher.handlers.ai_handler.AIHandler"
    service: "cloud.ivanbotty.Launcher.services.ai_service.AIService"
    icon: "dialog-question"
    settings:
      api_provider: "gemini"
      model: "gemini-pro"
      api_key: ""  # Set via environment variable
      temperature: 0.7
      max_tokens: 150

Per-Extension Configuration

Application Search Extension

app_search_settings:
  # Desktop file locations
  search_paths:
    - "/usr/share/applications"
    - "/usr/local/share/applications"
    - "~/.local/share/applications"
    - "/var/lib/flatpak/exports/share/applications"
    - "~/.local/share/flatpak/exports/share/applications"
  
  # Cache settings
  cache_enabled: true
  cache_duration: 3600  # seconds (1 hour)
  auto_refresh: true
  
  # Filtering
  show_hidden: false          # Show NoDisplay=true apps
  show_terminal_only: true    # Show Terminal=true apps
  category_filter: []         # Empty = all categories
  
  # Icon settings
  fallback_icon: "application-x-executable"
  icon_theme: "Adwaita"  # null = use system default

Math Calculator Extension

math_settings:
  # Display settings
  decimal_places: 2
  scientific_notation: false
  thousands_separator: false
  
  # Calculation settings
  angle_mode: "radians"  # radians or degrees
  precision: 15          # Internal precision
  
  # Allowed functions
  functions:
    - sqrt, pow, exp, log, log10
    - sin, cos, tan, asin, acos, atan
    - sinh, cosh, tanh
    - abs, ceil, floor, round
  
  # Constants
  constants:
    pi: 3.141592653589793
    e: 2.718281828459045
    phi: 1.618033988749895  # Golden ratio

AI Assistant Extension

ai_settings:
  # API Configuration
  provider: "gemini"
  model: "gemini-pro"
  api_key_env: "GEMINI_API_KEY"  # Environment variable name
  endpoint: "https://generativelanguage.googleapis.com/v1beta"
  
  # Generation settings
  temperature: 0.7       # 0.0-1.0 (creativity)
  max_tokens: 150        # Maximum response length
  top_p: 0.9            # Nucleus sampling
  top_k: 40             # Top-k sampling
  
  # Behavior
  streaming: false       # Stream responses
  context_length: 5      # Number of previous messages
  system_prompt: "You are a helpful assistant integrated into a Linux application launcher."
  
  # Safety
  safety_settings:
    harassment: "BLOCK_MEDIUM_AND_ABOVE"
    hate_speech: "BLOCK_MEDIUM_AND_ABOVE"
    sexually_explicit: "BLOCK_MEDIUM_AND_ABOVE"
    dangerous_content: "BLOCK_MEDIUM_AND_ABOVE"

Environment Variables

Override default settings using environment variables:

Application Settings

# Data directories
export LAUNCHER_DATA_DIR="$HOME/.local/share/cloud.ivanbotty.Launcher"
export LAUNCHER_CONFIG_DIR="$HOME/.config/cloud.ivanbotty.Launcher"
export LAUNCHER_CACHE_DIR="$HOME/.cache/cloud.ivanbotty.Launcher"

# Logging
export LAUNCHER_LOG_LEVEL="INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
export LAUNCHER_LOG_FILE="$HOME/.local/share/cloud.ivanbotty.Launcher/launcher.log"

# Performance
export LAUNCHER_CACHE_ENABLED="1"
export LAUNCHER_THREAD_POOL_SIZE="4"

# Debug mode
export LAUNCHER_DEBUG="0"  # 1 to enable debug mode

Extension Settings

# AI Service
export GEMINI_API_KEY="your-api-key-here"
export AI_MODEL="gemini-pro"
export AI_TEMPERATURE="0.7"

# Command Service
export LAUNCHER_ALLOW_COMMANDS="1"  # 1 to allow command execution
export LAUNCHER_COMMAND_TIMEOUT="30"  # seconds

GTK/Display Settings

# GTK theme
export GTK_THEME="Adwaita:dark"

# Display scaling
export GDK_SCALE="2"  # HiDPI scaling factor
export GDK_DPI_SCALE="0.5"

# Wayland/X11
export GDK_BACKEND="wayland"  # wayland or x11

Configuration Files

Database Schema

User preferences are stored in SQLite database:

-- Location: ~/.local/share/cloud.ivanbotty.Launcher/launcher.db

-- Preferences table
CREATE TABLE preferences (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    type TEXT NOT NULL,  -- string, int, bool, json
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Extensions state
CREATE TABLE extension_state (
    extension_id TEXT PRIMARY KEY,
    enabled BOOLEAN DEFAULT 1,
    priority INTEGER,
    settings TEXT  -- JSON
);

-- Application cache (optional)
CREATE TABLE app_cache (
    desktop_id TEXT PRIMARY KEY,
    name TEXT,
    description TEXT,
    icon TEXT,
    exec TEXT,
    categories TEXT,
    cached_at TIMESTAMP
);

Resource Files

cloud/ivanbotty/Launcher/resources/
├── extensions.yaml          # Extension definitions
├── wizard.yaml              # Welcome wizard config
├── resources.xml            # GResource bundle
├── appdata.xml              # AppStream metadata
└── *.svg                    # Icon files

Advanced Configuration

Custom Application Paths

Add custom desktop file locations:

# In your local extensions.yaml or via preferences
app_search_settings:
  additional_paths:
    - "/opt/applications"
    - "$HOME/custom-apps"

Custom Icon Themes

# Set custom icon theme
gsettings set org.gnome.desktop.interface icon-theme 'Papirus'

# Or via environment
export GTK_ICON_THEME="Papirus"

Performance Tuning

performance:
  # Database
  db_cache_size: 10000        # SQLite cache size (KB)
  db_synchronous: "NORMAL"    # OFF, NORMAL, FULL
  
  # Threading
  thread_pool_size: 4         # Background worker threads
  async_search: true          # Non-blocking search
  
  # Caching
  icon_cache_size: 100        # Cached icon paths
  app_cache_size: 500         # Cached app entries
  cache_ttl: 3600             # Cache TTL (seconds)

Debug Configuration

Enable detailed logging:

# Run with debug output
LAUNCHER_LOG_LEVEL=DEBUG flatpak run cloud.ivanbotty.Launcher

# Or with Python
LAUNCHER_LOG_LEVEL=DEBUG python3 -m cloud.ivanbotty.Launcher

Debug configuration:

debug:
  log_level: "DEBUG"
  log_to_file: true
  log_file: "~/.local/share/cloud.ivanbotty.Launcher/debug.log"
  log_format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  
  # Performance profiling
  profile_enabled: false
  profile_output: "/tmp/launcher-profile.prof"
  
  # GTK Inspector
  enable_inspector: true  # GTK_DEBUG=interactive

Flatpak-Specific Configuration

When running as Flatpak, some paths are different:

# Data directory
~/.var/app/cloud.ivanbotty.Launcher/data/cloud.ivanbotty.Launcher/

# Config directory
~/.var/app/cloud.ivanbotty.Launcher/config/cloud.ivanbotty.Launcher/

# Access host files (read-only)
/run/host/  # Host filesystem

# Override Flatpak settings
flatpak override --user cloud.ivanbotty.Launcher --filesystem=home

Configuration Examples

Minimal Configuration

For a clean, minimal setup:

general:
  show_icons: true
  max_results: 20
  
extensions:
  enabled:
    - app_search

Power User Configuration

For advanced users:

general:
  instant_search: true
  fuzzy_matching: true
  max_results: 100
  show_descriptions: true

keyboard_shortcuts:
  toggle_launcher: "Super+Space"
  quick_calc: "Super+C"

extensions:
  enabled:
    - app_search
    - math_calc
    - command
    - ai_assistant

performance:
  thread_pool_size: 8
  cache_size: 1000

Developer Configuration

For development and testing:

debug:
  log_level: "DEBUG"
  enable_inspector: true
  profile_enabled: true

development:
  reload_on_change: true
  show_widget_bounds: true
  verbose_errors: true

Resetting Configuration

Reset to Defaults

# Remove database (will be recreated)
rm ~/.local/share/cloud.ivanbotty.Launcher/launcher.db

# Or for Flatpak
rm ~/.var/app/cloud.ivanbotty.Launcher/data/cloud.ivanbotty.Launcher/launcher.db

Backup Configuration

# Backup user data
cp -r ~/.local/share/cloud.ivanbotty.Launcher ~/launcher-backup

# Restore from backup
cp -r ~/launcher-backup/* ~/.local/share/cloud.ivanbotty.Launcher/

Next Steps

Read the Usage Guide to learn how to use configured features
Check FAQ for configuration troubleshooting
See Architecture for technical details

Configuration

Configuration

Table of Contents

Configuration Overview

User Preferences

Accessing Preferences

General Settings

Application Behavior

Search Behavior

View Preferences

Compact Mode

Extended Mode

Keyboard Shortcuts

Extension Configuration

Managing Extensions

Extension Settings File

Per-Extension Configuration

Application Search Extension

Math Calculator Extension

AI Assistant Extension

Environment Variables

Application Settings

Extension Settings

GTK/Display Settings

Configuration Files

Database Schema

Resource Files

Advanced Configuration

Custom Application Paths

Custom Icon Themes

Performance Tuning

Debug Configuration

Flatpak-Specific Configuration

Configuration Examples

Minimal Configuration

Power User Configuration

Developer Configuration

Resetting Configuration

Reset to Defaults

Backup Configuration

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally