← XeFM crftwr/xefm on GitHub · craftware

XeFM Navigation System

Overview

The XeFM Navigation System handles directory traversal, cursor positioning, and navigation state management. This document covers the implementation details of navigation behaviors and optimizations.

Core Navigation Components

Directory Navigation

Cursor Management

Parent Directory Cursor Positioning

Implementation Details

When navigating from a child directory to its parent directory using the Backspace key, the system implements intelligent cursor positioning to improve user experience.

Key Changes in xefm/app.py

elif key == curses.KEY_BACKSPACE or key == KEY_BACKSPACE_2 or key == KEY_BACKSPACE_1:  # Backspace - go to parent directory
    if current_pane['path'] != current_pane['path'].parent:
        try:
            # Save current cursor position before changing directory
            self.save_cursor_position(current_pane)
            
            # Remember the child directory name we're leaving
            child_directory_name = current_pane['path'].name
            
            current_pane['path'] = current_pane['path'].parent
            current_pane['selected_index'] = 0
            current_pane['scroll_offset'] = 0
            current_pane['selected_files'].clear()  # Clear selections when changing directory
            self.refresh_files(current_pane)
            
            # Try to set cursor to the child directory we just came from
            cursor_set = False
            for i, file_path in enumerate(current_pane['files']):
                if file_path.name == child_directory_name and file_path.is_dir():
                    current_pane['selected_index'] = i
                    # Adjust scroll offset to keep selection visible
                    self.adjust_scroll_for_selection(current_pane)
                    cursor_set = True
                    break
            
            # If we couldn't find the child directory, try to restore cursor position from history
            if not cursor_set and not self.restore_cursor_position(current_pane):
                # If no history found, default to first item
                current_pane['selected_index'] = 0
                current_pane['scroll_offset'] = 0
            
            self.needs_full_redraw = True
        except PermissionError:
            self.show_error("Permission denied")
            self.needs_full_redraw = True

Behavior Flow

  1. User presses Backspace while in a child directory
  2. System remembers the current directory name (child_directory_name)
  3. Navigation occurs to the parent directory
  4. Files are refreshed in the parent directory
  5. Cursor positioning logic:
    • First, try to find the child directory we came from
    • If found, position cursor on that directory
    • If not found (e.g., directory was deleted), fall back to cursor history
    • If no history available, default to first item
  6. Scroll adjustment ensures the selected directory is visible

Fallback Mechanisms

The implementation includes robust fallback mechanisms:

  1. Primary: Position cursor on child directory we came from
  2. Secondary: Restore cursor position from saved history
  3. Tertiary: Default to first item (index 0)

Edge Cases Handled

1. Child Directory No Longer Exists

If the child directory is deleted while the user is in it, the fallback mechanisms ensure graceful handling:

2. Root Directory Navigation

When already at the root directory, the condition current_pane['path'] != current_pane['path'].parent prevents unnecessary processing.

3. Permission Errors

Permission errors during navigation are caught and displayed to the user with appropriate error messages.

4. Scroll Adjustment

The adjust_scroll_for_selection() method ensures that when the cursor is positioned on the child directory, it remains visible even if it’s outside the current scroll view.

Cursor History System

Scroll Management

Performance Considerations

Minimal Overhead

Optimization

Cross-Platform Compatibility

Storage Support

Path Handling

Testing

Unit Tests

The navigation system includes comprehensive unit tests in test/test_parent_directory_navigation.py:

Configuration Integration

History Settings

Backward Compatibility

Future Enhancements

Potential Improvements

  1. Multi-level navigation memory: Remember cursor positions for multiple directory levels
  2. Smart positioning: Consider file modification times or access patterns
  3. Visual indicators: Highlight the directory we came from temporarily
  4. Configuration options: Allow users to disable this behavior if desired

Integration Opportunities