138 lines
5.4 KiB
Markdown
138 lines
5.4 KiB
Markdown
# 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.
|