### Install qimgv on OpenSUSE

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use zypper to install qimgv on OpenSUSE.

```bash
zypper install qimgv
```

--------------------------------

### Install qimgv

Source: https://github.com/easymodo/qimgv/wiki/Compiling-qimgv-from-source

Installs the compiled qimgv application to the system.

```bash
sudo make install
```

--------------------------------

### Install qimgv on Gentoo

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use emerge to install qimgv on Gentoo.

```bash
emerge qimgv
```

--------------------------------

### Install Dependencies on Ubuntu (20.04)

Source: https://github.com/easymodo/qimgv/wiki/Compiling-qimgv-from-source

Installs essential build tools and qimgv dependencies for Ubuntu 20.04.

```bash
sudo apt install build-essential git cmake qt5-default libqt5svg5-dev qttools5-dev libexiv2-dev libmpv-dev libopencv-dev kimageformat-plugins gcc g++
```

--------------------------------

### Install qimgv on FreeBSD

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use pkg to install qimgv on FreeBSD.

```bash
pkg install qimgv
```

--------------------------------

### Install qimgv on Void Linux

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use xbps-install to install qimgv on Void Linux.

```bash
xbps-install -S qimgv
```

--------------------------------

### Install qimgv on Fedora

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use dnf to install qimgv on Fedora.

```bash
sudo dnf install qimgv
```

--------------------------------

### Install Dependencies on Ubuntu (21.04+)

Source: https://github.com/easymodo/qimgv/wiki/Compiling-qimgv-from-source

Installs essential build tools and qimgv dependencies for Ubuntu 21.04 and later.

```bash
sudo apt install build-essential git cmake qtbase5-dev libqt5svg5-dev qttools5-dev libexiv2-dev libmpv-dev libopencv-dev kimageformat-plugins gcc g++
```

--------------------------------

### Install qimgv with WinGet on Windows

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use this command to install qimgv on Windows via the WinGet package manager.

```bash
winget install --id easymodo.qimgv
```

--------------------------------

### Install qimgv on Ubuntu/Debian-based systems

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use apt to install qimgv on Ubuntu, Linux Mint, Pop!_OS, and similar distributions.

```bash
sudo apt install qimgv
```

--------------------------------

### Install qimgv on Alpine Linux

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use apk to install qimgv on Alpine Linux.

```bash
apk add qimgv
```

--------------------------------

### Install qimgv with Chocolatey on Windows

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Use this command to install qimgv on Windows via the Chocolatey package manager.

```bash
choco install qimgv
```

--------------------------------

### Install Dependencies on Fedora

Source: https://github.com/easymodo/qimgv/wiki/Compiling-qimgv-from-source

Installs necessary build tools and qimgv dependencies on Fedora, requiring RPMFusion for video playback.

```bash
sudo dnf install git cmake make qt5-qtbase qt5-qtbase-devel qt5-qtsvg qt5-qtsvg-devel qt5-linguist gcc-c++ mpv mpv-libs-devel exiv2-devel opencv opencv-devel
```

--------------------------------

### Configure qimgv Build with KDE Support

Source: https://github.com/easymodo/qimgv/wiki/Compiling-qimgv-from-source

Configures the qimgv build with CMake, enabling KDE support and specifying installation prefix.

```bash
cmake ../ -DKDE_SUPPORT=ON  -DCMAKE_INSTALL_PREFIX=/usr/
```

--------------------------------

### Build qimgv from Source (Ubuntu)

Source: https://context7.com/easymodo/qimgv/llms.txt

Installs dependencies and builds qimgv from source using CMake. Ensure you have the correct dependencies for your desired features.

```bash
# Ubuntu 21.04+ – install all dependencies
sudo apt install build-essential git cmake \
    qtbase5-dev libqt5svg5-dev qttools5-dev \
    libexiv2-dev libmpv-dev libopencv-dev gcc g++

# Clone and build
git clone https://github.com/easymodo/qimgv.git
cd qimgv
mkdir -p build && cd build

# Default build (OpenCV + exiv2 + video enabled, Qt5 preferred)
cmake ../ -DCMAKE_INSTALL_PREFIX=/usr/ -DCMAKE_INSTALL_LIBDIR=lib
make
sudo make install

# Build with KDE blur support, no video
cmake ../ \
    -DCMAKE_INSTALL_PREFIX=/usr/ \
    -DKDE_SUPPORT=ON \
    -DVIDEO_SUPPORT=OFF

# Build preferring Qt6, no OpenCV
cmake ../ \
    -DCMAKE_INSTALL_PREFIX=/usr/ \
    -DUSE_QT5=OFF \
    -DOPENCV_SUPPORT=OFF
```

--------------------------------

### Install qimgv via Package Managers

Source: https://context7.com/easymodo/qimgv/llms.txt

Installs qimgv using various package managers for different operating systems. Choose the command appropriate for your system.

```bash
# Windows – Chocolatey
choco install qimgv

# Windows – WinGet
winget install --id easymodo.qimgv

# Ubuntu / Debian / Linux Mint / Pop!_OS
sudo apt install qimgv

# Fedora (enable RPMFusion first for video support)
sudo dnf install qimgv

# Arch Linux / Manjaro (AUR)
yay -S qimgv-git      # or any AUR helper

# OpenSUSE
zypper install qimgv

# Gentoo
emerge qimgv

# Void Linux
xbps-install -S qimgv

# Alpine Linux
apk add qimgv

# FreeBSD
pkg install qimgv
```

--------------------------------

### Install qimgv from AUR on Arch Linux

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Install the qimgv-git package from the Arch User Repository (AUR).

