SELECTION — SELECTED DEVICE
Context
The Selection page carries the collection's device tree and holds the one device
that the rest of the application acts on — the scope of a search, of the Devices
page, of Create and of Statistics. In K2 the same panel is named Filters: its
objects are Filters_*, its code is qt_widgets/mainwindow_tab_filters.cpp
(header: "methods for the SELECTION panel") and its user page is
Selection.md. Searching K2 for "Selection" does not find it.
Nothing had ever written down which device is selected, how the selection changes, or how it is shown. Three consequences were found on 2026-08-30, all of them silent:
- Restoring a search from history restored every form criterion except the device the search had been run against, so the restored search ran against whatever happened to be selected and produced different results with no error and no visible sign.
- A card's context menu acted on the card that was right-clicked while the selection — and therefore the highlight — stayed on a different card.
- With a long device list scrolled past the highlighted card, nothing on screen said which device was selected.
This page is the only source of requirements for those behaviours.
Reading the requirement IDs. Each requirement has a permanent ID. IDs are never renumbered or reused; a retired requirement is marked
[Removed], not deleted. Status is one of[Implemented] / [Planned] / [Backlog] / [Removed].
Scope at a glance
In scope: which device is selected; the ways the selection changes — card
activation, the card context menu, and restoring a search from history; the
display of the current selection at the top of the Selection page; and the
display of each history entry's device scope; and the icon size of the
Selection cards together with the alignment that depends on it (SEL-F7,
SEL-C8), added 2026-09-12; and the content of the Selection card's second
line (SEL-F8, SEL-C10).
Pointer, not a requirement: selecting a Catalog card while the Explore page is open also opens that catalog in Explore. That effect is governed by EXP-F27 and EXP-C21 in SpecExplore.md (approved 2026-10-13), not by any row here; it does not change which device is selected or how (SEL-F1–SEL-F6, SEL-C7).
Pointer, not a requirement: the surface of the SEL-F5 reminder row — transparent when idle, tinted on hover — is governed by THM-F10 and THM-C13 in SpecTheme.md, not by any row here; SEL-F5, SEL-F6 and SEL-C7 are unchanged by it.
Out of scope (non-goals): the device tree's collapse and expand state and its
header controls; the ordering and filtering of the device list; the Devices page
and the device editor; connected-drives mode and its directory picker; every
search criterion other than the device scope — those belong to the search form
and, for the text and exclude term lists, to SpecSearchList.md. None of them is
governed by this spec and this spec does not authorise changing any of them.
Applies to: K3 (qt_quick) only. K2 is in maintenance mode and already
satisfies SEL-F1 and a labelled variant of SEL-F5; see SEL-C6.
Operational requirements — why / for whom
Goals in real use, independent of how they are built.
| ID | Requirement | Status |
|---|---|---|
| SEL-O1 | A user working in a collection with many devices can see which device the application is acting on without scrolling the device list to find the highlighted card. | [Planned] |
| SEL-O2 | A user who re-runs a search from history gets the results the original run produced, because the device it was run against comes back with it. | [Planned] |
| SEL-O3 | A user reading the search history can tell which device each past search covered before choosing one. | [Planned] |
| SEL-O4 | A user acting on a device through its context menu has the action applied to the device pointed at, not to a different one. | [Planned] |
Functional requirements — what the system does
Observable behaviour that can be triggered and watched.
| ID | Requirement | Status |
|---|---|---|
| SEL-F1 | Restoring a search from history restores the device selection the search was run against, in addition to every form criterion. If no device was stored, or the stored device no longer exists in the collection, the selection becomes All. | [Planned] |
| SEL-F2 | Each search history entry displays the device its search was run against, so the scope is visible before the entry is chosen. A search run against all devices displays All. | [Planned] |
| SEL-F3 | Activating Search or Explore from a Selection card's context menu selects that card's device before performing the action, so the highlighted card and the action always agree. The Search entry is always shown, whichever page is open; when Search is already open it moves to it, keeping Results (amended 2026-10-03 at the user's request: it was hidden while Search or Results was the open page). | [Planned] |
| SEL-F4 | Edit, Update and Open folder MUST NOT change the selection. They act on the right-clicked device while the highlight stays where it was. This is a deliberate, informed decision taken on 2026-08-30: the resulting mismatch — the same one SEL-F3 exists to remove for Search and Explore — was put to the maintainer explicitly for these three items and accepted. It is also a divergence from K2, which selects the device when the context menu is opened (qt_widgets/mainwindow_tab_filters.cpp:176-183 calls on_Filters_treeView_Devices_clicked() before building the menu), so in K2 every item selects and merely dismissing the menu selects too. K3 selects per item. This MUST NOT be "corrected" to match SEL-F3, and MUST NOT be "corrected" back to K2's select-on-menu-open. | [Planned] |
| SEL-F5 | The Selection page shows the currently selected device at the very top, immediately before the filter and expand row, rendered as a device card: the type icon and the device name with the per-type font rules. No label, heading or title precedes it. When no device is selected the row shows All with the folder icon — the same icon the All entry already uses elsewhere in K3. The row is always present, so the layout never shifts as the selection changes. Deliberate divergence from K2, which labels three separate rows Virtual / Storage / Catalog and fills the two that do not apply with All. | [Planned] |
| SEL-F6 | Clicking the SEL-F5 reminder scrolls the device list so the selected card is visible. It is a navigation affordance only — see SEL-C7. | [Planned] |
| SEL-F7 | The Selection cards draw their device icon at the size set by the bigger icon size preference (THM-F7, SpecTheme.md), the same two-state rule the Devices cards follow: the medium token when the option is set, the small-medium token when it is not. One setting therefore drives both pages. The user requested this on 2026-09-12. With the option off the Selection icon becomes larger than it was — small-medium (22) where it was small (16): that growth is part of the request, not a side effect, because a third size reserved for this page would defeat a shared preference and would break DVP-C20, which requires the two cards to match. | [Planned] |
| SEL-F8 | The second line of a Storage or Virtual Selection card states the file count, the total file size and the used space — and not the total space, which is removed. At the default card size the previous four figures wrapped onto a second line often enough to be the normal case, and the total was the value the user chose to drop on 2026-09-12. A Catalog card's second line is unchanged. | [Planned] |
Constructional requirements — how it is built / limits / MUST-NOTs
Boundaries and implementation constraints, not user-visible behaviour.
| ID | Requirement | Status |
|---|---|---|
| SEL-C1 | The SEL-F5 reminder and the device cards render their icon and name from one shared QML component. The icon rule (drive-multidisk for Virtual, drive-harddisk for Storage, media-optical-blu-ray for an active Catalog and media-optical otherwise), the per-type font.weight and font.italic, and the per-type opacity (0.60 Virtual / 0.78 Storage / 1.0 Catalog) MUST NOT be duplicated in a second file. Two copies would drift apart silently, and the reminder disagreeing with the card it mirrors is the exact failure this row prevents. | [Planned] |
| SEL-C2 | SEL-F1 MUST NOT change core/. core/ is already complete and is not at fault. Search::loadSearchHistoryCriteria reads selected_device_ID_list at result column index 44 and assigns it to selectedDeviceIDList at core/search.cpp:903-911; AppManager::selectDeviceById() already applies a selection and persists Selection/SelectedDeviceID. The defect is downstream: the K3 adapter's properties() map (qt_quick/adapters/search.h:54) omits selectedDeviceIDList, so AppManager::restoreSearchHistory() returns a map without it and PageSearchForm.applyHistoryCriteria() has nothing to apply. The change is confined to those three qt_quick/ points. (Recorded because the fault was twice attributed to core/ before being traced; a future reader should not repeat that.) | [Planned] |
| SEL-C3 | Only the first ID of the stored list is applied, matching K2 (qt_widgets/mainwindow_tab_search_ui.cpp:674), because the Selection page holds a single device. The stored comma-separated format, the search.selected_device_ID_list column and the database schema MUST NOT change. | [Planned] |
| SEL-C4 | These rows MUST add zero new translatable strings. SEL-F5 carries no label by definition and reuses the existing All; SEL-F2 renders the device name itself, or the existing All, as one more bare fragment of the existing history summary line. The K2 column header Selected Device ID List labels a raw-ID debug column and MUST NOT be reused. | [Planned] |
| SEL-C5 | The device name of SEL-F2 MUST be obtained through an existing device accessor. It MUST NOT be obtained by adding a device join, or any further raw SQL, to AppManager::getSearchHistory() (qt_quick/appmanager.cpp:1357), whose existing raw QSqlQuery is already a departure from the UI/core boundary. That departure is recorded in SpecBacklogNotes.md as reported and unruled; it is neither authorised nor to be deepened here. | [Planned] |
| SEL-C6 | K2 MUST NOT change. K2 already satisfies SEL-F1 (qt_widgets/mainwindow_tab_search_ui.cpp:651-693, including its "device still exists, else All" guard) and shows a labelled variant of SEL-F5 (displaySelectedDeviceName(), qt_widgets/mainwindow_tab_filters.cpp:449-470). K2's labelled three-row display, its select-on-menu-open behaviour and its raw-ID history column MUST NOT be reported as drift against these rows. | [Planned] |
| SEL-C7 | The SEL-F6 click MUST NOT change or clear the selection. Clearing to All was considered and rejected on 2026-08-30: the reminder sits directly above the filter field, so a misclick would silently widen the scope of the next search with no error and no visible cause — the same class of silent wrong answer that SEL-F1 exists to remove. The reminder scrolls the list and does nothing else. | [Planned] |
| SEL-C8 | The Selection card's second line is indented to line up with the name, not with the icon — its left margin is the icon size plus the small spacing. That margin MUST follow SEL-F7's themed size rather than the hard-coded small token it uses today, otherwise the description stops aligning with the name as soon as the icon size changes. This is the one edit to the Selection page authorised by the 2026-09-12 request; DVP-C21's prohibition on changing this page for the Devices work is unaffected and still stands for everything else. | [Planned] |
| SEL-C9 | SEL-F7 and SEL-C8 add no new user-visible string, and MUST NOT change what the Selection card says, which device is selected, or any behaviour of SEL-F1 to SEL-F6. They change two sizes and one margin. | [Planned] |
| SEL-C10 | The file-count text of the Selection card MUST be translatable. It is built today from a raw, untranslated literal (qt_quick/adapters/devicelistmodel.cpp:81), so the word ships in English in all 30 languages — a defect, not a wording choice. The fix MUST reuse the existing source string files, the one K3 already uses on the Devices card and the Backup form and which is already translated, with the count substituted separately. A combined %1 files source string MUST NOT be introduced: it would be new wording, costing 30 translation slots for text that already exists. | [Planned] |
| SEL-C11 | The space figure left by SEL-F8 stays unlabelled, as the other figures on that line are. Labelling it was considered and not authorised: labels cost the width SEL-F8 exists to recover. This is recorded because a single bare figure is less self-explanatory than the pair it replaces — see Open, not authorised below. The Devices card's labelled figures (DVP-F16) are not the model here: DVP-C20 names the second line's information as a permitted difference between the two cards, so the two lines differing is by design. | [Planned] |
Open, not authorised
| Item | Detail |
|---|---|
The bare space figure of SEL-F8 | With two figures a reader could infer used of total; with one, used and free are indistinguishable without a label. Removing the total was what the user asked for, and labelling the survivor would spend the width the removal recovered, so neither relabelling nor restoring the total is authorised. If the ambiguity proves to matter in use, the options — a short lowercase label reusing the existing used, or a tooltip — need the user's decision first. |
Manual test charter
For each row: set up the stated condition, run the operation, confirm the result.
- SEL-F1 — Select a Catalog, run a search, then select a different device. Reopen the history and click that entry: the first Catalog is selected again and re-running the search gives the original results. Repeat after deleting the stored device from the collection: the selection falls back to All, the form still restores, and nothing errors.
- SEL-F1 / SEL-C3 — Restore a history entry saved with no device scope. The selection becomes All rather than staying on the previous device.
- SEL-F2 — Open the history list. Every entry names the device its search covered; an all-devices search reads
All. Switch the interface to French: the device name stays as stored andAllis translated, confirming no new string was created. - SEL-F3 — Right-click a card other than the selected one and choose Search. The highlight moves to that card before the Search page opens, and running the search covers that device. Repeat with Explore on a Catalog.
- SEL-F4 — Right-click a card other than the selected one and choose Edit: the editor opens on that device and the highlight stays on the previously selected card. Repeat for Update and for Open folder: each acts on the right-clicked device while the highlight does not move. All three are intended and MUST NOT be reported as defects.
- SEL-F4 (K2 divergence) — In K2, right-click a device in the Selection panel and press Escape without choosing anything: the selection has moved to that device. In K3, do the same: the selection has not moved. Both are correct for their version.
- SEL-F5 — With a long device list scrolled well past the highlighted card, the top of the Selection page shows the selected device as a card, with no label or heading above it, and it sits before the filter and expand row. Select a Virtual, then a Storage, then an active Catalog, then an inactive one: the reminder's icon, boldness, italics and dimming match that device's own card exactly in each case.
- SEL-F5 (All) — Reset the selection so no device is selected. The reminder shows
Allwith thefoldericon, and the row keeps the same height, so nothing below it moves. - SEL-C1 — Change one styling value in the shared component and confirm the reminder and the cards both follow it. Confirm by inspection that the icon rule, the font rules and the opacity values exist in exactly one file.
- SEL-F6 / SEL-C7 — Scroll the device list until the selected card is off screen, then click the reminder: the list scrolls to the selected card. Confirm the selection is unchanged — same device highlighted, same device name in the reminder — and that no search scope has widened. Click the reminder repeatedly: nothing changes but the scroll position.
- SEL-F7 — Tick Use bigger icon size in Settings: the Selection card icons grow, and so do the Devices card icons, from one setting. Untick it: both shrink to the small-medium size. Confirm the Selection icon at the off state is the same size as the Devices card's at the off state.
- SEL-C8 — At each icon size, confirm the Selection card's second line starts exactly under the first character of the device name, not under the icon and not offset from it.
- SEL-C9 — Confirm the card still names the same device, that clicking it still selects, and that the
SEL-F5reminder and the context menu are unchanged. - SEL-F8 — At the default card size, look at a Storage card and a Virtual card with space figures: the line reads the file count, the size and one space figure, and fits on one line. Confirm the total space is gone and that the remaining figure matches the Used space column of the Devices table for the same device.
- SEL-F8 (catalog) — A Catalog card's second line is unchanged.
- SEL-C10 — Switch the interface to French and read a Selection card: the word for files is translated, not the English
files. Runninja translations_lupdate: no new untranslated string appears — the existingfilesis reused, now also in the device-list model context. - SEL-C10 (count) — Confirm the count is still locale-formatted, with the thousands separator of the active language, and that it is not glued to the word.
- SEL-C4 — Run
ninja translations_lupdate. No new untranslated string appears for the Selection page or the search history list. - SEL-F3 / EXP-F27 — With Explore open, right-click another Catalog card and choose Explore: the highlight moves, and the catalog opens in Explore once. Run the
EXP-F27charter inSpecExplore.mdfor the selection-follow behaviour. - SEL-C6 — Open the same collection in K2. Its Selection panel still shows the three labelled Virtual / Storage / Catalog rows and its history table still shows a raw ID column. Both are expected and are not defects of these rows.