helper scripts

README.md

@@ -5,11 +5,21 @@ A Qt6-based image gallery application that allows you to search through OCR data
 ## Features
 
 - Fast visual navigation through your screenshot collection
-- Ultra-responsive live search through OCR text as you type with optimized performance
+- Non-blocking UI with background threaded search operations
+- Smart typing detection with 500ms inactivity timer before searching
+- Visual feedback while typing and searching with animated status indicators
+- Settings dialog to customize database location and screenshots directory
+- Settings stored in ~/.config/ScreenshotOCRGallery/settings.ini for easy access
+- Customizable image preload count for performance tuning
+- Prominent "Load More Images" button for easy one-click pagination
+- Optimized lazy loading that only loads images when needed
+- Ultra-responsive live search through OCR text using SQLite FTS5 full-text search technology
+- Extremely fast search even with large databases containing thousands of screenshots
 - Dynamic grid layout that automatically reflows (1x, 2x, 3x, 4x, etc.) based on window width
 - No horizontal scrollbars - content always fits the window width
-- Filename overlay at the bottom of each image for easy identification
+- Dynamic filename overlay at the bottom of each image that scales with the thumbnail width
 - Opens images in your default image viewer on click
+- Menu bar with File options (Open, Open With, Settings, Quit)
 - Minimal 2px spacing between images for a compact view
 - Proper error handling for missing files and database issues
 
@@ -88,17 +98,76 @@ After building, run the application:
 
 ## Usage
 
-1. When the application starts, it will display all screenshots found in the database
-2. Type in the search bar to filter images by OCR text content
-3. Results update instantly as you type with optimized search performance
-4. When you clear the search bar, all images are immediately shown
+1. When the application starts, it will display the first batch of screenshots (20 by default)
+2. Click the large "Load More Images" button at the end of the gallery to load additional images with a single click
+3. Type in the search bar to filter images by OCR text content
+4. The app waits for you to stop typing (500ms pause) before performing the search
+5. Animated status indicators show when you're typing and when searching is in progress
+6. Search happens in the background - UI stays responsive even during complex searches
+7. Results update instantly as they become available, loading only what you can see
+8. When you clear the search bar, the first batch of images loads immediately
 5. Resize the application window to see the grid automatically reflow:
    - Wider windows show more columns (4x, 5x, etc.)
    - Narrower windows reduce to fewer columns (3x, 2x)
    - Very narrow windows show a single centered column (1x)
    - No horizontal scrolling - content always fits the available width
-6. Each image displays its filename at the bottom for easy identification
+6. Each image displays its filename at the bottom with a dark overlay that resizes with the thumbnail
 7. Click on any image to open it in your default image viewer
+8. Use the File menu for additional options:
+   - Open: Select and open an image file
+   - Open With: Choose a program to open an image file
+   - Settings: Configure your database path and screenshots directory
+   - Quit: Exit the application
+
+9. Configure the application through the Settings dialog:
+   - Database File Path: Change where your OCR database is stored
+   - Screenshots Directory: Set the default location for your screenshots
+   - Image count to pre-load: Adjust how many images are loaded at once (default: 20)
+   - The settings are automatically saved to ~/.config/ScreenshotOCRGallery/settings.ini
+   - Changes are applied immediately without requiring a restart
+
+## Search Technology
+
+This application combines multiple performance-enhancing technologies:
+
+### 1. Customizable Configuration
+- **Settings Dialog:** Easily configure database location, screenshots directory, and preload count
+- **File Path Selection:** Browse for locations using native file pickers
+- **Persistent Settings:** Your configuration is saved in ~/.config/ScreenshotOCRGallery/settings.ini
+- **Performance Tuning:** Adjust how many images are preloaded (20 by default)
+- **Dynamic Updates:** Changes are applied immediately without requiring a restart
+
+### 2. Intelligent Input Handling
+- **Typing Inactivity Detection:** Search only triggers after 500ms of no typing
+- **Visual Feedback:** Animated status indicators show typing and searching states
+- **Immediate Response:** UI instantly acknowledges your input
+- **Efficient Processing:** Prevents wasteful searches while you're still typing
+
+### 3. Lazy Loading & Pagination
+- **Initial Fast Load:** Only loads a configurable batch of images (default: 20) for immediate display
+- **Prominent Load More Button:** Large, clearly visible button at the end of the image list for loading more images
+- **Customizable Batch Size:** Adjust the number of images loaded at once via settings
+- **Optimized Memory Usage:** Only keeps necessary images in memory
+- **Built-in Progress Tracking:** Button dynamically updates to show current progress (e.g., "Load More Images (20 of 157)")
+- **Simple Interaction:** One-click loading of additional images without needing to scroll
+
+### 4. Background Threading
+- **Non-Blocking UI:** All search operations happen in background threads
+- **Responsive Interface:** The application remains fully responsive while searching
+- **Parallel Processing:** Search operations don't block the main UI thread
+- **Live Updates:** Results appear as they become available
+
+### 5. Full-Text Search
+- **What is FTS5?** A powerful full-text search engine built into SQLite that uses specialized indexing
+- **Performance Benefits:** Up to 100× faster than standard LIKE queries for text searches
+- **Smart Search:** Supports word stemming, prefix matches, and phrase queries
+- **Automatic Fallback:** If FTS5 is not available, the app automatically falls back to standard search
+
+### 6. Search Result Caching
+- **Paginated Cache:** Results are cached by page for efficient retrieval
+- **Smart Invalidation:** Cache expires after 5 minutes to ensure fresh results
+- **Thread-Safe:** The cache is protected for concurrent access
+- **Memory Efficient:** Only stores what's needed, with automatic cleanup
 
 ## Troubleshooting