```bash
qimgv-git
```

--------------------------------

### Configure qimgv Build with CMake

Source: https://github.com/easymodo/qimgv/wiki/Compiling-qimgv-from-source

Configures the qimgv build using CMake, specifying installation prefix and library directory.

```bash
cmake ../ -DCMAKE_INSTALL_PREFIX=/usr/ -DCMAKE_INSTALL_LIBDIR=lib
```

--------------------------------

### Querying Script Information with ScriptManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Demonstrates how to check if a script exists by name, retrieve a list of all registered script names, and get the configuration for a specific script.

```cpp
// --- Query ---
bool exists = sm->scriptExists("Convert to PDF");  // true
QList<QString> names = sm->scriptNames();           // ["Convert to PDF", "Open in GIMP"]
Script s = sm->getScript("Open in GIMP");
```

--------------------------------

### Run Shell Command for Image Conversion

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Example of a shell command to convert an image file to PDF. The `%file%` placeholder represents the current image path.

```bash
convert %file% %file%_.pdf
```

--------------------------------

### Execute a Shell Script on an Image

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Example of a shell script that takes an image path as an argument (`$1`) and opens it with GIMP. Ensure the script is executable and has a shebang.

```bash
#!/bin/bash
gimp "$1"
```

--------------------------------

### Translation Workflow with Qt Linguist

Source: https://context7.com/easymodo/qimgv/llms.txt

Instructions for adding new translations to qimgv. This involves installing Qt Linguist, managing .ts files, and submitting translated files.

```bash
# 1. Install Qt Linguist
#    Windows: https://github.com/easymodo/qt-builds/releases/tag/5.15.3-linguist
#    Linux:   sudo apt install qttools5-dev-tools

# 2. Download the base English translation file
wget https://raw.githubusercontent.com/easymodo/qimgv/master/qimgv/res/translations/en_US.ts

# 3. Rename for your locale
cp en_US.ts de_DE.ts   # example: German

# 4. Open in Qt Linguist, set target language:
#    Edit > Translation File Settings > Target Language = German / Germany
#    Translate all strings, then File > Save

# 5. To generate a new .ts from source (maintainer workflow):
cd qimgv
lupdate -recursive . -ts res/translations/de_DE.ts

# 6. Compile .ts → .qm during build (automatic via CMake)
#    Add "de_DE.ts" to TS_FILES list in qimgv/CMakeLists.txt

# 7. Submit the translated .ts file via:
#    - Pull request to github.com/easymodo/qimgv
#    - GitHub issue
#    - Email: easymodofrf@gmail.com

# Currently shipped locales:
# zh_CN  uk_UA  es_ES  de_DE  fr_FR  tr_TR  ja_JP
```

--------------------------------

### Core: Application Initialization and Path Loading

Source: https://context7.com/easymodo/qimgv/llms.txt

Shows the typical application entry point using the `Core` component and how to load a specific image file or an entire directory. The `showGui` method initializes and displays the main window.

```cpp
#include "core.h"

// Typical application entry point (from main.cpp)
Core core;
core.showGui();           // initialise and display the main window

// --- Open a path (image file or directory) ---
bool ok = core.loadPath("/home/user/photos/DSC001.jpg");
bool ok = core.loadPath("/home/user/photos/");
```

--------------------------------

### Configure Qimgv Runtime Settings

Source: https://context7.com/easymodo/qimgv/llms.txt

This C++ code demonstrates how to access and modify application settings using the `Settings` singleton. It covers various aspects of image display, UI, slideshows, sorting, folder views, zoom, and save quality. Ensure `settings.h` is included and the `Settings` singleton is accessed correctly.

```cpp
#include "settings.h"

// Access the singleton
Settings *s = Settings::getInstance();

// --- Image display ---
s->setImageFitMode(FIT_WIDTH);          // FIT_WINDOW | FIT_WIDTH | FIT_ORIGINAL | FIT_WINDOW_STRETCH | FIT_FREE
s->setExpandImage(true);                // expand small images to fill fit mode
s->setExpandLimit(200);                 // max expand percent (200 = up to 2×)
s->setSmoothUpscaling(true);
s->setScalingFilter(QI_FILTER_CV_CUBIC); // nearest | bilinear | cv_bilinear_sharpen | cv_cubic | cv_cubic_sharpen

// --- Panel & UI ---
s->setPanelEnabled(true);
s->setPanelPosition(PANEL_BOTTOM);      // PANEL_TOP | PANEL_BOTTOM | PANEL_LEFT | PANEL_RIGHT
s->setPanelPreviewsSize(120);           // thumbnail size in px
s->setSquareThumbnails(false);
s->setPanelFullscreenOnly(false);

// --- Slideshow ---
s->setSlideshowInterval(3000);          // ms between slides
s->setLoopSlideshow(true);

// --- Sorting ---
s->setSortingMode(SORT_NAME);           // SORT_NAME | SORT_NAME_DESC | SORT_SIZE | SORT_SIZE_DESC | SORT_TIME | SORT_TIME_DESC
s->setSortFolders(true);

// --- Folder view ---
s->setDefaultViewMode(MODE_DOCUMENT);   // MODE_DOCUMENT | MODE_FOLDERVIEW
s->setFolderViewIconSize(120);
s->setFolderViewMode(FV_EXTENDED);      // FV_SIMPLE | FV_EXTENDED | FV_EXT_FOLDERS
s->setFolderEndAction(FOLDER_END_LOOP); // FOLDER_END_NO_ACTION | FOLDER_END_LOOP | FOLDER_END_GOTO_ADJACENT

// --- Zoom ---
s->setZoomStep(0.1f);                   // zoom increment per step
s->setUseFixedZoomLevels(false);
s->setZoomLevels("10,25,50,75,100,150,200,400");

// --- Save quality ---
s->setJPEGSaveQuality(95);              // 1–100

// --- Misc ---
s->setFullscreenMode(false);
s->setCursorAutohide(true);
s->setConfirmDelete(true);
s->setLanguage("en_US");
s->setMemoryAllocationLimit(512);       // MB

// Persist all changes
s->sync();
```

