From 4e202e45237d968e3a5f67003d084ef7433538f3 Mon Sep 17 00:00:00 2001 From: Aaron Junker Date: Wed, 28 Sep 2022 18:18:55 +0200 Subject: [PATCH] [Docs]Replace docs.micrososft.com with learn.microsoft.com (#20662) * Update SUPPORT.md * Update runner.md * Update guidance.md * Update convert-stringtable-to-resx.ps1 * Update readme.md * Update ControlType.cs * Update README.md * Update CLSID.h * Update GenericProperty`1.cs * Update project-overview.md * Update interop.cpp * Update PreviewHandlerBase.cs * Update indexer.md * Update common.md * Update two_way_pipe_message_ipc.cpp * Update PowerToys.exe.manifest * Update HotkeySettings.cs * push * Update src/tests/win-app-driver/README.md * Update doc/devdocs/akaLinks.md * Update doc/devdocs/modules/launcher/plugins/registry.md --- README.md | 4 +-- SUPPORT.md | 2 +- doc/devdocs/akaLinks.md | 28 +++++++++---------- doc/devdocs/common.md | 2 +- doc/devdocs/guidance.md | 10 +++---- doc/devdocs/localization.md | 6 ++-- .../keyboardmanager/keyboardeventhandlers.md | 6 ++-- .../keyboardmanager/keyboardmanager.md | 6 ++-- .../keyboardmanager/keyboardmanagerui.md | 2 +- .../modules/launcher/plugins/indexer.md | 8 +++--- .../modules/launcher/plugins/registry.md | 6 ++-- doc/devdocs/readme.md | 2 +- doc/devdocs/runner.md | 4 +-- doc/devdocs/settingsv2/project-overview.md | 2 +- .../CustomAction.cpp | 4 +-- src/common/Telemetry/readme.md | 4 +-- src/common/interop/interop.cpp | 2 +- .../interop/two_way_pipe_message_ipc.cpp | 10 +++---- src/common/notifications/notifications.cpp | 2 +- .../MeasureToolUI/MeasureToolUI.csproj | 2 +- src/modules/PowerOCR/PowerOCR/app.manifest | 2 +- src/modules/awake/Awake/Awake.csproj | 2 +- .../awake/Awake/Core/Models/ControlType.cs | 2 +- .../ColorPickerUI/Helpers/AppStateHandler.cs | 2 +- .../ColorPickerUI/NativeMethods.cs | 2 +- .../imageresizer/ui/Models/ResizeOperation.cs | 2 +- .../KeyboardManagerEditor.exe.manifest | 2 +- .../KeyDropDownControl.cpp | 2 +- .../ShortcutControl.cpp | 2 +- .../SingleKeyRemapControl.cpp | 2 +- .../KeyboardManagerEngineTest/MockedInput.cpp | 4 +-- .../keyboardmanager/common/Shortcut.cpp | 2 +- .../SearchHelper/WindowsSearchAPI.cs | 2 +- .../Programs/UWPApplication.cs | 4 +-- .../Programs/Win32Program.cs | 2 +- .../Main.cs | 2 +- .../Helper/ContextMenuHelper.cs | 2 +- .../Properties/Resources.resx | 6 ++-- .../Components/TimeAndDateHelper.cs | 2 +- .../Helper/ContextMenuHelper.cs | 2 +- .../Helper/ContextMenuHelper.cs | 2 +- .../PowerLauncher/Helper/NativeMethods.cs | 4 +-- .../launcher/PowerLauncher/ResultList.xaml.cs | 2 +- .../Exception/ExceptionFormatter.cs | 2 +- .../VirtualDesktop/CVirtualDesktopManager.cs | 2 +- .../VirtualDesktop/IVirtualDesktopManager.cs | 2 +- .../VirtualDesktop/VirtualDesktopHelper.cs | 4 +-- .../Wox.Plugin/Common/Win32/NativeMethods.cs | 4 +-- .../powerrename/lib/PowerRenameManager.cpp | 4 +-- .../MarkdownPreviewHandlerControl.cs | 2 +- src/modules/previewpane/README.md | 4 +-- .../SvgPreviewHandler/SvgPreviewControl.cs | 2 +- .../SvgThumbnailProvider.cs | 2 +- .../NativeMethods.cs | 2 +- .../common/Utilities/ReadonlyStream.cs | 4 +-- .../cominterop/IInitializeWithStream.cs | 2 +- .../common/cominterop/IPreviewHandlerFrame.cs | 2 +- .../common/controls/FormHandlerControl.cs | 2 +- .../common/controls/IPreviewHandlerControl.cs | 4 +-- .../common/handlers/PreviewHandlerBase.cs | 6 ++-- src/modules/previewpane/powerpreview/CLSID.h | 4 +-- src/runner/PowerToys.exe.manifest | 4 +-- .../Settings.UI.Library/GenericProperty`1.cs | 2 +- .../Settings.UI.Library/HotkeySettings.cs | 4 +-- .../ModelsTests/BasePTModuleSettingsTest.cs | 2 +- src/tests/win-app-driver/README.md | 2 +- tools/build/convert-stringtable-to-resx.ps1 | 2 +- 67 files changed, 119 insertions(+), 119 deletions(-) diff --git a/README.md b/README.md index b81f52ee74..c1d709f396 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ ## About -Microsoft PowerToys is a set of utilities for power users to tune and streamline their Windows experience for greater productivity. For more info on [PowerToys overviews and how to use the utilities][usingPowerToys-docs-link], or any other tools and resources for [Windows development environments](https://docs.microsoft.com/windows/dev-environment/overview), head over to [docs.microsoft.com][usingPowerToys-docs-link]! +Microsoft PowerToys is a set of utilities for power users to tune and streamline their Windows experience for greater productivity. For more info on [PowerToys overviews and how to use the utilities][usingPowerToys-docs-link], or any other tools and resources for [Windows development environments](https://learn.microsoft.com/windows/dev-environment/overview), head over to [learn.microsoft.com][usingPowerToys-docs-link]! | | Current utilities: | | |--------------|--------------------|--------------| @@ -31,7 +31,7 @@ Microsoft PowerToys is a set of utilities for power users to tune and streamline - Our installer will install the following items: - [.NET 6.0.8 Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/6.0#runtime-desktop-6.0.8) or a newer 6.0.x runtime. - [Microsoft Edge WebView2 Runtime](https://go.microsoft.com/fwlink/p/?LinkId=2124703) bootstrapper. This will install the latest version. - - [Microsoft Visual C++ Redistributable](https://docs.microsoft.com/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022) installer. This will install one of the latest versions available. + - [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022) installer. This will install one of the latest versions available. ### Via GitHub with EXE [Recommended] diff --git a/SUPPORT.md b/SUPPORT.md index da76b0ac02..99ea4e3f4b 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -3,7 +3,7 @@ ## How to use Microsoft PowerToys -For more info on [PowerToys overviews and how to use the utilities][usingPowerToys-docs-link], or any other tools and resources for [Windows development environments](https://docs.microsoft.com/windows/dev-environment/overview), head over to [docs.microsoft.com][usingPowerToys-docs-link]! +For more info on [PowerToys overviews and how to use the utilities][usingPowerToys-docs-link], or any other tools and resources for [Windows development environments](https://learn.microsoft.com/windows/dev-environment/overview), head over to [learn.microsoft.com][usingPowerToys-docs-link]! ## How to file issues and get help diff --git a/doc/devdocs/akaLinks.md b/doc/devdocs/akaLinks.md index 8dc69c3382..6b0dcac1d8 100644 --- a/doc/devdocs/akaLinks.md +++ b/doc/devdocs/akaLinks.md @@ -7,11 +7,11 @@ | powertoys-license | https://github.com/microsoft/PowerToys/blob/main/LICENSE | | powertoys | https://github.com/microsoft/PowerToys | | PowerToysAppCompat | https://github.com/microsoft/PowerToys/wiki/Application-Compatibility | -| powerToysCannotRemapKeys | https://docs.microsoft.com/windows/powertoys/keyboard-manager#keys-that-cannot-be-remapped | +| powerToysCannotRemapKeys | https://learn.microsoft.com/windows/powertoys/keyboard-manager#keys-that-cannot-be-remapped | | powerToysColorPickerImageSmall | https://github.com/microsoft/PowerToys/wiki/images/overview/ColorPicker_small.png | | powerToysColorPickerSettingImage | https://raw.githubusercontent.com/microsoft/PowerToys/main/doc/images/overview/ColorPicker_large.png | -| powertoysDetectedElevatedHelp | https://docs.microsoft.com/windows/powertoys/administrator | -| powertoys-docs | https://docs.microsoft.com/windows/powertoys/?WT.mc_id=twitter-0000-docsmsft | +| powertoysDetectedElevatedHelp | https://learn.microsoft.com/windows/powertoys/administrator | +| powertoys-docs | https://learn.microsoft.com/windows/powertoys | | powerToysFancyZoneImageSmall | https://github.com/microsoft/PowerToys/wiki/images/overview/FancyZones_small.png | | powerToysFancyZoneSettingImage | https://raw.githubusercontent.com/microsoft/PowerToys/main/doc/images/overview/FancyZones_large.png | | powerToysGiveFeedback | https://github.com/microsoft/PowerToys/issues | @@ -19,17 +19,17 @@ | powerToysImageResizerSettingImage | https://raw.githubusercontent.com/microsoft/PowerToys/main/doc/images/overview/ImageResizer_large.png | | powerToysKBMImageSmall | https://github.com/microsoft/PowerToys/wiki/images/overview/KBM_small.png | | powerToysKBMSettingImage | https://raw.githubusercontent.com/microsoft/PowerToys/main/doc/images/overview/KBM_large.png | -| PowerToysOverview | https://docs.microsoft.com/windows/powertoys/ | -| PowerToysOverview_ColorPicker | https://docs.microsoft.com/windows/powertoys/color-picker | -| PowerToysOverview_FancyZones | https://docs.microsoft.com/windows/powertoys/fancyzones | -| PowerToysOverview_FileExplorerAddOns | https://docs.microsoft.com/windows/powertoys/file-explorer | -| PowerToysOverview_ImageResizer | https://docs.microsoft.com/windows/powertoys/image-resizer | -| PowerToysOverview_KeyboardManager | https://docs.microsoft.com/windows/powertoys/keyboard-manager | -| PowerToysOverview_MouseUtilities | https://docs.microsoft.com/windows/powertoys/mouse-utilities | -| PowerToysOverview_PowerRename | https://docs.microsoft.com/windows/powertoys/powerrename | -| PowerToysOverview_PowerToysRun | https://docs.microsoft.com/windows/powertoys/run | -| PowerToysOverview_ShortcutGuide | https://docs.microsoft.com/windows/powertoys/shortcut-guide | -| PowerToysOverview_VideoConference | https://docs.microsoft.com/windows/powertoys/video-conference-mute | +| PowerToysOverview | https://learn.microsoft.com/windows/powertoys/ | +| PowerToysOverview_ColorPicker | https://learn.microsoft.com/windows/powertoys/color-picker | +| PowerToysOverview_FancyZones | https://learn.microsoft.com/windows/powertoys/fancyzones | +| PowerToysOverview_FileExplorerAddOns | https://learn.microsoft.com/windows/powertoys/file-explorer | +| PowerToysOverview_ImageResizer | https://learn.microsoft.com/windows/powertoys/image-resizer | +| PowerToysOverview_KeyboardManager | https://learn.microsoft.com/windows/powertoys/keyboard-manager | +| PowerToysOverview_MouseUtilities | https://learn.microsoft.com/windows/powertoys/mouse-utilities | +| PowerToysOverview_PowerRename | https://learn.microsoft.com/windows/powertoys/powerrename | +| PowerToysOverview_PowerToysRun | https://learn.microsoft.com/windows/powertoys/run | +| PowerToysOverview_ShortcutGuide | https://learn.microsoft.com/windows/powertoys/shortcut-guide | +| PowerToysOverview_VideoConference | https://learn.microsoft.com/windows/powertoys/video-conference-mute | | powerToysPowerLauncherImageSmall | https://github.com/microsoft/PowerToys/wiki/images/overview/PowerLauncher_small.png | | powerToysPowerLauncherSettingImage | https://raw.githubusercontent.com/microsoft/PowerToys/main/doc/images/overview/PowerLauncher_large.png | | powerToysPowerPreviewImageSmall | https://github.com/microsoft/PowerToys/wiki/images/overview/PowerPreview_small.png | diff --git a/doc/devdocs/common.md b/doc/devdocs/common.md index eb26391370..48db53733b 100644 --- a/doc/devdocs/common.md +++ b/doc/devdocs/common.md @@ -95,6 +95,6 @@ namespace ``` -Note: since _background activation_ implies that your toast handler will be invoked in a separate process, you can't share data directly from within a handler and your PT process. Also, since PT is currently a Desktop Bridge app, _foreground activation_ is [handled the same as background](https://docs.microsoft.com/en-US/windows/uwp/design/shell/tiles-and-notifications/send-local-toast-desktop-cpp-wrl#foreground-vs-background-activation), therefore we don't make a dedicated API for it. You can read more on the rationale of the current design [here](https://github.com/microsoft/PowerToys/pull/1178#issue-368768337). +Note: since _background activation_ implies that your toast handler will be invoked in a separate process, you can't share data directly from within a handler and your PT process. Also, since PT is currently a Desktop Bridge app, _foreground activation_ is [handled the same as background](https://learn.microsoft.com/windows/uwp/design/shell/tiles-and-notifications/send-local-toast-desktop-cpp-wrl#foreground-vs-background-activation), therefore we don't make a dedicated API for it. You can read more on the rationale of the current design [here](https://github.com/microsoft/PowerToys/pull/1178#issue-368768337). diff --git a/doc/devdocs/guidance.md b/doc/devdocs/guidance.md index 2edbc2db9f..c3a5bc0830 100644 --- a/doc/devdocs/guidance.md +++ b/doc/devdocs/guidance.md @@ -62,8 +62,8 @@ Please review these brief docs below relating to our coding standards etc. * [Code Organization](./readme.md) -[VS Resource Editor]: https://docs.microsoft.com/en-us/cpp/windows/resource-editors?view=vs-2019 -[String Table]: https://docs.microsoft.com/en-us/windows/win32/menurc/stringtable-resource -[Resx Files VS]: https://docs.microsoft.com/en-us/dotnet/framework/resources/creating-resource-files-for-desktop-apps#resource-files-in-visual-studio -[Resx Files]: https://docs.microsoft.com/en-us/dotnet/framework/resources/creating-resource-files-for-desktop-apps#resources-in-resx-files -[Resource Manager]: https://docs.microsoft.com/en-us/dotnet/api/system.resources.resourcemanager?view=netframework-4.8 \ No newline at end of file +[VS Resource Editor]: https://learn.microsoft.com/cpp/windows/resource-editors?view=vs-2019 +[String Table]: https://learn.microsoft.com/windows/win32/menurc/stringtable-resource +[Resx Files VS]: https://learn.microsoft.com/dotnet/framework/resources/creating-resource-files-for-desktop-apps#resource-files-in-visual-studio +[Resx Files]: https://learn.microsoft.com/dotnet/framework/resources/creating-resource-files-for-desktop-apps#resources-in-resx-files +[Resource Manager]: https://learn.microsoft.com/dotnet/api/system.resources.resourcemanager?view=netframework-4.8 diff --git a/doc/devdocs/localization.md b/doc/devdocs/localization.md index 2e1764c5b8..a3842a9f8c 100644 --- a/doc/devdocs/localization.md +++ b/doc/devdocs/localization.md @@ -50,7 +50,7 @@ The rest of the steps depend on the project type and are covered in the sections ### C++ C++ projects do not support `resx` files, and instead use `rc` files along with `resource.h` files. The CDPX pipeline however doesn't support localizing `rc` files and the other alternative they support is directly translating the resources from the binary which makes it harder to maintain resources. To avoid this, a custom script has been added which expects a resx file and converts the entries to an rc file with a string table and adds resource declarations to a resource.h file so that the resources can be compiled with the C++ project. -If you already have a .rc file, copy the string table to a separate txt file and run the [convert-stringtable-to-resx.ps1](https://github.com/microsoft/PowerToys/blob/main/tools/build/convert-stringtable-to-resx.ps1) script on it. This script is not very robust to input, and requires the data in a specific format, where `IDS_ResName L"ResourceValue"` and any number of spaces can be present in between. The script converts this file to the format expected by [`resgen`](https://docs.microsoft.com/en-us/dotnet/framework/tools/resgen-exe-resource-file-generator#Convert), which will convert it to resx. The resource names are changed from all uppercase to title case, and the `IDS_` prefix is removed. Escape characters might have to be manually replaced, for example .rc files would have escaped double quotes as `""`, so this should be replaced with just `"` before converting to the resx files. +If you already have a .rc file, copy the string table to a separate txt file and run the [convert-stringtable-to-resx.ps1](https://github.com/microsoft/PowerToys/blob/main/tools/build/convert-stringtable-to-resx.ps1) script on it. This script is not very robust to input, and requires the data in a specific format, where `IDS_ResName L"ResourceValue"` and any number of spaces can be present in between. The script converts this file to the format expected by [`resgen`](https://learn.microsoft.com/dotnet/framework/tools/resgen-exe-resource-file-generator#Convert), which will convert it to resx. The resource names are changed from all uppercase to title case, and the `IDS_` prefix is removed. Escape characters might have to be manually replaced, for example .rc files would have escaped double quotes as `""`, so this should be replaced with just `"` before converting to the resx files. After generating the resx file, rename the existing rc and h files to ProjName.base.rc and resource.base.h. In the rc file remove the string table which is to be localized and in the .h file remove all `#define`s corresponding to localized resources. In the vcxproj of the C++ project, add the following build event: ``` @@ -59,7 +59,7 @@ After generating the resx file, rename the existing rc and h files to ProjName.b ``` -This event runs a script which generates a resource.h and ProjName.rc in the `Generated Files` folder using the strings in all the resx files along with the existing information in resource.base.h and ProjName.base.rc. The script can be found [here](https://github.com/microsoft/PowerToys/blob/main/tools/build/convert-resx-to-rc.ps1). The script uses [`resgen`](https://docs.microsoft.com/en-us/dotnet/framework/tools/resgen-exe-resource-file-generator#Convert) to convert the resx file to a string table expected in the .rc file format. When the resources are added to the rc file the `IDS_` prefix is added and resource names are in upper case (as it was originally). Any occurrences of `"` in the string resource is escaped as `""` to prevent build errors. The string tables are added to the rc file in the following format: +This event runs a script which generates a resource.h and ProjName.rc in the `Generated Files` folder using the strings in all the resx files along with the existing information in resource.base.h and ProjName.base.rc. The script can be found [here](https://github.com/microsoft/PowerToys/blob/main/tools/build/convert-resx-to-rc.ps1). The script uses [`resgen`](https://learn.microsoft.com/dotnet/framework/tools/resgen-exe-resource-file-generator#Convert) to convert the resx file to a string table expected in the .rc file format. When the resources are added to the rc file the `IDS_` prefix is added and resource names are in upper case (as it was originally). Any occurrences of `"` in the string resource is escaped as `""` to prevent build errors. The string tables are added to the rc file in the following format: ``` #if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_ENU) LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US @@ -88,7 +88,7 @@ Since C# projects natively support `resx` files, the only step required here is **Note:** Building with localized resources may cause a build warning `Referenced assembly 'mscorlib.dll' targets a different processor` which is a VS bug. More details can be found [here](https://github.com/microsoft/PowerToys/issues/7269). -**Note:** If a project needs to be migrated from XAML resources to resx, the easiest way to convert the resources would be to change to format to `=` separates resources by either manually (by Ctrl+H on a text editor), or by a script, and then running [`resgen`](https://docs.microsoft.com/en-us/dotnet/framework/tools/resgen-exe-resource-file-generator#Convert) on `Developer Command Prompt for VS` to convert it to resx format. +**Note:** If a project needs to be migrated from XAML resources to resx, the easiest way to convert the resources would be to change to format to `=` separates resources by either manually (by Ctrl+H on a text editor), or by a script, and then running [`resgen`](https://learn.microsoft.com/dotnet/framework/tools/resgen-exe-resource-file-generator#Convert) on `Developer Command Prompt for VS` to convert it to resx format. ``` Calculator Allows to do mathematical calculations.(Try 5*3-2 in Wox) diff --git a/doc/devdocs/modules/keyboardmanager/keyboardeventhandlers.md b/doc/devdocs/modules/keyboardmanager/keyboardeventhandlers.md index 1732694dcb..f8ee72ea4f 100644 --- a/doc/devdocs/modules/keyboardmanager/keyboardeventhandlers.md +++ b/doc/devdocs/modules/keyboardmanager/keyboardeventhandlers.md @@ -66,15 +66,15 @@ This file contains documentation for all the methods involved in key/shortcut re [This method](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/dll/KeyboardEventHandlers.cpp#L126-L176) was added to support a feature for converting the behavior of a key from behaving like a toggle (like Caps Lock/Num Lock) to a modifier (like Ctrl), such that when you hold Caps Lock it would behave as if Caps Lock was active, and when it was not pressed Caps Lock would be off. For Caps Lock this would be similar to behaving like Shift, but for Num Lock there is no existing key which can substitute for this. This was added while testing out remapping for the KBM PoC, but wasn't added as a feature since it wasn't a priority. ## Tests -In order to test the remapping logic, a mocked keyboard input handler had to be created because otherwise the tests would process and send actual key events. For this the [`InputInterface`](https://github.com/microsoft/PowerToys/blob/main/src/modules/keyboardmanager/common/InputInterface.h) was made, and in production code the methods are implemented using [`SendInput`](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-sendinput) and [`GetAsyncKeyState`](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getasynckeystate). In addition to this, [`GetCurrentApplication`](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/common/Helpers.cpp#L226-L268) had to be mocked so that app-specific remapping can be tested. +In order to test the remapping logic, a mocked keyboard input handler had to be created because otherwise the tests would process and send actual key events. For this the [`InputInterface`](https://github.com/microsoft/PowerToys/blob/main/src/modules/keyboardmanager/common/InputInterface.h) was made, and in production code the methods are implemented using [`SendInput`](https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-sendinput) and [`GetAsyncKeyState`](https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-getasynckeystate). In addition to this, [`GetCurrentApplication`](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/common/Helpers.cpp#L226-L268) had to be mocked so that app-specific remapping can be tested. ### MockedInput The [`MockedInput`](https://github.com/microsoft/PowerToys/blob/main/src/modules/keyboardmanager/test/MockedInput.h) class uses a 256 size `bool` vector to store the key state for each key code. Identifying the foreground process is mocked by simply setting and getting a string value for the name of the current process. [To mock the `SendInput` method](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/test/MockedInput.cpp#L10-L110), the steps for processing the input are as follows. This implementation is based on public documentation for SendInput and the behavior of key messages and keyboard hooks: - Iterate over all the inputs in the INPUT array argument -- If the event is a key up event, then it is considered [`WM_SYSKEYUP`](https://docs.microsoft.com/en-us/windows/win32/inputdev/wm-syskeyup) if Alt is held down, otherwise it is `WM_KEYUP`. -- If the event is a key down event, then it is considered [`WM_SYSKEYDOWN`](https://docs.microsoft.com/en-us/windows/win32/inputdev/wm-syskeydown) if either Alt is held down or if it is F10, otherwise it is `WM_KEYDOWN`. +- If the event is a key up event, then it is considered [`WM_SYSKEYUP`](https://learn.microsoft.com/windows/win32/inputdev/wm-syskeyup) if Alt is held down, otherwise it is `WM_KEYUP`. +- If the event is a key down event, then it is considered [`WM_SYSKEYDOWN`](https://learn.microsoft.com/windows/win32/inputdev/wm-syskeydown) if either Alt is held down or if it is F10, otherwise it is `WM_KEYDOWN`. - An optional function which can be set on the `MockedInput` handler can be used to test for the number of times a key event is received by the system with a particular condition using [`sendVirtualInputCallCondition`](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/test/MockedInput.cpp#L48-L52). - The hook logic for a low level hook which returns 0 or 1 can be set on the `MockedInput` handler such that it behaves like a low level hook would behave with actual keyboard input. If the method returns 1, then the keyboard state is not updated, and if it returns 0 the corresponding key event is used to update the key state. This works in the recursive way as well similar to low level hooks, as `SendVirtualInput` can be called from within the hook, thus simulating identical behavior to calling `SendInput` in a low level hook (as soon as SendInput is called, the low level hook is called for the new input event, and only after those are processed it returns back to the current event, check this [blog](https://devblogs.microsoft.com/oldnewthing/20140213-00/?p=1773) for more details). - For updating the keyboard state, KEYUP messages result in the state for that key code being set to false, and KEYDOWN result in the state for that key code being set to true. diff --git a/doc/devdocs/modules/keyboardmanager/keyboardmanager.md b/doc/devdocs/modules/keyboardmanager/keyboardmanager.md index fbfa70784f..7924290748 100644 --- a/doc/devdocs/modules/keyboardmanager/keyboardmanager.md +++ b/doc/devdocs/modules/keyboardmanager/keyboardmanager.md @@ -27,7 +27,7 @@ The `KeyboardManager` module has [3 main class members](https://github.com/micro - An object of type `KeyboardManagerState`. This object contains all the data related to remappings and is also used in the sense of a View Model as it used to communicate common data that is shared between the KBM UI and the backend. This class is described in more detail [here](keyboardmanagercommon.md#keyboardmanagerstate). ## Enable/Disable -On enabling KBM, the low level keyboard hook is started, and it is unhooked on disable. This is done to allow users to manually restart KBM if some other application which registers a keyboard hook was launched after PowerToys, so that it can be brought back to the highest priority hook (as the last hook to be registered receives the input first as mentioned [here](https://docs.microsoft.com/en-us/windows/win32/winmsg/about-hooks#hook-procedures)). +On enabling KBM, the low level keyboard hook is started, and it is unhooked on disable. This is done to allow users to manually restart KBM if some other application which registers a keyboard hook was launched after PowerToys, so that it can be brought back to the highest priority hook (as the last hook to be registered receives the input first as mentioned [here](https://learn.microsoft.com/windows/win32/winmsg/about-hooks#hook-procedures)). In addition to stopping the hook, any active KBM UI windows are also closed on disabling. This is done because the KBM UI uses the same keyboard hook for the Type button where you can type a key/shortcut, so if KBM is disabled the windows would not be completely functional. @@ -129,7 +129,7 @@ KBM uses the [`call_custom_action`](https://github.com/microsoft/PowerToys/blob/ ## SendInput Special Scenarios ### Extended keys -Certain keys such as the arrow keys, right Ctrl/Alt, and Del/Home/Ins, etc need to be sent with the `KEYEVENTF_EXTENDEDKEY` flag because otherwise the NumPad versions get sent, which can cause weird behavior when NumLock is on. The code can be found [here](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/common/Helpers.cpp#L190-L194) and the list of extended keys in code can be found [here](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/common/Helpers.cpp#L73-L98). Docs about extended keys can be found [here](https://docs.microsoft.com/en-us/windows/win32/inputdev/about-keyboard-input#extended-key-flag). +Certain keys such as the arrow keys, right Ctrl/Alt, and Del/Home/Ins, etc need to be sent with the `KEYEVENTF_EXTENDEDKEY` flag because otherwise the NumPad versions get sent, which can cause weird behavior when NumLock is on. The code can be found [here](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/common/Helpers.cpp#L190-L194) and the list of extended keys in code can be found [here](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/common/Helpers.cpp#L73-L98). Docs about extended keys can be found [here](https://learn.microsoft.com/windows/win32/inputdev/about-keyboard-input#extended-key-flag). The weird behavior that is caused by this can be found at these issues: - https://github.com/microsoft/PowerToys/issues/3478 @@ -173,7 +173,7 @@ For example, while [remapping Ctrl to Caps Lock](https://g While the above work around fixes most of the cases, there are still some scenarios where the modifier can get stuck, mentioned at this [comment](https://github.com/microsoft/PowerToys/issues/3397#issuecomment-663729278), which is why the issue is still open. This occurs if a modifier is pressed after the remap has been invoked before releasing the remapped key and it is a harder scenario to solve which requires refactoring the single key remap code. ### UIPI Issues (not resolved) -`SendInput` does not work directly with certain key codes such as Play/Pause Media, Calculator key, etc as it requires UAC privileges to be injected to the OS and accordingly play the active media app or launch the Calculator app. In order to resolve this the correct approach is that the executable which calls `SendInput` needs to have the [UIAccess flag](https://docs.microsoft.com/en-us/windows/win32/winauto/uiauto-securityoverview) set to true, which will also avoid the requirement of KBM having to run as administrator to intercept key events when an elevated window is in focus. The UIAccess flag has many constraints such as it must be a signed executable and must be located in a protected path like Program Files. Since KBM currently runs out of the runner process, it would make more sense to do this work after KBM is moved to a separate executable, and it could be enabled by a separate toggle in settings only if PowerToys is installed in Program Files. [This comment](https://github.com/microsoft/PowerToys/issues/3192#issuecomment-646323661) has more details on this approach and (this)[https://github.com/microsoft/PowerToys/issues/3255] is the tracking issue. +`SendInput` does not work directly with certain key codes such as Play/Pause Media, Calculator key, etc as it requires UAC privileges to be injected to the OS and accordingly play the active media app or launch the Calculator app. In order to resolve this the correct approach is that the executable which calls `SendInput` needs to have the [UIAccess flag](https://learn.microsoft.com/windows/win32/winauto/uiauto-securityoverview) set to true, which will also avoid the requirement of KBM having to run as administrator to intercept key events when an elevated window is in focus. The UIAccess flag has many constraints such as it must be a signed executable and must be located in a protected path like Program Files. Since KBM currently runs out of the runner process, it would make more sense to do this work after KBM is moved to a separate executable, and it could be enabled by a separate toggle in settings only if PowerToys is installed in Program Files. [This comment](https://github.com/microsoft/PowerToys/issues/3192#issuecomment-646323661) has more details on this approach and (this)[https://github.com/microsoft/PowerToys/issues/3255] is the tracking issue. ## Other remapping approaches Other approaches for remapping which were deprioritized are: diff --git a/doc/devdocs/modules/keyboardmanager/keyboardmanagerui.md b/doc/devdocs/modules/keyboardmanager/keyboardmanagerui.md index bcd68f5d16..3542385029 100644 --- a/doc/devdocs/modules/keyboardmanager/keyboardmanagerui.md +++ b/doc/devdocs/modules/keyboardmanager/keyboardmanagerui.md @@ -28,7 +28,7 @@ The windows are [created as C++ windows](https://github.com/microsoft/PowerToys/ Once the UI controls are created, the parent container is set as the content for the `DesktopWindowXamlSource` and the `XamlBridge.MessageLoop` is executed. Messages are processed by the C++ window handler like [`EditKeyboardWindowProc`](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/ui/EditKeyboardWindow.cpp#L364-L404). The general structure we use for this is, for any `WM_PAINT` or `WM_SIZE` message we resize the Xaml Island window. For `WM_GETMINMAXINFO` we set minimum widths so that the window cannot be resized beyond a minimum height and width. This is done to prevent the WinUI elements from overlapping and getting cropped. If it is neither of these cases we send the message to the [`XamlBridge.MessageHandler`](https://github.com/microsoft/PowerToys/blob/b80578b1b9a4b24c9945bddac33c771204280107/src/modules/keyboardmanager/ui/XamlBridge.cpp#L291-L301) which handles Destroy, Activation and Focus. If `WM_NCDESTROY` is received when the `XamlBridge` is `nullptr`, the window thread is terminated. -**Note:** `ContentDialog` in Xaml Islands requires manually settings a `XamlRoot`. This can generally be done by passing the XamlRoot from a component in the main window, such as the button used to open the dialog ([`sender.as