← XeFM crftwr/xefm on GitHub · craftware

Jump Dialog System Documentation

Overview

The Jump Dialog System provides fast and efficient navigation to any directory within the current directory tree. It features recursive scanning, real-time filtering, hidden file support, and performance optimization for seamless directory navigation.

Key Features

🚀 Fast Directory Navigation

🔍 Smart Filtering

⚡ Performance Optimized

🎯 User-Friendly Interface

Hidden Files Support

Context-Aware Filtering

The Jump Dialog respects the show_hidden setting from FileOperations, providing consistent behavior with the main file panes:

Smart Filtering Logic

The filtering uses context-aware logic:

Example Directory Structure

/home/user/project/
├── documents/
├── downloads/
├── .git/
├── .vscode/
├── .config/
│   └── settings/
└── src/
    └── .cache/

With Hidden Files OFF (show_hidden = False)

From visible root (/home/user/project/): Shows:

Filters out: .git/, .vscode/, .config/, src/.cache/

From hidden root (/home/user/project/.git/): Shows all subdirectories within the .git/ context for normal navigation.

With Hidden Files ON (show_hidden = True)

Shows all directories including hidden ones.

Usage

Opening the Jump Dialog

Visual Elements

Selection Behavior

Technical Implementation

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Jump Dialog System                       │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │   Threading     │  │   Filtering     │  │   Animation     │  │
│  │   - Scan Worker │  │   - Real-time   │  │   - Progress    │  │
│  │   - Cancellation│  │   - Case-insens │  │   - Spinner     │  │
│  │   - Thread-safe │  │   - Partial     │  │   - Context     │  │
│  │   - Hidden Files│  │   - Hidden Files│  │   - Status      │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │   Navigation    │  │   Integration   │  │   Configuration │  │
│  │   - Keyboard    │  │   - Main App    │  │   - Key Binding │  │
│  │   - Selection   │  │   - Pane Mgmt   │  │   - Limits      │  │
│  │   - Scrolling   │  │   - State Mgmt  │  │   - Hidden Files│  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Core Components

1. JumpDialog Class (xefm/jump_dialog.py)

2. JumpDialogHelpers Class

3. Threading Implementation

4. Hidden Files Integration

5. Progress Animation

Key Implementation Details

Hidden Files Filtering

def _should_include_directory(self, directory_path):
    """Determine if a directory should be included based on show_hidden setting"""
    if not self.file_operations:
        return True  # Fallback: include all directories
    
    if self.file_operations.show_hidden:
        return True  # Show all directories
    
    # Context-aware filtering logic
    directory_name = directory_path.name
    if directory_name.startswith('.'):
        # Check if we're already in a hidden directory context
        return self._is_in_hidden_context(directory_path)
    
    return True  # Include non-hidden directories

Integration with Main Application

# Main application passes FileOperations reference
self.jump_dialog.show(root_directory, self.file_operations)

Configuration

Key Binding

KEY_BINDINGS = {
    'jump_dialog': ['J'],  # Shift+J to open jump dialog
    # ... other bindings
}

Performance Settings

The number of directories scanned is bounded by an internal cap (not a config key), which keeps the dialog responsive on large trees.

# Hidden files behavior (inherited from main application)
SHOW_HIDDEN_FILES = False  # Default: hide hidden directories

Progress Animation Settings

# Progress animation settings (inherited)
PROGRESS_ANIMATION_PATTERN = 'spinner'
PROGRESS_ANIMATION_SPEED = 0.2

Testing

Comprehensive Test Coverage

1. Unit Tests (test/test_jump_dialog.py)

2. Hidden Files Tests (test/test_jump_dialog_hidden_files.py)

3. Integration Tests (test/test_jump_dialog_integration.py)

4. End-to-End Tests (test/test_jump_dialog_end_to_end.py)

Test Results

✅ Unit Tests: 11/11 passed (including selection preservation tests)
✅ Hidden Files Tests: 8/8 passed
✅ Integration Tests: 6/6 passed  
✅ End-to-End Tests: 6/6 passed
✅ Total: 31/31 tests passed

Performance Characteristics

Scanning Performance

Hidden Files Impact

Thread Safety

Resource Management

Benefits

User Experience Benefits

Technical Benefits

Troubleshooting

Common Issues

1. Slow Scanning

2. Memory Usage

3. Hidden Files Not Filtering

4. Permission Errors

Debug Information

Future Enhancements

Potential Improvements

  1. Bookmarking: Save frequently accessed directories
  2. History: Remember recently visited directories
  3. Fuzzy Matching: More intelligent search algorithms
  4. Directory Previews: Show directory contents in preview pane
  5. Custom Sorting: Sort by name, date, size, etc.
  6. Network Directories: Support for remote/network paths
  7. Symlink Handling: Better handling of symbolic links

Configuration Extensions

  1. Custom Filters: User-defined directory filters
  2. Scan Depth Limits: Configurable recursion depth
  3. Exclusion Patterns: Skip certain directory patterns
  4. Custom Key Bindings: Additional navigation shortcuts

Conclusion

The Jump Dialog System significantly enhances XeFM’s navigation capabilities by providing:

This system follows XeFM’s design principles of being fast, reliable, and user-friendly while maintaining the keyboard-driven workflow that makes XeFM efficient for power users. The hidden files integration ensures consistent behavior across all navigation methods in the application.