Mirrors/PowerToys
1
0
Fork 0
mirror of https://github.com/microsoft/PowerToys.git synced 2026-09-01 19:51:34 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
7c28d3006a742c91db377e3f8d53854d5edfd165
PowerToys/doc/devdocs
History
takahashi 7c28d3006a [Keyboard Manager] Add "alone" (tap) condition for single-key remaps (dual-key / to_if_alone) (#49136) 
## Summary of the Pull Request

Adds an optional **"alone" condition** to single-key remaps in Keyboard
Manager, bringing
Karabiner-style `to_if_alone` (dual-key / tap-vs-hold) behavior: a key
can perform one action
when **tapped by itself** while still acting as its normal self **when
combined** with other
keys — via the keyboard **or the mouse**.

Example use case: **Right Ctrl → IME On when tapped alone**, **Left Ctrl
→ IME Off when tapped alone**,
while **Right/Left Ctrl + other keys / clicks / wheel** keep working as
normal Ctrl. This is the
Windows equivalent of the popular macOS "left/right ⌘ → 英数/かな" mapping.

## Demo

Muted screen recording with on-screen captions (the physical keys I
press aren't visible; a red ring marks the tray IME indicator あ / A so
the On/Off switching is easy to follow):


https://github.com/user-attachments/assets/0da27a7d-3ae9-4718-94c9-5e79f054ca58

What it shows:
1. Tap **Right Ctrl** alone → IME On (Japanese); tap **Left Ctrl** alone
→ IME Off (English) — directional and idempotent (repeated taps keep the
same state).
2. The same keys still act as **normal modifiers in combination**: Right
Ctrl + H/J/K/L → arrow keys (Vim-style), and Ctrl+A / Ctrl+C / Ctrl+V
behave normally.
3. **Mouse combinations preserved**: a plain click follows a link, while
**Ctrl+Click** opens it in a new tab (via the companion low-level mouse
hook).
4. In Keyboard Manager the whole config is just two "Alone" single-key
remaps plus the Ctrl+H/J/K/L arrows, and the edit dialog shows the new
**Condition → "Alone (tap)"**.

## PR Checklist

- [ ] Closes: #40647
- [ ] Related: #5679 (broader dual-key / `to_if_alone` tracking issue;
#40647 was closed as a duplicate of it)
- [ ] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [x] **Tests:** Added/updated and all pass
- [x] **Localization:** All end-user-facing strings can be localized
- [x] **Dev docs:** Added/updated
- [ ] **New binaries:** Added on the required places — *N/A: no new
binaries/projects are introduced (existing engine, editor UI and test
projects only).*
- [ ] **Documentation updated:** If checked, please file a pull request
on our docs repo and link it here: #xxx

## Detailed Description of the Pull Request / Additional comments

**Engine (C++):**
- New separate remap table `aloneSingleKeyReMap` (parallel to
`singleKeyReMap`) with
  `Add/Clear/GetSingleKeyAloneRemap` (`MappingConfiguration`).
- New handler `HandleSingleKeyAloneRemapEvent` using a **lazy +
release-fire** strategy:
suppress the alone key's key-down; on the first *other* key it flushes
the original key-down
(promoting to a normal combination); on solo release it fires the alone
action. Wired into the
hook dispatch **before** the normal single-key handler; per-key runtime
state lives in `State`.
- **Mouse combinations:** a companion low-level mouse hook
(`WH_MOUSE_LL`) is installed alongside
the keyboard hook **only while alone remaps exist** (reconciled on
settings reload). On a
button-down or wheel event — but **not** mouse-move, which must not
cancel a tap — it promotes
the held alone key(s) to a real modifier via the shared
`PromotePendingAloneKeysToCombination`,
so **Ctrl+Click / Ctrl+Wheel** work while an alone-mapped Ctrl is held.
The mouse event itself is
never suppressed; `State::HasPendingAloneKeys` gives the hook a cheap
early-out.
- Settings JSON: an optional `"condition"` field per single-key remap
(`"always"` default, or
`"alone"`). Fully backward compatible; both **load** and **save** handle
it, so hand-edited or
  UI-created alone remaps round-trip without loss.

**Editor UI (WinUI3):**
- Native wrapper exposes parallel alone add/get/delete over the alone
table (reuses the existing
  `SingleKeyMapping` marshaling struct).
- `SingleKeyRemapCondition` (Always / Alone) flows through the C#
interop/service/model layers.
- A localized **"Condition"** combo box in the add/edit dialog, shown
**only for a single-key
remap whose action is a key/shortcut** (the case the engine supports),
plus a localized
  **"Alone" badge** on such rows in the list.
- **Modifier-conflict validation fix:** two *distinct* modifier sides
(e.g. Left Ctrl and Right
Ctrl) are no longer flagged as a "conflicting modifier". The check now
only fires when one side
is the generic, side-agnostic modifier (Ctrl/Shift/Alt/Win) versus a
specific side — which is
  exactly the left/right pairing this feature targets.
- **Duplicate-entry fix:** the editor's own settings store now rejects
exact-duplicate remaps
(guarding the add path the way the engine tables already do,
condition-aware so "always" vs
"alone" stay distinct) and **self-heals** pre-existing duplicates on
load, so a remap can no
longer appear twice in the list after mixed GUI / hand-edited-config
changes.

**Known limitations / follow-ups (intentionally not in this PR):**
- Hold-timeout not implemented (holding the alone key then releasing
still fires the alone action;
  needs an injectable clock — deferred, noted in code).
- Alone *target* supports a single key or a shortcut (not text/URL/app).

## Validation Steps Performed

- Engine unit tests: **110/110** (alone tests + edge cases, incl. 2 new
mouse-promotion cases).
  Editor C++ tests: **88/88**.
- Editor UI project compiles clean (0 warnings / 0 errors).
- **Manual E2E on real hardware** (self-built x64 Release, multiple
machines):
- Right Ctrl tapped alone → IME On; Left Ctrl tapped alone → IME Off
(directional, idempotent).
- Ctrl+C / V / Z / A and existing Ctrl-based custom shortcuts unaffected
(keyboard modifier
    pass-through OK).
- **Ctrl+Click and Ctrl+Wheel** work while an alone-mapped Ctrl is held
(mouse-combo pass-through).
- Left Ctrl and Right Ctrl can both be mapped at once with no false
"conflicting modifier" error.
- Editor UI: opening an existing alone remap shows Condition = "Alone
(tap)"; saving round-trips a
full real-world config (single-key + dozens of global and app-specific
shortcuts) with **zero
loss** and **no duplicate rows**; the "Alone" badge and the show/hide
gating of the Condition
    combo both behave correctly.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-31 10:34:38 +00:00
..
common
[DevDocs] More content and restructure (#40165)
2025-07-01 14:27:34 +02:00
core
Docs: Fix broken links and incorrect source file references (#49294)
2026-07-16 12:50:09 +00:00
development
[UITests][PowerRename] Migrate to new .Next and add more UI tests (#50096)
2026-08-26 00:26:10 +02:00
images
Shortcut Guide V2 (#40834)
2026-05-21 17:27:52 +02:00
modules
[Keyboard Manager] Add "alone" (tap) condition for single-key remaps (dual-key / to_if_alone) (#49136)
2026-08-31 10:34:38 +00:00
processes
Resolve spelling check noise (#40433)
2025-07-07 13:08:48 +08:00
tools
[UITests] New framework around WinApp CLI, no WinAppDriver or Selenium. (#48467)
2026-07-08 13:58:08 +08:00
akaLinks.md
[VCM]Deprecate the Video Conference Mute utility (#36772)
2025-01-16 15:17:34 +00:00
cli-conventions.md
Add native CLI shims for PowerToys command-line tools (#48631)
2026-08-14 14:32:27 +08:00
commands.md
Add issue triage actions (#49828)
2026-08-14 14:57:02 +08:00
disk-usage-footprint.md
…
embedded-msix.md
…
events.md
Add developer documentation for implementing telemetry events in PowerToys modules. (#44912)
2026-02-10 11:22:51 -08:00
guidance.md
Fix broken style.md links in devdocs (#44457)
2026-01-04 12:23:45 +08:00
logging.md
Centralize c# logger (#22760)
2023-03-21 10:27:29 +01:00
readme.md
docs(devdocs): update docs.microsoft.com to learn.microsoft.com (#50102)
2026-08-26 00:26:27 +02:00
run-as-admin-detection.md
…
watson-queries.md
Move wiki triage queries into the repo (#48744)
2026-07-08 14:15:21 +00:00

readme.md

PowerToys Developer Documentation

Welcome to the PowerToys developer documentation. This documentation provides information for developers who want to contribute to PowerToys or understand how it works.

Getting Started

Prerequisites

  1. Windows 10 April 2018 Update (version 1803) or newer
  2. Visual Studio 2026 (recommended) or Visual Studio 2022 17.4+ with the following workloads/components:
    • Desktop Development with C++
    • WinUI application development
    • .NET desktop development
    • Windows 11 SDK (10.0.22621.0)
    • Windows 11 SDK (10.0.26100.3916)
  3. .NET 8 SDK
  4. Enable long paths in Windows (see Enable Long Paths for details)

Tip: You can install Visual Studio with all required workloads automatically using the WinGet configuration files in the repository:

winget configure .config\configuration.winget

Pick the file that matches your VS edition (e.g., configuration.vsProfessional.winget or configuration.vsEnterprise.winget).

Fork, Clone, and Set Up

  1. Fork the repo on GitHub if you haven't already
  2. Clone your fork locally
  3. Run the automated setup script (recommended):
.\tools\build\setup-dev-environment.ps1

This script will:

  • Enable Windows long path support (requires administrator privileges)
  • Enable Windows Developer Mode (requires administrator privileges)
  • Guide you through installing required Visual Studio components from .vsconfig
  • Initialize git submodules

Run with -Help to see all available options.

Manual setup (if you prefer not to use the script)

Install Visual Studio dependencies

  1. Open the PowerToys.slnx file.
  2. If you see a dialog that says install extra components in the solution explorer pane, click install

Alternatively, import the .vsconfig file from the repository root using Visual Studio Installer to install all required workloads.

Initialize submodules

This is a one-time step required before you can compile most parts of PowerToys.

  1. Open a terminal
  2. Navigate to the folder you cloned PowerToys to.
  3. Run git submodule update --init --recursive

Building

Using Visual Studio

  • Open PowerToys.slnx in Visual Studio.
  • In the Solutions Configuration drop-down menu select Release or Debug.
  • From the Build menu choose Build Solution, or press Control+Shift+b on your keyboard.
  • The build process may take several minutes depending on your computer's performance. Once it completes, the PowerToys binaries will be in your repo under x64\Release\.
    • You can run x64\Release\PowerToys.exe directly without installing PowerToys, but some modules (i.e. PowerRename, ImageResizer, File Explorer extension etc.) will not be available unless you also build the installer and install PowerToys.

Using Command Line

You can also build from the command line using the provided scripts in tools\build\:

# Build the full solution (auto-detects platform)
.\tools\build\build.ps1

# Build with specific configuration
.\tools\build\build.ps1 -Platform x64 -Configuration Release

# Build only essential projects (runner + settings) for faster iteration
.\tools\build\build-essentials.ps1

# Build everything including the installer (Release only)
.\tools\build\build-installer.ps1

Debugging

See Debugging for detailed debugging techniques, including Visual Studio setup, attaching to child processes, and troubleshooting build errors.

Creating a New PowerToy

See Creating a New PowerToy for an end-to-end guide covering module architecture, settings integration, installer packaging, and testing.

Building Command Palette Extensions

If you want to build your own extensions for Command Palette, check out the Command Palette extensibility documentation. It covers how to create, package, and distribute custom extensions that integrate with Command Palette.

Development Guidelines

Rules

  • Follow the pattern of what you already see in the code.
  • Coding style.
  • Try to package new functionality/components into libraries that have nicely defined interfaces.
  • Package new functionality into classes or refactor existing functionality into a class as you extend the code.
  • When adding new classes/methods/changing existing code, add new unit tests or update the existing tests.

GitHub Workflow

  • Before starting to work on a fix/feature, make sure there is an open issue to track the work.
  • Add the In progress label to the issue, if not already present. Also add a Cost-Small/Medium/Large estimate and make sure all appropriate labels are set.
  • If you are a community contributor, you will not be able to add labels to the issue; in that case just add a comment saying that you have started work on the issue and try to give an estimate for the delivery date.
  • If the work item has a medium/large cost, using the markdown task list, list each sub item and update the list with a check mark after completing each sub item.
  • Before opening a PR, ensure your changes build successfully locally and functionality tests pass. This is especially important for AI-assisted (vibe coding) contributions—always verify AI-generated code works as intended. Exploratory PRs or draft PRs for discussion are exceptions.
  • When opening a PR, follow the PR template.
  • When you'd like the team to take a look (even if the work is not yet fully complete) mark the PR as 'Ready For Review' so that the team can review your work and provide comments, suggestions, and request changes. It may take several cycles, but the end result will be solid, testable, conformant code that is safe for us to merge.
  • When the PR is approved, let the owner of the PR merge it. For community contributions, the reviewer who approved the PR can also merge it.
  • Use the Squash and merge option to merge a PR. If you don't want to squash it because there are logically different commits, use Rebase and merge.
  • Close issues automatically when referenced in a PR. You can use closing keywords in the body of the PR to have GitHub automatically link your PR to the issue.

Core Architecture

Common Components

  • Context Menu Handlers - How PowerToys implements and registers Explorer context menu handlers
  • Monaco Editor - How PowerToys uses the Monaco code editor component across modules

Tools

Processes

Other Resources

Building the Installer

Our installer is two parts, an EXE and an MSI. The EXE (Bootstrapper) contains the MSI and handles more complex installation logic.

  • The EXE installs all prerequisites and installs PowerToys via the MSI. It has additional features such as the installation flags (see below).
  • The MSI installs the PowerToys binaries.

The installer can only be compiled in Release mode; steps 1 and 2 must be performed before the MSI can be compiled.

  1. Compile PowerToys.slnx. Instructions are listed above.
  2. Compile BugReportTool.sln tool. Path from root: tools\BugReportTool\BugReportTool.sln (details listed below)
  3. Compile StylesReportTool.sln tool. Path from root: tools\StylesReportTool\StylesReportTool.sln (details listed below)
  4. Compile PowerToysSetup.slnx Path from root: installer\PowerToysSetup.slnx (details listed below)

See Installer for more details on building and debugging the installer.

Reference in New Issue View Git Blame Copy Permalink