diff --git a/3d_mouse.md b/3d_mouse.md new file mode 100644 index 0000000..14dfe63 --- /dev/null +++ b/3d_mouse.md @@ -0,0 +1,188 @@ +# 3D mouse (SpaceMouse) + +A 3Dconnexion 3D mouse — SpaceMouse, SpacePilot, SpaceNavigator and the like — +can pan and zoom QElectroTech's folios and the element editor with one hand, +leaving the other on the ordinary mouse for drawing. Its buttons can run any +QElectroTech command that has a keyboard shortcut. + +Support was asked for, and is still discussed, in +[discussion #599](https://github.com/qelectrotech/qelectrotech-source-mirror/discussions/599). +Reports from real devices are welcome there: see §6. + +--- + +## 1. What it does + +| On the device | In QElectroTech | +|---|---| +| Slide the cap left/right, forward/back | pans the view | +| Push/pull the cap (default), or twist it (setting) | zooms | +| Tilt | nothing | +| A button | the command you bound to it, if any | + +It acts on whichever window is in front: the current folio of the schematic +editor, or the element editor's drawing. Zoom stops at the same limits as the +mouse wheel. + +Nothing happens on a button press until you bind that button (§3). There is no +default binding. + +--- + +## 2. Which builds have it + +3D mouse support is a compile-time option, off by default. How the device is +read depends on the build: + +| Build | Reads the device through | Needs | +|---|---|---| +| Windows package | USB directly (hidapi) | nothing extra; no 3Dconnexion driver is required | +| macOS package | 3DxWare when it is installed and running, otherwise USB directly | nothing extra | +| Flatpak | USB directly (hidapi) | read access to `/dev/hidraw*`, see §5 | +| Snap | spacenavd | the `spacenavd` daemon running | +| Linux distribution packages, own builds | whatever the packager chose | see §7 | + +If the **Souris 3D** page is missing from the preferences (§3), your build does +not have 3D mouse support. + +On macOS, while QElectroTech is the front application, 3DxWare's own actions +are switched off in it, so the view does not move twice. + +--- + +## 3. Settings + +*Edit → Preferences*, page **Souris 3D** (*3D mouse*). + +### Mouvement (*Motion*) + +| Setting | Range | Default | Does | +|---|---|---|---| +| **Vitesse de déplacement** (*Pan speed*) | 10–400 % | 100 % | how fast the view pans | +| **Vitesse du zoom** (*Zoom speed*) | 10–400 % | 100 % | how fast it zooms | +| **Zoomer en** (*Zoom by*) | *Pousser / tirer le capuchon* (push/pull the cap), *Tourner le capuchon* (twist the cap) | push/pull | which movement zooms | +| **Zone morte** (*Dead zone*) | 0–200 | 0 | movements smaller than this are ignored; raise it if the view drifts while you are not touching the device | +| **Inverser le déplacement horizontal** | on/off | off | reverses left/right | +| **Inverser le déplacement vertical** | on/off | off | reverses forward/back | +| **Inverser le zoom** | on/off | off | reverses zoom in/out | + +The speed on screen does not depend on how often the driver sends updates, so +the same setting feels the same on every system. An equal push and pull cancel +out exactly. + +### Boutons (*Buttons*) + +A table of button number → command: + +1. Click **Ajouter une association** (*Add a binding*). +2. Set **N° bouton** to the button's number. +3. Pick the command under **Action**. The list holds every command that has a + shortcut in QElectroTech, grouped by editor. +4. Click **OK** to save. + +The number a button sends depends on the device and on how it is read. The +device's documentation may give it; otherwise try 0, 1, 2… in turn. The button +at the end of a row removes the binding. + +--- + +## 4. Where the settings are kept + +In QElectroTech's own settings, not in any project: under `spacemouse/motion/` +for the motion settings and `spacemouse/buttons/` for the bindings. They apply +to every project, and to both editors. + +--- + +## 5. When nothing happens + +| Symptom | Check | +|---|---| +| No **Souris 3D** page in the preferences | the build has no 3D mouse support: §2 | +| Snap: the device does nothing | `spacenavd` is installed and running (`systemctl status spacenavd`) | +| Flatpak: the device does nothing | your user can read the device: `ls -l /dev/hidraw*`. On many distributions these nodes are readable by root only, and a udev rule is needed (below) | +| The view drifts on its own | raise **Zone morte** | +| It moves the wrong way | the **Inverser…** settings | +| A button does nothing | it is not bound yet, or bound to the wrong number: §3 | + +A udev rule giving the logged-in user access to 3Dconnexion devices, for the +Flatpak or any build using the USB backend on Linux. Save it as +`/etc/udev/rules.d/70-3dmouse.rules`: + +``` +KERNEL=="hidraw*", ATTRS{idVendor}=="256f", TAG+="uaccess" +KERNEL=="hidraw*", ATTRS{idVendor}=="046d", TAG+="uaccess" +``` + +`256f` is 3Dconnexion; `046d` is Logitech, which sold the older models. Then +run `sudo udevadm control --reload && sudo udevadm trigger` and replug the +device. QElectroTech looks for a device every three seconds, so it does not +need restarting, and it reconnects on its own after the device is unplugged. + +--- + +## 6. Helping with a recording + +The USB backend decodes each device model's raw reports itself. A short +recording from a real device lets that model be tested. The script +`misc/spacemouse-capture.py` in the source tree guides you through a few +movements, saves one `.json` file, and sends nothing anywhere. It runs on +Linux, macOS and Windows with only Python 3. + +```bash +curl -LO https://raw.githubusercontent.com/qelectrotech/qelectrotech-source-mirror/master/misc/spacemouse-capture.py +python3 spacemouse-capture.py --help # step-by-step instructions for your system +python3 spacemouse-capture.py --seconds 3 # record, three times the default time per step +``` + +On Linux, run it with `sudo`, for the reason in §5. Attach the file to +[discussion #599](https://github.com/qelectrotech/qelectrotech-source-mirror/discussions/599). +One recording per device model is enough. + +--- + +## 7. Building it in + +Two CMake options: + +| Option | Values | Default | +|---|---|---| +| `QET_ENABLE_SPACEMOUSE` | `ON`, `OFF` | `OFF` | +| `QET_SPACEMOUSE_BACKEND` | `auto`, `spnav`, `hid` | `auto` | + +| Backend | Reads through | Library (pkg-config) | +|---|---|---| +| `spnav` | the spacenavd daemon, Linux | `libspnav-dev` (`spnav`) | +| `hid` | USB directly, any system | `libhidapi-dev` on Linux (`hidapi-hidraw`), MSYS2 `mingw-w64-ucrt-x86_64-hidapi`, Homebrew `hidapi` | +| `auto` | spnav on Linux when libspnav is found, hid otherwise | | + +On macOS the 3DxWare backend is always added as well. It loads 3DxWare's +library at run time and needs nothing to build. + +```bash +cmake -B build -DQET_ENABLE_SPACEMOUSE=ON -DQET_SPACEMOUSE_BACKEND=hid +``` + +If the chosen backend's library is not found, CMake prints a warning and builds +**without** 3D mouse support rather than failing. Check the configure output +for a line like `QET_ENABLE_SPACEMOUSE ON (backend: hidapi 0.14.0)`. + +--- + +## 8. Limitations + +| Limitation | Detail | +|---|---| +| Pan and zoom only | tilting the cap does nothing; there is no rotation of the folio | +| Button numbers are raw | there is no "press the button to bind it"; find the number by trying | +| 3DxWare app events | on macOS, only raw button presses are read, not the named actions newer 3DxWare versions send | +| Hardware coverage | tested on the devices reported in discussion #599; other models may need a recording (§6) | + +--- + +## See also + +- **[Preferences reference](preferences)** — the other preference pages +- **[Finding your place on a folio](navigating_folios)** — going to a cell, keeping the headers in sight +- **[Keyboard-only control](keyboard_control)** — the commands a button can be bound to +- **[Building from Source](building)** — the full build instructions diff --git a/_Sidebar.md b/_Sidebar.md index 99bdddb..f51565c 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -38,7 +38,11 @@ **[Mouse modifiers](mouse_modifiers)** — what Shift, Ctrl and Alt change while you drag -**[Aligning items](aligning_items)** — snap symbols back to the grid *(pending)* +**[3D mouse](3d_mouse)** — SpaceMouse pan, zoom and buttons + +**[Aligning items](aligning_items)** — snap symbols back to the grid + +**[Pictures on a folio](pictures)** — labels, crop, transparency, what they cost in the file **[Grouping items](grouping_items)** — select, move and copy several items as one *(pending)* diff --git a/aligning_items.md b/aligning_items.md index d296862..3a72258 100644 --- a/aligning_items.md +++ b/aligning_items.md @@ -34,12 +34,6 @@ translations are updated, with an English gloss in italics. ## Snap to grid -> **Status: pending.** This section describes -> [PR #1073](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1073), -> not yet merged. Nothing here works until that lands — check the PR before -> trying any of this against your own build. This section will drop this -> notice once it does. - ### Using it 1. Select the items to fix. **Ctrl+A** selects everything on the folio, diff --git a/conductors.md b/conductors.md index d789efe..06adf19 100644 --- a/conductors.md +++ b/conductors.md @@ -203,13 +203,33 @@ automatically. The drawing looks fine; the hand-routing is lost. ## 7. Colouring quickly -Select exactly one conductor and press **F2** to open a colour picker for it. -The shortcut does nothing with several conductors selected, or none. +The **Couleur de conducteur** (*Conductor colour*) swatch on the **Schéma** +toolbar colours every selected conductor in one click: -> A toolbar colour button that applies to every selected conductor at once, and -> sets the colour of the next conductor drawn, is proposed in -> [PR #929](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/929). -> Until it merges, F2 one at a time — or Search & Replace for bulk changes. +1. Select the conductors: one, several, or **Ctrl+A** for the whole folio. +2. Open the swatch and pick a colour. + +The menu lists the colours electricians name — Noir, Marron, Gris, Bleu, +Vert, Rouge, Orange, Violet, Blanc (*black, brown, grey, blue, green, red, +orange, violet, white*) — then the custom colours you picked this session under +*Récemment utilisées*, then **Autre couleur…** for the full colour dialog. + +What it does: + +- **Whole wires, not segments.** A wire split into several segments by + junctions is recoloured along its whole electrical potential, as the + properties dialog does. +- **One undo step** for the whole selection. +- **The next wire too.** The picked colour becomes the colour of the next + conductor you draw. With nothing selected, picking a colour only does that. +- **Nothing is saved as a setting.** The colour lives on the conductors it was + applied to; the recent list is forgotten when QET closes. + +The swatch is greyed out when no folio is open or the project is read-only. + +**F2** still opens the colour picker for exactly one selected conductor, and +does nothing with several selected or none. For bulk changes across folios by +some other criterion, use **[Search & Replace](search_and_replace)**. There are **no named conductor presets**. A project has a single default set of conductor properties, not a library of named ones; the request for that is diff --git a/data_files/elements_child_description.md b/data_files/elements_child_description.md index 78b3326..6f85689 100644 --- a/data_files/elements_child_description.md +++ b/data_files/elements_child_description.md @@ -31,3 +31,9 @@ Connections: Order matters: parts are drawn in document order, so a later sibling paints over an earlier one. + +Every part may carry a `uuid` attribute, its permanent id within the symbol. +Terminals and dynamic texts have long had one. Since September 2026 the element +editor also writes one on every shape and fixed text when it saves, and paste +in the editor gives the copies new ids. Symbols without them load normally, +and older versions of QElectroTech ignore the attribute on shapes and texts. diff --git a/data_files/project_diagram_child_images.md b/data_files/project_diagram_child_images.md index 3d0013d..ffc4f1c 100644 --- a/data_files/project_diagram_child_images.md +++ b/data_files/project_diagram_child_images.md @@ -7,12 +7,22 @@ attribute : none ## child elements * ``, with attributes: + * uuid -- the picture's permanent id * x, y, z -- position and stacking order * size -- scale factor * rotation -- degrees - * is_movable -- `true` / `false` + * is_movable -- `1` / `0` + * label -- caption drawn under the picture; written only when set -The image data itself is stored base64-encoded as the text node of the -`` element, so a project file stays self-contained. +The image data itself is stored as PNG, base64-encoded, as the first text node +of the `` element, so a project file stays self-contained. + +Optional children, each written only when it carries something: + * `` -- rotation, skewX, skewY, scaleX, scaleY, pivotX, pivotY + * `` -- one `` per keyed colour + * `` -- x, y, w, h of the kept region + * `` -- the untouched original, PNG base64, when cropped or keyed + +See **[Pictures on a folio](pictures)** for what each does. Written only when the folio has at least one image, by `Diagram::toXml()`. diff --git a/data_files/project_diagram_child_inputs.md b/data_files/project_diagram_child_inputs.md index 4901541..578c8a4 100644 --- a/data_files/project_diagram_child_inputs.md +++ b/data_files/project_diagram_child_inputs.md @@ -8,6 +8,7 @@ attribute : none ## child elements * ``, with attributes: + * uuid -- the text's permanent id * x, y -- position * text -- the string * font -- serialised `QFont` diff --git a/data_files/project_diagram_child_shapes.md b/data_files/project_diagram_child_shapes.md index 312d77f..2160631 100644 --- a/data_files/project_diagram_child_shapes.md +++ b/data_files/project_diagram_child_shapes.md @@ -8,12 +8,13 @@ attribute : none ## child elements * ``, with attributes: + * uuid -- the shape's permanent id * type -- `Line`, `Rectangle`, `Ellipse` or `Polygon` * x1, y1, x2, y2 -- defining points * rx, ry -- corner radii, for rectangles * closed -- for polygons * z -- stacking order - * is_movable -- `true` / `false` + * is_movable -- `1` / `0` These are diagram shapes and are **not** the same as the element drawing primitives documented under [description](elements_child_description), even diff --git a/element_linking.md b/element_linking.md index 4dcab9e..8d6dde5 100644 --- a/element_linking.md +++ b/element_linking.md @@ -92,9 +92,11 @@ A master can describe the contacts it actually offers, typed and labelled: coil - + + + @@ -109,13 +111,46 @@ A master can describe the contacts it actually offers, typed and labelled: | `type` | `NO`, `NC`, `SW`, `Other` | Contact state. Defaults to `NO`. | | `subtype` | `simple`, `power`, `delayOn`, `delayOff`, `delayOnOff`, `plc` | Contact kind. Defaults to `simple`. | | `contactCount` | integer | How many contacts this group provides. Defaults to `1`. | -| `terminalCount` | integer | Terminals per contact. Defaults to `1`. | +| `terminalCount` | integer | Terminals in the whole group, shared out over its contacts in order. Defaults to `1`. | | `