--------------------------------

### Launch qimgv Application

Source: https://context7.com/easymodo/qimgv/llms.txt

Launches the qimgv image viewer from the command line. You can specify an image or directory to open, or override HiDPI scaling.

```bash
# Open a specific image
qimgv /path/to/image.png

# Open a directory (shows first image; folder view available)
qimgv /path/to/photos/

# Override HiDPI scale factor (Linux / macOS)
QT_SCALE_FACTOR="1.5" qimgv /path/to/image.png

# Persist HiDPI override via .desktop file
# Edit /usr/share/applications/qimgv.desktop:
# Exec=env QT_SCALE_FACTOR=1.5 qimgv %f
```

--------------------------------

### DirectoryManager: Load and Query Files

Source: https://context7.com/easymodo/qimgv/llms.txt

Demonstrates loading a directory, setting sorting modes, and querying file and directory counts. Ensure sorting mode is set before loading for immediate effect.

```cpp
#include "components/directorymanager/directorymanager.h"

DirectoryManager dm;

// --- Load a directory ---
dm.setSortingMode(SORT_TIME_DESC);   // sort before loading
bool ok = dm.setDirectory("/home/user/photos");
// or load entire subtree:
dm.setDirectoryRecursive("/home/user/photos");

// --- Query counts ---
unsigned long imgCount = dm.fileCount();   // supported image/video files
unsigned long dirCount = dm.dirCount();    // subdirectory entries
unsigned long total    = dm.totalCount();
```

--------------------------------

### Querying and Modifying Shortcuts with ActionManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Demonstrates how to query existing shortcuts for actions, add new shortcuts, remove them, and manage default settings. Persist changes using saveShortcuts().

```cpp
#include "components/actionmanager/actionmanager.h"

ActionManager *am = ActionManager::getInstance();

// --- Query shortcuts ---
QString shortcut = am->shortcutForAction("nextImage");  // e.g. "Right"
QList<QString> all = am->shortcutsForAction("zoomIn");  // multiple shortcuts per action
QString action = am->actionForShortcut("Ctrl+S");       // "saveFile"

// --- Modify shortcuts ---
am->addShortcut("Ctrl+Right", "nextImage");
am->removeShortcut("Ctrl+Right");
am->removeAllShortcuts("nextImage");      // remove all shortcuts for one action
am->resetDefaults("nextImage");           // restore factory default for one action
am->resetDefaults();                      // restore all factory defaults
am->saveShortcuts();                      // persist to settings
```

--------------------------------

### ActionManager - Query and Modify Shortcuts

Source: https://context7.com/easymodo/qimgv/llms.txt

Demonstrates how to query existing shortcuts for actions, add new shortcuts, remove shortcuts, and reset them to defaults.

```APIDOC
## ActionManager - Shortcut Management

### Description
Manages keyboard and mouse shortcuts for named actions, allowing for runtime reconfiguration.

### Methods
- `shortcutForAction(actionName)`: Returns the shortcut string for a given action.
- `shortcutsForAction(actionName)`: Returns a list of all shortcuts for a given action.
- `actionForShortcut(shortcut)`: Returns the action name associated with a shortcut.
- `addShortcut(shortcut, actionName)`: Adds a new shortcut for an action.
- `removeShortcut(shortcut)`: Removes a specific shortcut.
- `removeAllShortcuts(actionName)`: Removes all shortcuts associated with an action.
- `resetDefaults(actionName)`: Restores the factory default shortcut for a specific action.
- `resetDefaults()`: Restores all factory default shortcuts.
- `saveShortcuts()`: Persists the current shortcut configurations to settings.

### Example Usage
```cpp
#include "components/actionmanager/actionmanager.h"

ActionManager *am = ActionManager::getInstance();

// Query shortcuts
QString shortcut = am->shortcutForAction("nextImage");
QList<QString> all = am->shortcutsForAction("zoomIn");
QString action = am->actionForShortcut("Ctrl+S");

// Modify shortcuts
am->addShortcut("Ctrl+Right", "nextImage");
am->removeShortcut("Ctrl+Right");
am->removeAllShortcuts("nextImage");
am->resetDefaults("nextImage");
am->resetDefaults();
am->saveShortcuts();
```
```

--------------------------------

### Displaying Content with MW

Source: https://context7.com/easymodo/qimgv/llms.txt

Use these methods to display various types of content in the main window. Ensure necessary support (like VIDEO_SUPPORT) is enabled for video playback.

```cpp
mw->showImage(std::move(pixmap));                // QPixmap
```

```cpp
mw->showAnimation(movie);                        // QMovie (animated GIF etc.)
```

```cpp
mw->showVideo("/path/to/clip.webm");             // path (requires VIDEO_SUPPORT)
```

--------------------------------

### Configure Qt6 Test and Widgets for Executable

Source: https://github.com/easymodo/qimgv/blob/master/qimgv/tests/CMakeLists.txt

Finds the required Qt6 components (Test and Widgets) for building the test executable. This is a prerequisite for linking the test application against Qt's testing framework and GUI elements.

