Advanced Features

BoxMux includes mouse support, hot keys, clipboard integration, navigation, and performance monitoring.

Table of Contents

Mouse Click Support

BoxMux provides mouse interaction for navigation and control.

Features

Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Enable mouse interaction (enabled by default)
app:
  mouse_enabled: true
  layouts:
    - id: 'interactive'
      children:
        - id: 'clickable_menu'
          title: 'Actions (Click to Execute)'
          choices:
            - id: 'deploy'
              content: 'Deploy Application'
              script: ['./deploy.sh']
            - id: 'test'
              content: 'Run Tests'
              script: ['cargo test']
              
        - id: 'output_box'
          title: 'Output (Click to Focus)'
          position: {x1: 0%, y1: 50%, x2: 100%, y2: 100%}
          content: 'Click this box to focus and enable scrolling'

Mouse Interaction Behavior

Hot Key Actions

Global keyboard shortcuts to trigger specific choice actions without menu navigation.

Features

Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

app:
  hot_keys:
    'F1': 'build'           # F1 triggers build action
    'F2': 'test'            # F2 triggers test action
    'F3': 'deploy'          # F3 triggers deploy action
    'F5': 'refresh_all'     # F5 refreshes all boxes
    'F9': 'git_status'      # F9 shows git status
    'F12': 'system_info'    # F12 shows system info
    
  layouts:
    - id: 'development'
      title: 'Dev Environment (F1=Build, F2=Test, F3=Deploy)'
      children:
        - id: 'menu'
          title: 'Quick Actions'
          choices:
            - id: 'build'
              content: 'Build Project [F1]'
              script: ['cargo build']
              redirect_output: 'output'
              
            - id: 'test'
              content: 'Run Tests [F2]'
              script: ['cargo test']
              redirect_output: 'output'
              
            - id: 'deploy'
              content: 'Deploy [F3]'
              script: ['./deploy.sh']
              redirect_output: 'output'
              
        - id: 'output'
          title: 'Build/Test Output'
          position: {x1: 0%, y1: 40%, x2: 100%, y2: 100%}

Hot Key Best Practices

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Group related actions by function key ranges
app:
  hot_keys:
    # Build/Test (F1-F4)
    'F1': 'build_debug'
    'F2': 'build_release'
    'F3': 'test_unit'
    'F4': 'test_integration'
    
    # Git operations (F5-F8)
    'F5': 'git_status'
    'F6': 'git_pull'
    'F7': 'git_commit'
    'F8': 'git_push'
    
    # System monitoring (F9-F12)
    'F9': 'cpu_usage'
    'F10': 'memory_usage'
    'F11': 'disk_usage'
    'F12': 'system_logs'

Enhanced Navigation

Keyboard navigation with Home/End scrolling and proportional scrollbars.

Features

1
2
3
4
5
6

Home          - Scroll to beginning of current line (horizontal 0%)
End           - Scroll to end of current line (horizontal 100%)
Ctrl+Home     - Scroll to top of content (vertical 0%)
Ctrl+End      - Scroll to bottom of content (vertical 100%)
Arrow Keys    - Line-by-line scrolling
Page Up/Down  - Page-based scrolling

1
2
3
4
5
6
7
8
9
10
11
12

# Box with enhanced navigation
- id: 'large_content'
  title: 'Large Content (Home/End/Ctrl+Home/End navigation)'
  position: {x1: 10%, y1: 10%, x2: 90%, y2: 80%}
  scrollable: true
  navigation_enabled: true
  script:
    - |
      echo "=== Large Content for Navigation Demo ==="
      for i in {1..100}; do
        echo "Line $i: This is a very long line that extends beyond the box width to demonstrate horizontal scrolling capabilities in BoxMux boxes"
      done

Proportional Scrollbar Behavior

1
2
3
4
5
6
7
8

# Example: Different content ratios
- id: 'small_overflow'
  title: 'Small Overflow (Large Knob)'
  script: ['seq 1 25']  # Only 5 extra lines - large scrollbar knob
  
- id: 'large_overflow' 
  title: 'Large Overflow (Small Knob)'
  script: ['seq 1 1000'] # Many extra lines - small scrollbar knob

Clipboard Integration

BoxMux provides platform-specific clipboard integration with visual feedback.

Features

Usage

  1. Navigate to a box using Tab key or mouse
  2. Press Ctrl+C to copy box content to clipboard
  3. Visual flash indicates successful copy operation
  4. Paste content in any application using standard clipboard operations

Configuration

1
2
3
4
5
6

# Enable clipboard for specific boxes
- id: 'results_box'
  title: 'Command Results'
  clipboard_enabled: true  # Allow clipboard copying
  script:
    - ps aux | head -20

Implementation Details

