Mirrors/PowerToys
1
0
Fork 0
mirror of https://github.com/microsoft/PowerToys.git synced 2026-08-29 10:09:43 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
1703e7ac09ed132361c1700f75da9182f2ee8c54
PowerToys/doc/devdocs
History
moooyo 8f63402400 PowerDisplay: Adjust brightness by scrolling over the tray icon (#49446) 
## Summary of the Pull Request

Scrolling the mouse wheel over the Power Display tray icon adjusts
brightness, without opening the flyout.

- New **Tray icon mouse wheel** setting: `Off` / `Primary display` /
`All displays`, defaulting to **`Off`**. It is scoped to the tray icon —
the flyout sliders accept wheel input regardless, as they always have.
The existing **Mouse wheel increment** setting supplies the per-notch
step.
- **Off by default.** The gesture consumes a wheel notch that would
otherwise reach the window under the pointer, and acting on it installs
a system-wide `WH_MOUSE_LL` hook. Neither is something an existing
installation should acquire silently on upgrade. With the setting `Off`
no hook is ever installed and no notch is ever consumed, so this PR
changes no existing behaviour until the user opts in: 1958 insertions, 2
deletions, and both deletions are refactors of lines this feature
reuses.
- **No feedback UI.** Brightness is self-evidencing — you scroll and the
screen changes — so the display itself is the feedback. The notification
icon is untouched: same tooltip, same text, same legacy
notification-icon protocol.

## PR Checklist

- [x] Closes: #49410
- [ ] **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
- [ ] [JSON for
signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json)
for new binaries
- [ ] [WXS for
installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs)
for new binaries and localization folder
- [ ] [YML for CI
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml)
for new test projects
- [ ] [YML for signed
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml)
- [ ] **Documentation updated:** If checked, please file a pull request
on [our docs
repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys)
and link it here: #xxx

No new binaries or projects — everything lands in existing assemblies.
Communication is unchecked because #49410 is still Needs-Triage.

## Detailed Description of the Pull Request / Additional comments

### Why a low-level hook

The Shell does not forward `WM_MOUSEWHEEL` to a notification icon's
callback window under any `NOTIFYICON_VERSION`, and a click-through
overlay placed over the icon cannot receive wheel input either.
`TrayIconMouseWheelListener` therefore installs a `WH_MOUSE_LL` hook —
but only transiently, and only when it will act on the result:

- Nothing is installed at all while the setting is `Off`, which is the
default.
- Installed in `EnsureHook()` when the UI thread confirms the pointer is
inside the rectangle from `Shell_NotifyIconGetRect` **and**
`CanAdjustBrightnessFromTrayWheel` says some monitor can accept a
brightness write.
- Removed in `DisarmCore()` as soon as either condition stops holding,
the pointer leaves the rectangle, or the mode changes.
- A notch is consumed (the hook proc returns non-zero) only while armed
and only for points inside the armed rectangle, so a wheel event Power
Display will not act on still reaches the window under the cursor.

The hook runs on a dedicated background thread with its own message
loop; the proc itself only enqueues a sample and posts a drain request.
Deltas are marshalled to the UI thread in batches, and
`WheelDeltaAccumulator` folds high-resolution deltas (precision wheels,
touchpads) into whole notches. Each sample carries the hover generation
it was captured under, so samples from a hover the UI thread has already
retired are discarded rather than applied late.

### Hover detection

The Shell sends `WM_MOUSEMOVE` to the icon's callback window while the
pointer is over it. `TrayIconService.HandleTrayMouseMove` resolves the
rectangle with `Shell_NotifyIconGetRect` and caches it for a second,
because that message repeats for every pixel of travel.

`TrayIconService` gains nothing else: no protocol change, no new hover
UI, no polling. The rest of the file — and `MainWindow.xaml` — is
untouched.

### Linked brightness

While linked brightness is on, a notch has to move the whole group, so
it goes through `MainViewModel.LinkedBrightness` rather than the
individual monitor setters. The new master value is taken from the
planner's value for the monitor the wheel named, **not** from the
current master. The master is positional only —
`SeedInitialLinkedBrightness` takes it from the lowest-numbered linked
monitor and never writes hardware, and every monitor-list rebuild
re-seeds it — so it can sit arbitrarily far from the monitor the wheel
is aimed at. Stepping it relative to itself would apply a wrong-sized or
wrong-signed change, and a master already clamped at 0/100 would swallow
the notch while writing nothing at all.

The setting description calls out that linked brightness widens the
scope, so `Primary display` is not literally a single display while it
is on.

### What is deliberately not here

An earlier revision of this PR showed the target and percentage in a
custom overlay as you scrolled. Doing that meant the standard Shell
tooltip would not do (it cannot be shown on demand), which meant an own
window, which meant suppressing the Shell tooltip so the two did not
collide, which meant `NOTIFYICON_VERSION_4`, which changed the callback
packing and made the app responsible for all hover text — including for
keyboard and touch users, who never reach a cursor-anchored overlay and
would have been left with no visible tooltip at all.

That chain was about half the diff, for a readout that adds little on
top of watching the screen change. It is gone. If a readout is wanted
later it can be argued on its own merits, separately from this feature.

The same revision also gated the flyout sliders on this setting. That
bundled two unrelated things behind one switch — turning off tray
scrolling would also have stopped the contrast and volume sliders
responding to the wheel — so the setting is now scoped to the tray icon
and named accordingly.

An earlier revision also routed the tray **Exit** action through
`Shutdown()`. That fixes a pre-existing teardown leak which has nothing
to do with this feature, so it now lives in #49580 and is out of scope
here. This branch does not depend on it: the hook thread is a background
thread and the process is ending either way.

## Validation Steps Performed

- Unit tests: `PowerDisplay.Lib.UnitTests` 215 passed,
`Settings.UI.UnitTests` 165 passed.
- Builds: `PowerDisplay` and Settings UI, x64 Debug, no warnings.
- Automated coverage is in `PowerDisplay.Lib.UnitTests`: target
selection per mode, wheel accumulation including negative deltas,
partial notches and direction reversal, half-open rectangle containment,
and settings serialization and round-trip for the new mode, including
that a settings file predating the feature loads as `Off`.
`Settings.UI.UnitTests` covers the view-model index mapping and pins the
enum values to the ComboBox item order.
- The Win32 glue in `TrayIconService` and `TrayIconMouseWheelListener`
is not unit tested.

Manual passes performed: scrolling over the icon in both modes, the icon
parked in the notification overflow, high-resolution wheel input,
brightness boundaries, live monitor refresh while hovering, tray icon
hidden and re-enabled, Explorer restart, the context menu and
left-click, `Off` stopping tray scrolling while the flyout sliders keep
working, and confirming a notch that Power Display will not act on still
reaches the window under the cursor.

Not verified, needing hardware this branch has not been run on:

- Multiple taskbars, where the tray icon is on a secondary display and
`Primary display` mode adjusts a monitor the user may not be looking at.
- Mixed-DPI setups, for the `Shell_NotifyIconGetRect` rectangle and the
hook's physical-pixel hit test.

---------

Co-authored-by: Yu Leng <yuleng@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copilot-Session: 5d7f36fe-d175-4aa9-a3c7-b370d952d1d3
2026-07-31 16:21:08 +08: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
Make PowerShell script invocation more reliable (#46729)
2026-07-09 08:55:21 +00:00
images
Shortcut Guide V2 (#40834)
2026-05-21 17:27:52 +02:00
modules
PowerDisplay: Adjust brightness by scrolling over the tray icon (#49446)
2026-07-31 16:21:08 +08: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 standard CLI support for Image Resizer (#44287)
2025-12-26 12:54:47 +08:00
commands.md
Add documentation of bot commands and fix some devdocs (#43399)
2025-12-05 14:55:45 +01:00
disk-usage-footprint.md
[devdocs] Add disk usage footprint doc (#23248)
2023-01-25 18:36:25 +01:00
embedded-msix.md
[Docs] Add msix embedding instructions (#13489)
2021-09-30 14:29:05 +03:00
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
Fix dev setup .vsconfig component IDs for Visual Studio 2026 (#48824)
2026-07-08 14:01:15 +00:00
run-as-admin-detection.md
Create run-as-admin-detection.md
2020-07-29 17:43:43 -07:00
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