```cmake
find_package(Qt6 REQUIRED COMPONENTS Test Widgets)
```

--------------------------------

### Clone qimgv Repository and Prepare Build Directory

Source: https://github.com/easymodo/qimgv/wiki/Compiling-qimgv-from-source

Clones the qimgv source code from GitHub and creates a build directory.

```bash
git clone https://github.com/easymodo/qimgv.git
cd qimgv && mkdir -p build && cd build
```

--------------------------------

### Running Scripts on Images with ScriptManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Illustrates how to execute a registered script on a given image. This is typically invoked by the Core module via an ActionManager signal.

```cpp
// --- Run a script on the current image ---
// (typically invoked by Core via ActionManager signal)
std::shared_ptr<Image> img = /* current image */;
sm->runScript("Convert to PDF", img);
```

--------------------------------

### Define Test Executable and Link Qt6 Libraries

Source: https://github.com/easymodo/qimgv/blob/master/qimgv/tests/CMakeLists.txt

Defines the 'unit_tests' executable and links it against the found Qt6 Test and Widgets components. This ensures the test application has access to Qt's testing utilities and GUI functionalities.

```cmake
add_executable(unit_tests test_mapoverlay.cpp)
target_link_libraries(unit_tests PRIVATE Qt6::Test Qt6::Widgets)
```

--------------------------------

### Compile qimgv

Source: https://github.com/easymodo/qimgv/wiki/Compiling-qimgv-from-source

Compiles the qimgv application using the Make build system.

```bash
make
```

--------------------------------

### Defining and Registering Scripts with ScriptManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Shows how to define shell scripts, either as inline commands or external files, and register them with ScriptManager. Scripts are persisted to settings.

```cpp
#include "components/scriptmanager/scriptmanager.h"
#include "utils/script.h"

ScriptManager *sm = ScriptManager::getInstance();

// --- Define a script ---
Script convertToPdf;
convertToPdf.command = "convert %file% %file%_.pdf";  // %file% → current image path
convertToPdf.isFile  = false;   // inline shell command

Script openInGimp;
openInGimp.path   = "/home/user/scripts/open_gimp.sh";  // $1 = image path
openInGimp.isFile = true;

// --- Register scripts ---
sm->addScript("Convert to PDF", convertToPdf);
sm->addScript("Open in GIMP",   openInGimp);
sm->saveScripts();  // persist
```

--------------------------------

### ActionManager - Invoke and Process Events

Source: https://context7.com/easymodo/qimgv/llms.txt

Shows how to programmatically invoke actions and process raw input events.

```APIDOC
## ActionManager - Action Invocation and Event Processing

### Description
Allows for programmatic invocation of actions and processing of raw input events to trigger actions.

### Methods
- `invokeAction(actionName)`: Programmatically triggers a named action.
- `processEvent(event)`: Processes a raw input event (e.g., QKeyEvent) and returns true if a bound action was triggered.
- `actionList()`: Returns a list of all available action names.

### Example Usage
```cpp
#include "components/actionmanager/actionmanager.h"
#include <QKeyEvent>

ActionManager *am = ActionManager::getInstance();

// Programmatically invoke an action
am->invokeAction("nextImage");
am->invokeAction("toggleFullscreen");

// Process a raw input event
QKeyEvent *ev = new QKeyEvent(QEvent::KeyPress, Qt::Key_Right, Qt::NoModifier);
bool handled = am->processEvent(ev);

// List all available actions
QStringList actions = am->actionList();
```
```

--------------------------------

### Overlays and Panels with MW

Source: https://context7.com/easymodo/qimgv/llms.txt

Control the visibility and interaction of various overlays and panels, such as crop, settings, and info displays. Some panels can be triggered by keyboard shortcuts.

```cpp
mw->showCropPanel();
```

```cpp
mw->hideCropPanel();
```

```cpp
mw->triggerCopyOverlay();     // quick-copy panel (C key)
```

```cpp
mw->triggerMoveOverlay();     // quick-move panel (M key)
```

```cpp
mw->showSettings();
```

```cpp
mw->toggleImageInfoOverlay(); // EXIF info (I key)
```

```cpp
mw->toggleFullscreenInfoBar();
```

```cpp
mw->toggleRenameOverlay("DSC001.jpg");
```

--------------------------------

### ScriptManager - Define and Register Scripts

Source: https://context7.com/easymodo/qimgv/llms.txt

Explains how to define script objects and register them with the ScriptManager.

```APIDOC
## ScriptManager - Script Definition and Registration

### Description
Manages named shell scripts that operate on the currently viewed image. Scripts can be defined with inline commands or external files and are persisted.

### Methods
- `addScript(name, script)`: Registers a script with a given name.
- `saveScripts()`: Persists the registered scripts to settings.

### Script Object Structure
```cpp
struct Script {
    QString command; // Inline command string
    QString path;    // Path to an executable script file
    bool isFile;     // True if path points to a file, false for inline command
};
```

### Example Usage
```cpp
#include "components/scriptmanager/scriptmanager.h"
#include "utils/script.h"

ScriptManager *sm = ScriptManager::getInstance();

// Define a script (inline command)
Script convertToPdf;
convertToPdf.command = "convert %file% %file%_.pdf";
convertToPdf.isFile  = false;

// Define a script (external file)
Script openInGimp;
openInGimp.path   = "/home/user/scripts/open_gimp.sh";
openInGimp.isFile = true;

// Register scripts
sm->addScript("Convert to PDF", convertToPdf);
sm->addScript("Open in GIMP",   openInGimp);
sm->saveScripts();
```
```

--------------------------------

### Setting Scaling Filters with MW