Enhanced Scrolling

BoxMux provides advanced scrolling capabilities with position preservation and navigation controls.

Features

Keyboard Controls

Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13

# Box with enhanced scrolling
- id: 'scrollable_output'
  title: 'Large Output'
  position: {x1: 10%, y1: 10%, x2: 90%, y2: 80%}
  scroll: true
  scroll_config:
    preserve_position: true    # Maintain position during refresh
    show_indicators: true      # Show scroll position
    page_size: 10             # Lines per page scroll
    smooth_scrolling: true    # Enable smooth scrolling
  refresh_interval: 2000
  script:
    - ps aux | head -100  # Large output for scrolling demo

Advanced Scrolling Features

1
2
3
4
5
6
7
8
9
10
11

# Auto-refresh with scroll preservation
- id: 'live_data'
  title: 'Live Data Stream'
  scroll: true
  scroll_config:
    preserve_position: true
    auto_scroll_new: false    # Don't auto-scroll to new content
    scroll_buffer_size: 1000  # Maximum lines to keep
  refresh_interval: 1000
  script:
    - date && ps aux | head -50

Performance Monitoring

BoxMux includes built-in performance monitoring and benchmarking capabilities.

Performance Benchmarks

BoxMux tracks performance metrics for core operations:

Monitoring Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Performance monitoring box
- id: 'performance'
  title: 'System Performance'
  position: {x1: 5%, y1: 10%, x2: 95%, y2: 50%}
  performance_monitoring: true
  refresh_interval: 5000
  script:
    - |
      echo "BoxMux Performance Metrics:"
      echo "=========================="
      echo "Memory Usage: $(ps -o rss= -p $$) KB"
      echo "CPU Usage: $(ps -o %cpu= -p $$)%"
      echo "Uptime: $(uptime -p)"
      echo "Active Boxes: $(pgrep -f boxmux | wc -l)"

Performance Testing

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Load testing configuration
- id: 'load_test'
  title: 'Load Test Results'
  performance_test: true
  test_config:
    duration: 60        # Test duration in seconds
    refresh_rate: 100   # Fast refresh for stress testing
    data_volume: 'high' # High data volume test
  script:
    - |
      # Generate high-volume output for testing
      for i in {1..1000}; do
        echo "Test line $i: $(date)"
      done

Configuration Schema Validation

BoxMux includes comprehensive JSON Schema validation for YAML configurations.

Features

Error Reporting

When loading invalid configuration:

1
2
3
4
5
6
7
8

$ boxmux invalid-config.yaml
Error: Configuration validation failed
  --> invalid-config.yaml:15:3
   |
15 |   position: "invalid"
   |   ^^^^^^^^ expected object with x1, y1, x2, y2 properties
   |
   = help: position must be an object with percentage-based coordinates

Schema Validation Configuration

1
2
3
4
5
6
7

# Enable strict validation
app:
  validation:
    schema_validation: true     # Enable JSON schema validation
    strict_mode: true          # Fail on any validation error
    validate_scripts: true     # Validate script syntax
    validate_colors: true      # Validate color names

Custom Validation Rules

1
2
3
4
5
6
7
8
9

# Custom validation for specific fields
app:
  validation:
    custom_rules:
      - field: 'refresh_interval'
        min_value: 100           # Minimum refresh interval
        max_value: 300000        # Maximum refresh interval
      - field: 'position'
        validate_bounds: true    # Validate position bounds

Manual Socket Implementation

BoxMux uses a manual Unix socket implementation without external dependencies for maximum control and reliability.

Features

Socket Commands

BoxMux supports comprehensive socket API:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Update box content
echo '{"UpdateBox": {"box_id": "status", "content": "Connected"}}' | nc -U /tmp/boxmux.sock

# Replace box script
echo '{"ReplaceScript": {"box_id": "monitor", "script": ["uptime"]}}' | nc -U /tmp/boxmux.sock

# Switch layouts
echo '{"SwitchLayout": {"layout_id": "dashboard"}}' | nc -U /tmp/boxmux.sock

# Add new box
echo '{"AddBox": {"parent_id": "main", "box": {...}}}' | nc -U /tmp/boxmux.sock

# Control refresh
echo '{"StartRefresh": {"box_id": "logs"}}' | nc -U /tmp/boxmux.sock
echo '{"StopRefresh": {"box_id": "logs"}}' | nc -U /tmp/boxmux.sock

Socket Configuration

1
2
3
4
5
6
7
8

# Socket server configuration
app:
  socket_config:
    socket_path: '/tmp/boxmux.sock'
    permissions: 0660
    buffer_size: 8192
    timeout: 5000
    max_connections: 10

Real-World Examples

DevOps Dashboard

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

