Screenshot Capture Feature

Overview

KeyClipper's screenshot capture feature automatically takes screenshots of your source applications whenever you copy content to the clipboard. This provides valuable context for your clipboard entries, helping you remember what you were looking at when you copied specific content.

How It Works

Automatic Capture

• When you copy text or images, KeyClipper automatically captures a screenshot of the source application window
• Screenshots are captured in the background without interrupting your workflow
• Each screenshot is associated with its corresponding clipboard entry

Note: This is an optional feature that you can enable or disable in KeyClipper's settings at any time.

Setup & Configuration

Enabling Screenshot Capture

1. Open KeyClipper's settings window
2. Navigate to the "Screenshots" section
3. Toggle "Capture screenshot of source app on copy" to ON
4. The setting is saved automatically

Required Permissions

Screen Recording Permission: macOS requires this permission for screenshot capture

How to Grant:

1. Go to System Preferences > Security & Privacy > Privacy > Screen Recording
2. Find KeyClipper in the list
3. Check the box to enable screen recording access
4. Restart KeyClipper if prompted

Using Screenshot Viewing

Visual Indicators

• Entries with screenshots display a small "→" arrow in the top-right corner
• This indicator helps you quickly identify which entries have associated screenshots

Viewing Screenshots

1. Select an Entry: Use arrow keys or mouse to select a clipboard entry
2. View Screenshot: Press the right arrow key to view the screenshot
3. Return to List: Press the left arrow key or escape key to return

Screenshot View Features

• Full-Screen Display: Screenshots are shown in full-screen mode
• Smooth Transitions: Animated transitions between list and screenshot views
• State Preservation: Your selection and list position are maintained when returning
• Fallback Message: If a screenshot file is missing, a helpful message is displayed

Technical Details

Storage

• Screenshots are saved as JPEG files with 85% compression
• Location: ~/Library/Application Support/KeyClip/screenshots/
• Naming: {entryId}.jpg (where entryId is the clipboard entry's database ID)

Performance

• Screenshots are captured on a background thread to avoid UI blocking
• Uses macOS 14+ ScreenCaptureKit API for high-quality captures
• Efficient storage and retrieval for optimal performance

Database Integration

• Each clipboard entry includes a hasScreenshot flag
• This flag indicates whether a screenshot exists for the entry
• The flag is set when the entry is created based on your settings

Troubleshooting

Screenshot Not Capturing

1. Check Permissions: Ensure Screen Recording permission is granted
2. Verify Settings: Confirm screenshot capture is enabled in settings
3. Restart App: Try restarting KeyClipper after granting permissions

Screenshot Not Displaying

1. Check Indicator: Look for the "→" arrow in the entry's top-right corner
2. File System: Verify the screenshot file exists in the screenshots directory
3. Database: The entry should have hasScreenshot = true in the database

Performance Issues

• Screenshots are captured asynchronously to avoid performance impact
• Large numbers of screenshots may use significant disk space
• Consider periodically cleaning up old screenshots if needed

Use Cases

Research & Documentation

• Capture screenshots while researching topics
• Maintain context for copied quotes or data
• Create visual references for documentation

Development & Debugging

• Capture error messages and UI states
• Document application behavior
• Share visual context with team members

Content Creation

• Save visual references for articles or presentations
• Capture design inspiration and layouts
• Maintain context for copied content

Tips & Best Practices

1. Enable When Needed: Turn on screenshot capture only when you need it to save disk space
2. Regular Cleanup: Periodically review and delete old screenshots
3. Keyboard Shortcuts: Learn the arrow key shortcuts for efficient navigation
4. Visual Indicators: Use the arrow indicators to quickly identify entries with screenshots

Privacy & Security

• Screenshots are stored locally on your device
• No screenshots are transmitted or shared
• You have full control over when screenshots are captured
• Screenshots can be manually deleted from the file system