Source: https://context7.com/easymodo/qimgv/llms.txt

Configure the image scaling filter used by the viewer. Options range from nearest-neighbor to bilinear and cubic filters. `toggleScalingFilter()` cycles through available filters.

```cpp
mw->setFilterNearest();
```

```cpp
mw->setFilterBilinear();
```

```cpp
mw->setFilter(QI_FILTER_CV_CUBIC);
```

```cpp
mw->toggleScalingFilter();
```

--------------------------------

### Dialogs

Source: https://context7.com/easymodo/qimgv/llms.txt

Methods to invoke standard file dialogs and other configuration dialogs.

```APIDOC
## Dialogs

### `showOpenDialog(const char *initialDir)`
Opens a file dialog to select files, starting in the specified directory.

### `showResizeDialog(QSize size)`
Opens a dialog for resizing images, pre-filled with the given size.

### `getSaveFileName(const char *defaultName)`
Opens a file save dialog, suggesting a default filename.
```

--------------------------------

### Display Content

Source: https://context7.com/easymodo/qimgv/llms.txt

Methods to display various types of content within the main window, including static images, animations, and videos.

```APIDOC
## Display Content

### `showImage(QPixmap pixmap)`
Displays a static image.

### `showAnimation(QMovie movie)`
Displays an animated image format like GIF.

### `showVideo(const char *path)`
Displays a video file. Requires VIDEO_SUPPORT.
```

--------------------------------

### DirectoryManager: Index and Adjacency Lookup

Source: https://context7.com/easymodo/qimgv/llms.txt

Provides methods for looking up file indices, retrieving file paths and names by index, and navigating to the first/last files. Also includes functions for finding the next and previous files or directories.

```cpp
// --- Index lookup ---
int idx = dm.indexOfFile("/home/user/photos/DSC001.jpg");  // -1 if not found
QString path = dm.filePathAt(0);    // first file in sorted order
QString name = dm.fileNameAt(0);    // basename only
QString last = dm.lastFile();
QString first = dm.firstFile();

// --- Adjacency navigation ---
QString next = dm.nextOfFile("/home/user/photos/DSC001.jpg");
QString prev = dm.prevOfFile("/home/user/photos/DSC001.jpg");

// --- Directory navigation ---
QString nextDir = dm.nextOfDir("/home/user/photos/vacation");
QString prevDir = dm.prevOfDir("/home/user/photos/vacation");
```

--------------------------------

### Core

Source: https://context7.com/easymodo/qimgv/llms.txt

The central application controller that manages the DirectoryModel, GUI, image loading, caching, and file operations.

```APIDOC
## Core — Application Controller

The central application controller that manages the DirectoryModel, GUI, image loading, caching, and file operations.

### Methods

- **showGui()**: Initializes and displays the main application window.
- **loadPath(const QString &path)**: Opens and loads the specified image file or directory. Returns true if successful.

### Actions (Slots)

These actions are typically triggered via signals from other components (e.g., ActionManager) and represent the core functionality:

- **nextImage()**: Displays the next image.
- **prevImage()**: Displays the previous image.
- **jumpToFirst()**: Navigates to the first image in the list.
- **jumpToLast()**: Navigates to the last image in the list.
- **rotateLeft()**: Rotates the current image 90 degrees counter-clockwise.
- **rotateRight()**: Rotates the current image 90 degrees clockwise.
- **flipH()**: Flips the current image horizontally.
- **flipV()**: Flips the current image vertically.
- **crop(QRect rect)**: Crops the current image to the specified rectangle.
- **cropAndSave(QRect rect)**: Crops the current image to the specified rectangle and saves it.
- **resize(QSize size)**: Resizes the current image to the specified dimensions.
- **saveCurrentFile()**: Saves changes to the current image file.
- **saveCurrentFileAs(QString destPath)**: Saves the current image file to a new location.
- **moveToTrash()**: Moves the current file to the system's trash.
- **removePermanent()**: Permanently deletes the current file.
- **copyCurrentFile(QString destDir)**: Copies the current file to the specified destination directory.
- **moveCurrentFile(QString destDir)**: Moves the current file to the specified destination directory.
- **toggleSlideshow()**: Toggles the slideshow mode.
- **toggleShuffle()**: Toggles shuffle playback for the slideshow.
- **toggleFolderView()**: Toggles the folder view mode.
- **enableFolderView()**: Enables the folder view mode.
- **enableDocumentView()**: Enables the document view mode.
- **reloadImage()**: Reloads the current image from disk.
- **copyFileClipboard()**: Copies the current image file to the clipboard.
- **copyPathClipboard()**: Copies the path of the current file to the clipboard.
- **openFromClipboard()**: Opens an image from the clipboard.
- **runScript(const QString &scriptName)**: Executes a specified script.
- **setWallpaper()**: Sets the current image as the desktop wallpaper.
- **sortByName()**: Sorts the image list by name.
- **sortByTime()**: Sorts the image list by time.
- **sortBySize()**: Sorts the image list by size.
- **print()**: Prints the current image.
```

--------------------------------

### Executing Commands with ScriptManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Shows how to run external shell commands. `runCommand` is blocking and returns the output, while `runCommandDetached` executes the command without waiting for completion.

```cpp
// --- One-shot command execution (blocking) ---
QString output = ScriptManager::runCommand("exiftool /path/to/image.jpg");

// --- One-shot detached execution ---
ScriptManager::runCommandDetached("gimp /path/to/image.png");
```

--------------------------------

### ScriptManager - Query and Run Scripts

Source: https://context7.com/easymodo/qimgv/llms.txt