app:
  layouts:
    - id: 'devops'
      root: true
      title: 'DevOps Command Center'
      children:
        # Live deployment logs
        - id: 'deploy_logs'
          title: 'Deployment Logs'
          position: {x1: 5%, y1: 10%, x2: 60%, y2: 50%}
          clipboard_enabled: true
          scroll: true
          scroll_config:
            preserve_position: true
            show_indicators: true
          script:
            - kubectl logs -f deployment/api-server
            
        # Performance monitoring
        - id: 'cluster_perf'
          title: 'Cluster Performance'
          position: {x1: 65%, y1: 10%, x2: 95%, y2: 50%}
          performance_monitoring: true
          refresh_interval: 2000
          script:
            - kubectl top nodes
            - echo "---"
            - kubectl top pods
            
        # Interactive control box
        - id: 'controls'
          title: 'Deployment Controls'
          position: {x1: 5%, y1: 55%, x2: 95%, y2: 90%}
          tab_order: '1'
          choices:
            - id: 'scale_up'
              content: 'Scale Up (3→5 replicas)'
              script:
                - kubectl scale deployment/api-server --replicas=5
              redirect_output: 'deploy_logs'
            - id: 'rollback'
              content: 'Rollback to Previous Version'  
              script:
                - kubectl rollout undo deployment/api-server
              redirect_output: 'deploy_logs'

System Monitoring with Advanced Features

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

app:
  layouts:
    - id: 'advanced_monitor'
      root: true
      title: 'Advanced System Monitor'
      children:
        # System logs
        - id: 'system_logs'
          title: 'System Logs'
          position: {x1: 5%, y1: 10%, x2: 48%, y2: 60%}
          clipboard_enabled: true
          scroll: true
          scroll_config:
            preserve_position: true
            auto_scroll_new: true
            scroll_buffer_size: 2000
          script:
            - tail -f /var/log/system.log | grep -E "(error|warning|critical)"
            
        # Performance metrics with clipboard
        - id: 'perf_metrics'
          title: 'Performance Metrics'
          position: {x1: 52%, y1: 10%, x2: 95%, y2: 60%}
          clipboard_enabled: true
          performance_monitoring: true
          refresh_interval: 1000
          script:
            - |
              echo "=== System Performance ==="
              echo "CPU: $(top -l 1 | grep "CPU usage" | awk '{print $3}')"
              echo "Memory: $(free | awk 'NR==2{printf "%.1f%%", $3/$2*100}')"
              echo "Load: $(uptime | awk -F'load average:' '{print $2}')"
              echo "Processes: $(ps aux | wc -l)"
              echo "BoxMux Memory: $(ps -o rss= -p $$) KB"
              
        # Enhanced table with all features
        - id: 'process_table'
          title: 'Top Processes'
          position: {x1: 5%, y1: 65%, x2: 95%, y2: 90%}
          table_config:
            headers: ['Command', 'CPU %', 'Memory %', 'PID', 'User']
            sortable: true
            filterable: true
            page_size: 8
            zebra_striping: true
            show_row_numbers: true
            border_style: 'rounded'
          clipboard_enabled: true
          refresh_interval: 3000
          script:
            - ps aux --no-headers | awk '{printf "%s,%.1f,%.1f,%s,%s\n", $11, $3, $4, $2, $1}' | 
              sort -rn -k2 -t, | head -20

Development Environment Monitor

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

app:
  layouts:
    - id: 'dev_monitor'
      root: true
      title: 'Development Environment'
      children:
        # Build output
        - id: 'build_output'
          title: 'Build Output'
          position: {x1: 5%, y1: 10%, x2: 60%, y2: 70%}
          clipboard_enabled: true
          scroll: true
          scroll_config:
            preserve_position: false  # Always show latest for builds
            auto_scroll_new: true
          script:
            - cargo watch -x build
            
        # Git status with clipboard support
        - id: 'git_status'
          title: 'Git Status'
          position: {x1: 65%, y1: 10%, x2: 95%, y2: 40%}
          clipboard_enabled: true
          refresh_interval: 5000
          script:
            - git status --porcelain
            - echo "---"
            - git log --oneline -5
            
        # Test results with performance monitoring
        - id: 'test_results'
          title: 'Test Suite'
          position: {x1: 65%, y1: 45%, x2: 95%, y2: 70%}
          performance_monitoring: true
          clipboard_enabled: true
          refresh_interval: 10000
          script:
            - |
              echo "Running test suite..."
              start_time=$(date +%s%3N)
              cargo test --quiet 2>&1 | head -20
              end_time=$(date +%s%3N)
              duration=$((end_time - start_time))
              echo "Test duration: ${duration}ms"

For configuration details, see Configuration Reference.
For basic usage, see User Guide.
For plugin development, see Plugin System.