wfassoc/example/qwfassoc/README.md

# qwfassoc

A Qt Widgets based GUI front-end for the [wfassoc](../../wfassoc) library.

`qwfassoc` exposes the same install / uninstall / file-association operations
as the `wfassoc-exec` command line tool, but in a small tabbed dialog aimed at
end users rather than scripts.

## Layout

```
qwfassoc/
├── CMakeLists.txt             CMake build script
├── README.md                  This file
├── cmake/
│   ├── Findwfassoc.cmake      Verbatim copy of wfassoc's Find module
│   └── README.md              Provenance notes for the copy
├── i18n/
│   └── qwfassoc_zh_CN.ts      Empty placeholder translation file
└── src/
    ├── main.cpp               Entry point, CLI parsing, translator loading
    ├── main_window.h/.cpp     Main configuration dialog
    ├── main_window.ui         Qt Designer description of the dialog
    ├── manifest.h/.cpp        TOML manifest loader (toml11) and schema builder
    └── icon_utils.h/.cpp      wfassocpp::HICON -> QPixmap conversion helper
```

## Requirements

* **CMake** 3.20 or newer.
* A C++17 compiler.
* **Qt 6** (6.3 or newer is recommended for `qt6_add_translations`). The
  `Widgets` and `LinguistTools` components are required:
  `find_package(Qt6 COMPONENTS Widgets LinguistTools)`.
* **toml11**. `find_package(toml11)` is used.
* **wfassoc**. `find_package(wfassoc)` is used, which requires `wfassoc_ROOT`
  to point at an installed wfassoc tree (see
  [`cmake/Findwfassoc.cmake`](cmake/Findwfassoc.cmake) for the expected
  directory layout).

## Building

```bat
cmake -S . -B build -DCMAKE_PREFIX_PATH=C:\Qt\6.x.x\msvc2022_64 ^
    -Dwfassoc_ROOT=C:\path\to\wfassoc\install ^
    -Dtoml11_DIR=C:\path\to\toml11\share\toml11\cmake
cmake --build build --config Release
```

The resulting executable is `build/Release/qwfassoc.exe` (or a similar path
depending on the generator).

## Running

`qwfassoc` requires two command line arguments:

| Short | Long         | Meaning                                                       |
| ----- | ------------ | ------------------------------------------------------------- |
| `-c`  | `--manifest` | Path to the application manifest TOML file (see [`example/manifest/ppic.toml`](../manifest/ppic.toml)). |
| `-f`  | `--for`      | Target scope: `user` or `system`.                             |

Example:

```bat
qwfassoc -c C:\path\to\ppic.toml -f user
```

When `-f user` is used the "All Users" column of the file-association table is
read-only (cells render greyed out and clicks are ignored). Use `-f system`
(with appropriate administrator privileges) to make changes that affect all
users.

## Internationalization

The user-facing strings shipped in the source code and the `.ui` file are
written in English. Every translatable string is wrapped in `tr()` (in code)
or marked as a regular `<string>` (in the `.ui` file, which `uic` then wraps
in `QCoreApplication::translate`).

The CMake build wires up the standard Qt translation pipeline via
`qt6_add_translations()`:

* the listed `.ts` files under `i18n/` are kept in sync with the source by
  `lupdate`,
* `lrelease` compiles them into `.qm` files which are embedded under the
  `:/i18n/` resource prefix,
* `installTranslators()` in `src/main.cpp` loads the `.qm` file matching the
  current locale at startup.

The repository ships `i18n/qwfassoc_zh_CN.ts` as an **empty placeholder**.
Translators are expected to fill it in (or add new language files and list
them in `CMakeLists.txt`). No actual translation work is performed by the
build on its own.

## UI Overview

The dialog is a fixed 480x600 `QDialog` with two tabs.

### Applications tab

Lets the user install or uninstall the program described by the manifest in
the scope selected by `--for`. The currently-active action button is enabled
based on whether the program is already registered; the other one is disabled.

### File associations tab

Lists every extension declared in the manifest. Each row shows:

* the dotted extension (`.jpg`) with a hybrid-view icon,
* the display name of the handler currently registered for the current user,
* the display name of the handler currently registered for all users.

Clicking a cell in the user or all-users column toggles the cell state between
the program-provided handler (link) and no handler (unlink). The "+ " buttons
above each column progressively select more: the first click only fills blank
cells, the next click overrides any cell pointing at another handler.

Changes are buffered in memory and only written to the registry when **OK** or
**Apply** is pressed. **OK** writes and closes the dialog; **Apply** writes
and refreshes the table; **Cancel** discards the pending changes and closes
the dialog. The **Apply** button is disabled when no changes are pending.

If the program is not installed in the active scope, the whole file
associations tab is disabled.

## Notes and Limitations

* The "self" detection in the file-association table is based on comparing the
  display name returned by wfassoc with the display name this program would
  use. Two programs sharing the exact same display name could therefore be
  confused.
* The dialog uses `Qt::ItemIsSelectable` (without `Qt::ItemIsEnabled`) to
  render disabled system-column cells in user mode; their text is still shown
  but they cannot be clicked.
* All errors originating from wfassoc are surfaced through `QMessageBox`
  dialogs; fatal errors during startup cause the process to exit with a
  non-zero status code.