Covers querying script information, running registered scripts on images, and executing commands.

```APIDOC
## ScriptManager - Script Querying and Execution

### Description
Provides functionality to check for script existence, retrieve script names, get script details, run registered scripts on images, and execute arbitrary shell commands.

### Methods
- `scriptExists(name)`: Returns true if a script with the given name is registered.
- `scriptNames()`: Returns a list of all registered script names.
- `getScript(name)`: Returns the `Script` object for a given name.
- `runScript(name, image)`: Executes a registered script on a given image.
- `runCommand(command)`: Executes a shell command and returns its output (blocking).
- `runCommandDetached(command)`: Executes a shell command in a detached process.
- `removeScript(name)`: Removes a registered script.

### Example Usage
```cpp
#include "components/scriptmanager/scriptmanager.h"
#include "utils/script.h"
#include <memory>
#include "image.h"

ScriptManager *sm = ScriptManager::getInstance();

// Query scripts
bool exists = sm->scriptExists("Convert to PDF");
QList<QString> names = sm->scriptNames();
Script s = sm->getScript("Open in GIMP");

// Run a script on the current image
std::shared_ptr<Image> img = /* current image */;
sm->runScript("Convert to PDF", img);

// One-shot command execution
QString output = ScriptManager::runCommand("exiftool /path/to/image.jpg");
ScriptManager::runCommandDetached("gimp /path/to/image.png");

// Remove a script
sm->removeScript("Convert to PDF");
```
```

--------------------------------

### Listing Available Actions with ActionManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Provides a method to retrieve a list of all available action names managed by ActionManager. This can be used for introspection or UI generation.

```cpp
// --- List all available action names ---
QStringList actions = am->actionList();
// e.g. ["nextImage", "prevImage", "zoomIn", "zoomOut", "crop", "resize",
//        "rotateLeft", "rotateRight", "flipH", "flipV", "saveFile", ...]
```

--------------------------------

### DirectoryManager: File System Change Signals

Source: https://context7.com/easymodo/qimgv/llms.txt

Lists the signals emitted by `DirectoryManager` to indicate live file system changes, such as files being added, removed, modified, or renamed, as well as directory loading completion.

```cpp
// --- Signals emitted on live FS changes ---
// fileAdded(QString filePath)
// fileRemoved(QString filePath, int oldIndex)
// fileModified(QString filePath)
// fileRenamed(QString from, int fromIdx, QString to, int toIdx)
// loaded(const QString &path)
```

--------------------------------

### DirectoryManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Manages loading, indexing, and querying of image and video files within a directory. It supports sorting and provides navigation between files and directories.

```APIDOC
## DirectoryManager — File System Navigation

Manages loading, indexing, and querying of image and video files within a directory. It supports sorting and provides navigation between files and directories.

### Methods

- **setSortingMode(SortingMode mode)**: Sets the sorting mode for directory contents. Supported modes include `SORT_TIME_DESC`, `SORT_NAME`, `SORT_TIME`, `SORT_SIZE`, etc.
- **setDirectory(const QString &path)**: Loads and indexes files from the specified directory. Returns true if successful.
- **setDirectoryRecursive(const QString &path)**: Loads and indexes files from the specified directory and all its subdirectories.
- **fileCount()**: Returns the number of supported image/video files.
- **dirCount()**: Returns the number of subdirectories.
- **totalCount()**: Returns the total number of entries (files and directories).
- **indexOfFile(const QString &filePath)**: Returns the index of a given file in the sorted list, or -1 if not found.
- **filePathAt(int index)**: Returns the full path of the file at the specified index.
- **fileNameAt(int index)**: Returns the base name of the file at the specified index.
- **lastFile()**: Returns the path of the last file in the sorted list.
- **firstFile()**: Returns the path of the first file in the sorted list.
- **nextOfFile(const QString &filePath)**: Returns the path of the file immediately following the given file in the sorted list.
- **prevOfFile(const QString &filePath)**: Returns the path of the file immediately preceding the given file in the sorted list.
- **nextOfDir(const QString &dirPath)**: Returns the path of the directory immediately following the given directory in the sorted list.
- **prevOfDir(const QString &dirPath)**: Returns the path of the directory immediately preceding the given directory in the sorted list.
- **sortingMode()**: Returns the current sorting mode.
- **isSupportedFile(const QString &filePath)**: Checks if the file extension is supported.

### Signals

- **fileAdded(QString filePath)**: Emitted when a new file is added.
- **fileRemoved(QString filePath, int oldIndex)**: Emitted when a file is removed.
- **fileModified(QString filePath)**: Emitted when a file is modified.
- **fileRenamed(QString from, int fromIdx, QString to, int toIdx)**: Emitted when a file is renamed.
- **loaded(const QString &path)**: Emitted when a directory has been loaded.
```

--------------------------------

### Fullscreen Control

Source: https://context7.com/easymodo/qimgv/llms.txt

Methods for toggling and managing the fullscreen display mode.

```APIDOC
## Fullscreen Control

### `showFullScreen()`
Enters fullscreen mode.

### `showWindowed()`
Exits fullscreen mode and returns to windowed mode.

### `triggerFullScreen()`
Toggles between fullscreen and windowed mode.
```

--------------------------------

### CMake Build Options for qimgv

Source: https://context7.com/easymodo/qimgv/llms.txt

Configures the qimgv build using CMake options. These flags enable or disable specific features like video support, OpenCV scaling, and Qt version preference.

