Skip to content

FONT_FIX.md

Latest commit

 

History

History
140 lines (107 loc) · 4.26 KB

FONT_FIX.md

File metadata and controls

140 lines (107 loc) · 4.26 KB

Font Fix Documentation

Problem

The original application was getting a Qt warning:

qt.qpa.fonts: Populating font family aliases took 182 ms. Replace uses of missing font family "Monospace" with one that exists to avoid this cost.

This warning occurs because:

  1. The application used hardcoded font-family: monospace; in CSS styles
  2. The generic "monospace" font family isn't guaranteed to exist on all systems
  3. Qt had to spend time searching for font alternatives, causing the warning

Solution

Created a comprehensive font management system that:

1. Platform-Aware Font Detection (font_manager.py)

The FontManager class provides:

  • Platform-specific font stacks: Different fonts prioritized per OS
  • Universal fallback system: Comprehensive list of monospace fonts
  • Font availability detection: Checks which fonts are actually installed
  • Cross-platform compatibility: Works on Windows, macOS, and Linux

2. Font Stack Priority

macOS (Darwin):

  • SF Mono (native macOS terminal font)
  • Monaco (classic Mac font)
  • Menlo
  • Courier New
  • Generic fallbacks

Windows:

  • Consolas (modern Windows terminal font)
  • Lucida Console
  • Courier New
  • Generic fallbacks

Linux:

  • DejaVu Sans Mono (widely available)
  • Liberation Mono
  • Ubuntu Mono
  • Noto Sans Mono
  • Droid Sans Mono
  • Generic fallbacks

3. Integration Changes

Updated menu.py to:

  • Import and use the font manager
  • Replace hardcoded "monospace" with platform-appropriate font stacks
  • Apply consistent font sizing (12px) across all text inputs
  • Use proper CSS font-family stacks with fallbacks

4. Build System Updates

Updated all build scripts to:

  • Include font_manager.py in the executable
  • Verify font manager is present during build
  • Bundle the font management system with the application

Technical Details

Font Detection Logic

def detect_best_monospace_font(self):
    """Detect the best available monospace font on this system"""
    available_families = set(self.font_db.families())
    
    for font_family in self.monospace_font_stack:
        if font_family in available_families:
            # Verify it's actually monospace
            font = QFont(font_family)
            if font.fixedPitch() or self._is_likely_monospace(font_family):
                return font_family
    
    return "Courier"  # Ultimate fallback

CSS Generation

def get_monospace_font_css(self, size=None):
    """Get CSS font-family stack for monospace fonts"""
    css_stack = []
    available_families = set(self.font_db.families())
    
    # Add available fonts from our stack
    for family in self.monospace_font_stack:
        if family in available_families:
            # Escape font names with spaces  
            if ' ' in family:
                css_stack.append(f'"{family}"')
            else:
                css_stack.append(family)

Final CSS Output Example

On macOS, this might generate:

font-family: "SF Mono", Monaco, Menlo, "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Courier New", monospace, serif;

Benefits

  1. No More Font Warnings: Qt finds fonts immediately without searching
  2. Better Typography: Uses the best available monospace font per platform
  3. Consistent Sizing: All terminal areas use 12px for readability
  4. Cross-Platform: Works reliably on Windows, macOS, and Linux
  5. Future-Proof: Easy to add new fonts as they become available
  6. Fallback Safety: Multiple fallback options prevent font failures

Files Modified

  • menu.py: Updated to use font manager and improved font CSS
  • font_manager.py: New - Comprehensive font management system
  • build.py: Include font manager in build process
  • build.sh: Include font manager in build process
  • test_build.py: Verify font manager is present during testing

Testing

The font fix can be tested by:

  1. Building the application with the new system
  2. Running on different platforms (Windows/Mac/Linux)
  3. Verifying no Qt font warnings appear
  4. Confirming terminal text uses appropriate monospace fonts

Future Enhancements

Could be extended to:

  • Support custom font loading (if fonts are embedded)
  • Font size preferences in config.yml
  • Additional font categories beyond monospace
  • Font rendering quality options