```cmake
# CMakeLists.txt option declarations (from root CMakeLists.txt)
option(EXIV2          "For reading/writing exif tags"       ON)
option(VIDEO_SUPPORT  "Enable video support"                ON)
option(OPENCV_SUPPORT "Enable HQ scaling via OpenCV"        ON)
option(KDE_SUPPORT    "Support blur when using KDE"         OFF)
option(USE_QT5        "Build with Qt5 if available"         ON)

# Usage examples
cmake ../ -DVIDEO_SUPPORT=ON  -DKDE_SUPPORT=ON  -DCMAKE_INSTALL_PREFIX=/usr/
cmake ../ -DOPENCV_SUPPORT=OFF -DEXIV2=OFF -DCMAKE_INSTALL_PREFIX=/usr/
cmake ../ -DUSE_QT5=OFF -DCMAKE_INSTALL_PREFIX=/usr/   # force Qt6

# Fix "/usr/lib64 exists in filesystem" install error on some distros
cmake ../ -DCMAKE_INSTALL_PREFIX=/usr/ -DCMAKE_INSTALL_LIBDIR:PATH=/usr/lib

# Specify external Qt path (Linux / macOS)
cmake ../ -DQT_EXTERN_PATH=/opt/Qt/6.2.0/gcc_64 -DCMAKE_INSTALL_PREFIX=/usr/
```

--------------------------------

### Processing Raw Input Events with ActionManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Illustrates how ActionManager processes raw input events like key presses. It returns true if a bound action was triggered by the event, allowing for event handling logic.

```cpp
// --- Process a raw input event (called by MW event handlers) ---
QKeyEvent *ev = new QKeyEvent(QEvent::KeyPress, Qt::Key_Right, Qt::NoModifier);
bool handled = am->processEvent(ev);      // returns true if a bound action was triggered
```

--------------------------------

### Managing Fit Modes with MW

Source: https://context7.com/easymodo/qimgv/llms.txt

Control how images are scaled to fit the window using these MW slots. `switchFitMode()` cycles through all available modes.

```cpp
mw->fitWindow();          // scale image to fit window (letterbox)
```

```cpp
mw->fitWidth();           // scale to window width
```

```cpp
mw->fitOriginal();        // 1:1 pixels
```

```cpp
mw->fitWindowStretch();   // stretch to fill window
```

```cpp
mw->switchFitMode();      // cycle through modes
```

--------------------------------

### Showing Dialogs with MW

Source: https://context7.com/easymodo/qimgv/llms.txt

Open standard file dialogs for opening or saving files, or specific dialogs like the resize dialog. `getSaveFileName()` returns the selected path.

```cpp
mw->showOpenDialog("/home/user/photos");
```

```cpp
mw->showResizeDialog(QSize(1920, 1080));
```

```cpp
QString savePath = mw->getSaveFileName("DSC001.jpg");
```

--------------------------------

### Qimgv Keyboard & Mouse Controls Reference

Source: https://context7.com/easymodo/qimgv/llms.txt

This section lists the default keyboard and mouse shortcuts for various operations in Qimgv. All shortcuts are reconfigurable via the application's settings.

```text
Navigation
──────────
Right arrow / MouseWheel          Next image
Left arrow  / MouseWheel          Previous image
Home                              Go to first image
End                               Go to last image
Enter / Backspace                 Toggle folder view

Zoom
────
Ctrl+MouseWheel / Ctrl+Up         Zoom in
Ctrl+MouseWheel / Ctrl+Down       Zoom out
Hold RMB + drag up/down           Zoom (alternative)
1                                 Fit mode: window
2                                 Fit mode: width
3                                 Fit mode: 1:1 (no scaling)
Space                             Cycle fit modes

View
────
DoubleClick / F / F11             Toggle fullscreen
Esc                               Exit fullscreen
I                                 Show EXIF / image info panel
~                                 Slideshow mode
Ctrl+~                            Shuffle mode

Editing
──────
X                                 Crop image
R                                 Resize image
Ctrl+L                            Rotate left
Ctrl+R                            Rotate right
Ctrl+S                            Save
Ctrl+Shift+S                      Save As

File Management
───────────────
C                                 Quick copy panel
M                                 Quick move panel
  (with panel open: 1–9 keys)     Copy/move to saved directory slot
Delete                            Move to trash
Shift+Delete                      Delete permanently
Ctrl+D                            Open containing directory

Application
──────────
Ctrl+O                            Open file dialog
P                                 Settings
Ctrl+P                            Print / Export PDF
Esc / Ctrl+Q / Alt+X / MiddleClick  Exit
```

--------------------------------

### Invoking Actions Programmatically with ActionManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Shows how to trigger named actions directly through the ActionManager instance. This is useful for programmatic control or when an action is not directly tied to a user input event.

```cpp
// --- Programmatically invoke an action ---
am->invokeAction("nextImage");
am->invokeAction("toggleFullscreen");
am->invokeAction("crop");
```

--------------------------------

### Register Test with CTest

Source: https://github.com/easymodo/qimgv/blob/master/qimgv/tests/CMakeLists.txt

Adds the 'unit_tests' executable as a test named 'QUI_TEST' to the CTest testing suite. This allows the test to be discovered and run using the CTest command-line tool.

```cmake
add_test(NAME QUI_TEST COMMAND unit_tests)
```

--------------------------------

### Fullscreen Controls with MW

Source: https://context7.com/easymodo/qimgv/llms.txt

Manage fullscreen display modes using these MW slots. `triggerFullScreen()` toggles the current fullscreen state.

```cpp
mw->showFullScreen();
```

```cpp
mw->showWindowed();
```

```cpp
mw->triggerFullScreen();  // toggle
```

--------------------------------

### Overlays and Panels

Source: https://context7.com/easymodo/qimgv/llms.txt

Functions to show, hide, or toggle various overlay panels and information displays.

```APIDOC
## Overlays and Panels

### `showCropPanel()`
Displays the cropping adjustment panel.

### `hideCropPanel()`
Hides the cropping adjustment panel.

### `triggerCopyOverlay()`
Activates the quick-copy overlay panel (shortcut: C).

### `triggerMoveOverlay()`
Activates the quick-move overlay panel (shortcut: M).

### `showSettings()`
Opens the application settings dialog.

### `toggleImageInfoOverlay()`
Toggles the display of image information, such as EXIF data (shortcut: I).

### `toggleFullscreenInfoBar()`
Toggles the visibility of the information bar in fullscreen mode.

### `toggleRenameOverlay(const char *defaultName)`
Toggles the rename overlay, optionally pre-filling with a default name.
```

--------------------------------

### Core: Image Manipulation and File Operations

Source: https://context7.com/easymodo/qimgv/llms.txt

Lists various private slot actions available in the `Core` component, representing the full set of image editing, file management, and view control operations. These are typically connected via `ActionManager` signals.

```cpp
// --- Selected core slot actions (connected via ActionManager signals) ---
// These are private slots but represent the full action set:
//   nextImage()            prevImage()           jumpToFirst()   jumpToLast()
//   rotateLeft()           rotateRight()
//   flipH()                flipV()
//   crop(QRect)            cropAndSave(QRect)
//   resize(QSize)
//   saveCurrentFile()      saveCurrentFileAs(QString)
//   moveToTrash()          removePermanent()
//   copyCurrentFile(QString destDir)
//   moveCurrentFile(QString destDir)
//   toggleSlideshow()      toggleShuffle()
//   toggleFolderView()     enableFolderView()    enableDocumentView()
//   reloadImage()
//   copyFileClipboard()    copyPathClipboard()
//   openFromClipboard()
//   runScript(const QString &scriptName)
//   setWallpaper()
//   sortByName()           sortByTime()          sortBySize()
//   print()
```

--------------------------------

### Set HiDPI Scale Factor on Linux/MacOS

Source: https://github.com/easymodo/qimgv/blob/master/README.md

Override the scale factor for qimgv on HiDPI displays. This command sets the scale factor to 1.5. Values less than 1.0 are not supported.

```bash
QT_SCALE_FACTOR="1.5" qimgv /path/to/image.png
```

--------------------------------

### DirectoryManager: Sorting and File Support Check

Source: https://context7.com/easymodo/qimgv/llms.txt

Allows changing the sorting mode of the directory manager in-place and checking if a given file extension is supported. The `setSortingMode` function re-sorts the existing index.

```cpp
// --- Sorting ---
dm.setSortingMode(SORT_NAME);   // re-sorts in place
dm.sortingMode();               // returns current SortingMode

// --- Format support check ---
bool supported = dm.isSupportedFile("/tmp/photo.avif");
```

--------------------------------

### Displaying Status Messages with MW

Source: https://context7.com/easymodo/qimgv/llms.txt

Show temporary on-screen messages to the user. Messages can include success, warning, or error states, and can optionally have a duration.

```cpp
mw->showMessage("Copied to /home/user/backup");
```

```cpp
mw->showMessage("Processing…", 2000);      // with duration in ms
```

```cpp
mw->showMessageSuccess("Saved");
```

```cpp
mw->showWarning("Read-only filesystem");
```

```cpp
mw->showError("File not found");
```

--------------------------------

### Fit Modes

Source: https://context7.com/easymodo/qimgv/llms.txt

Control how the image is scaled to fit the viewer window.

```APIDOC
## Fit Modes

### `fitWindow()`
Scales the image to fit within the window boundaries, maintaining aspect ratio (letterboxing).

### `fitWidth()`
Scales the image to fit the window's width, maintaining aspect ratio.

### `fitOriginal()`
Displays the image at its original 1:1 pixel ratio.

### `fitWindowStretch()`
Stretches the image to fill the window completely, potentially distorting aspect ratio.

### `switchFitMode()`
Cycles through the available fit modes.
```

--------------------------------

### Status Messages

Source: https://context7.com/easymodo/qimgv/llms.txt

Display temporary on-screen messages to the user.

```APIDOC
## Status Messages

### `showMessage(const char *message)`
Displays a general status message.

### `showMessage(const char *message, int durationMs)`
Displays a status message for a specified duration in milliseconds.

### `showMessageSuccess(const char *message)`
Displays a success-themed status message.

### `showWarning(const char *message)`
Displays a warning-themed status message.

### `showError(const char *message)`
Displays an error-themed status message.
```

--------------------------------

### Scaling Filter

Source: https://context7.com/easymodo/qimgv/llms.txt

Methods to control the image scaling algorithm used for resizing and zooming.

```APIDOC
## Scaling Filter

### `setFilterNearest()`
Sets the scaling filter to Nearest Neighbor.

### `setFilterBilinear()`
Sets the scaling filter to Bilinear interpolation.

### `setFilter(int filter)`
Sets the scaling filter to a specific enumerated value (e.g., `QI_FILTER_CV_CUBIC`).

### `toggleScalingFilter()`
Cycles through the available scaling filter modes.
```

--------------------------------

### Removing Scripts with ScriptManager

Source: https://context7.com/easymodo/qimgv/llms.txt

Demonstrates how to remove a previously registered script from ScriptManager. This action is persisted when `saveScripts()` is called.

```cpp
// --- Remove a script ---
sm->removeScript("Convert to PDF");
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.