FancyZones and Shortcut Guide initial commit

Co-authored-by: Alexis Campailla <alexis@janeasystems.com>
Co-authored-by: Bret Anderson <bretan@microsoft.com>
Co-authored-by: Enrico Giordani <enrico.giordani@gmail.com>
Co-authored-by: Jaime Bernardo <jaime@janeasystems.com>
Co-authored-by: Jeff Bogdan <jeffbog@microsoft.com>
Co-authored-by: March Rogers <marchr@microsoft.com>
Co-authored-by: Mike Harsh <mharsh@microsoft.com>
Co-authored-by: Nachum Bundak <Nachum.Bundak@microsoft.com>
Co-authored-by: Oliver Jones <ojones@microsoft.com>
Co-authored-by: Patrick Little <plittle@microsoft.com>

src/modules/example_powertoy/README.md

@@ -0,0 +1,22 @@
+# Example PowerToy
+
+# Introduction
+This PowerToy serves as a sample to show how to implement the [PowerToys interface](/src/modules/interface/) when creating a PowerToy. It also showcases the currently implemented settings.
+
+# Options
+This module has a setting to serve as an example for each of the currently implemented settings property:
+  - BoolToggle property
+  - IntSpinner property
+  - String property
+  - ColorPicker property
+  - CustomAction property
+
+![Image of the Options](/doc/images/example_powertoy/settings.png)
+
+# Code organization
+
+#### [`dllmain.cpp`](./dllmain.cpp)
+Contains DLL boilerplate code and implementation of the [PowerToys interface](/src/modules/interface/).
+
+#### [`trace.cpp`](./trace.cpp)
+Contains code for telemetry.

src/modules/example_powertoy/dllmain.cpp

@@ -0,0 +1,292 @@
+#include "pch.h"
+#include <interface/powertoy_module_interface.h>
+#include <interface/lowlevel_keyboard_event_data.h>
+#include <interface/win_hook_event_data.h>
+#include "trace.h"
+#include <common/settings_objects.h>
+
+extern "C" IMAGE_DOS_HEADER __ImageBase;
+
+BOOL APIENTRY DllMain(HMODULE hModule, DWORD  ul_reason_for_call, LPVOID lpReserved) {
+  switch (ul_reason_for_call) {
+  case DLL_PROCESS_ATTACH:
+    Trace::RegisterProvider();
+    break;
+  case DLL_THREAD_ATTACH:
+  case DLL_THREAD_DETACH:
+    break;
+  case DLL_PROCESS_DETACH:
+    Trace::UnregisterProvider();
+    break;
+  }
+  return TRUE;
+}
+
+// PowerToy sample settings.
+struct SampleSettings {
+  bool test_bool_prop = true;
+  int test_int_prop = 10;
+  std::wstring test_string_prop = L"The quick brown fox jumps over the lazy dog";
+  std::wstring test_color_prop = L"#1212FF";
+} g_settings;
+
+// Implement the PowerToy Module Interface and all the required methods.
+class ExamplePowertoy : public PowertoyModuleIface {
+private:
+  // The PowerToy state.
+  bool m_enabled = false;
+
+  // Load and save Settings.
+  void init_settings();
+  void save_settings();
+
+public:
+  // Constructor
+  ExamplePowertoy() {
+    init_settings();
+  };
+
+  // Destroy the powertoy and free memory
+  virtual void destroy() override {
+    delete this;
+  }
+
+  // Return the display name of the powertoy, this will be cached
+  virtual const wchar_t* get_name() override {
+    return L"Example Powertoy";
+  }
+
+  // Return array of the names of all events that this powertoy listens for, with
+  // nullptr as the last element of the array. Nullptr can also be retured for empty
+  // list.
+  // Right now there is only lowlevel keyboard hook event
+  virtual const wchar_t** get_events() override {
+    static const wchar_t* events[] = { ll_keyboard,
+                                       win_hook_event,
+                                       nullptr };
+    return events;
+  }
+
+  // Return JSON with the configuration options.
+  virtual bool get_config(wchar_t* buffer, int* buffer_size) override {
+    HINSTANCE hinstance = reinterpret_cast<HINSTANCE>(&__ImageBase);
+
+    // Create a Settings object.
+    PowerToysSettings::Settings settings(hinstance, get_name());
+    settings.set_description(L"Serves as an example powertoy, with example settings.");
+
+    // Show an overview link in the Settings page
+    settings.set_overview_link(L"https://github.com/microsoft/PowerToys");
+
+    // Show a video link in the Settings page.
+    settings.set_video_link(L"https://www.youtube.com/watch?v=d3LHo2yXKoY&t=21462");
+
+    // Add a bool property with a toggle editor.
+    settings.add_bool_toogle(
+      L"test_bool_toggle", // property name.
+      L"This is what a BoolToggle property looks like", // description or resource id of the localized string.
+      g_settings.test_bool_prop // property value.
+    );
+
+    // Add an integer property with a spinner editor.
+    settings.add_int_spinner(
+      L"test_int_spinner", // property name
+      L"This is what a IntSpinner property looks like", // description or resource id of the localized string.
+      g_settings.test_int_prop, // property value.
+      0, // min value.
+      100, // max value.
+      10 // incremental step.
+    );
+
+    // Add a string property with a textbox editor.
+    settings.add_string(
+      L"test_string_text", // property name.
+      L"This is what a String property looks like", // description or resource id of the localized string.
+      g_settings.test_string_prop // property value.
+    );
+
+    // Add a string property with a color picker editor.
+    settings.add_color_picker(
+      L"test_color_picker", // property name.
+      L"This is what a ColorPicker property looks like", // description or resource id of the localized string.
+      g_settings.test_color_prop // property value.
+    );
+
+    // Add a custom action property. When using this settings type, the "PowertoyModuleIface::call_custom_action()"
+    // method should be overriden as well.
+    settings.add_custom_action(
+      L"test_custom_action", // action name.
+      L"This is what a CustomAction property looks like", // label above the field.
+      L"Call a custom action", // button text.
+      L"Press the button to call a custom action in the Example PowerToy" // display values / extended info.
+    );
+
+    return settings.serialize_to_buffer(buffer, buffer_size);
+  }
+
+  // Signal from the Settings editor to call a custom action.
+  // This can be used to spawn more complex editors.
+  virtual void call_custom_action(const wchar_t* action) override {
+    static UINT custom_action_num_calls = 0;
+    try {
+      // Parse the action values, including name.
+      PowerToysSettings::CustomActionObject action_object =
+        PowerToysSettings::CustomActionObject::from_json_string(action);
+
+      if (action_object.get_name() == L"test_custom_action") {
+        // Custom action code to increase and show a counter.
+        ++custom_action_num_calls;
+        std::wstring msg(L"I have been called ");
+        msg += std::to_wstring(custom_action_num_calls);
+        msg += L" time(s).";
+        MessageBox(NULL, msg.c_str(), L"Custom action call.", MB_OK | MB_TOPMOST);
+      }
+    }
+    catch (std::exception ex) {
+      // Improper JSON.
+    }
+  }
+
+  // Called by the runner to pass the updated settings values as a serialized JSON.
+  virtual void set_config(const wchar_t* config) override { 
+    try {
+      // Parse the input JSON string.
+      PowerToysSettings::PowerToyValues values =
+        PowerToysSettings::PowerToyValues::from_json_string(config);
+
+      // Update the bool property.
+      if (values.is_bool_value(L"test_bool_toggle")) {
+        g_settings.test_bool_prop = values.get_bool_value(L"test_bool_toggle");
+      }
+
+      // Update the int property.
+      if (values.is_int_value(L"test_int_spinner")) {
+        g_settings.test_int_prop = values.get_int_value(L"test_int_spinner");
+      }
+
+      // Update the string property.
+      if (values.is_string_value(L"test_string_text")) {
+        g_settings.test_string_prop = values.get_string_value(L"test_string_text");
+      }
+
+      // Update the color property.
+      if (values.is_string_value(L"test_color_picker")) {
+        g_settings.test_color_prop = values.get_string_value(L"test_color_picker");
+      }
+
+      // If you don't need to do any custom processing of the settings, proceed
+      // to persists the values calling:
+      values.save_to_settings_file();
+      // Otherwise call a custom function to process the settings before saving them to disk:
+      // save_settings();
+    }
+    catch (std::exception ex) {
+      // Improper JSON.
+    }
+  }
+
+  // Enable the powertoy
+  virtual void enable() {
+    m_enabled = true;
+  }
+
+  // Disable the powertoy
+  virtual void disable() {
+    m_enabled = false;
+  }
+
+  // Returns if the powertoys is enabled
+  virtual bool is_enabled() override { 
+    return m_enabled;
+  }
+
+  // Handle incoming event, data is event-specific
+  virtual intptr_t signal_event(const wchar_t* name, intptr_t data)  override {
+    if (wcscmp(name, ll_keyboard) == 0) {
+      auto& event = *(reinterpret_cast<LowlevelKeyboardEvent*>(data));
+      // Return 1 if the keypress is to be suppressed (not forwarded to Windows),
+      // otherwise return 0.
+      return 0;
+    } else if (wcscmp(name, win_hook_event) == 0) {
+      auto& event = *(reinterpret_cast<WinHookEvent*>(data));
+      // Return value is ignored
+      return 0;
+    }
+    return 0;
+  }
+};
+
+// Load the settings file.
+void ExamplePowertoy::init_settings() {
+  try {
+    // Load and parse the settings file for this PowerToy.
+    PowerToysSettings::PowerToyValues settings =
+      PowerToysSettings::PowerToyValues::load_from_settings_file(get_name());
+
+    // Load the bool property.
+    if (settings.is_bool_value(L"test_bool_toggle")) {
+      g_settings.test_bool_prop = settings.get_bool_value(L"test_bool_toggle");
+    }
+
+    // Load the int property.
+    if (settings.is_int_value(L"test_int_spinner")) {
+      g_settings.test_int_prop = settings.get_int_value(L"test_int_spinner");
+    }
+
+    // Load the string property.
+    if (settings.is_string_value(L"test_string_text")) {
+      g_settings.test_string_prop = settings.get_string_value(L"test_string_text");
+    }
+
+    // Load the color property.
+    if (settings.is_string_value(L"test_color_picker")) {
+      g_settings.test_color_prop = settings.get_string_value(L"test_color_picker");
+    }
+  }
+  catch (std::exception ex) {
+    // Error while loading from the settings file. Let default values stay as they are.
+  }
+}
+
+// This method of saving the module settings is only required if you need to do any
+// custom processing of the settings before saving them to disk.
+void ExamplePowertoy::save_settings() {
+  try {
+    // Create a PowerToyValues object for this PowerToy
+    PowerToysSettings::PowerToyValues values(get_name());
+
+    // Save the bool property.
+    values.add_property(
+      L"test_bool_toggle", // property name
+      g_settings.test_bool_prop // property value
+    );
+
+    // Save the int property.
+    values.add_property(
+      L"test_int_spinner", // property name
+      g_settings.test_int_prop // property value
+    );
+
+    // Save the string property.
+    values.add_property(
+      L"test_string_text", // property name
+      g_settings.test_string_prop // property value
+    );
+
+    // Save the color property.
+    values.add_property(
+      L"test_color_picker", // property name
+      g_settings.test_color_prop // property value
+    );
+
+    // Save the PowerToyValues JSON to the power toy settings file.
+    values.save_to_settings_file();
+  }
+  catch (std::exception ex) {
+    // Couldn't save the settings.
+  }
+}
+
+extern "C" __declspec(dllexport) PowertoyModuleIface*  __cdecl powertoy_create() {
+  return new ExamplePowertoy();
+}

src/modules/example_powertoy/example_powertoy.vcxproj

@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <ItemGroup Label="ProjectConfigurations">
+    <ProjectConfiguration Include="Debug|x64">
+      <Configuration>Debug</Configuration>
+      <Platform>x64</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Release|x64">
+      <Configuration>Release</Configuration>
+      <Platform>x64</Platform>
+    </ProjectConfiguration>
+  </ItemGroup>
+  <PropertyGroup Label="Globals">
+    <VCProjectVersion>15.0</VCProjectVersion>
+    <ProjectGuid>{44CC9375-3E6E-4D99-8913-7FB748807EBD}</ProjectGuid>
+    <Keyword>Win32Proj</Keyword>
+    <RootNamespace>examplepowertoy</RootNamespace>
+    <WindowsTargetPlatformVersion>10.0</WindowsTargetPlatformVersion>
+  </PropertyGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'" Label="Configuration">
+    <ConfigurationType>DynamicLibrary</ConfigurationType>
+    <UseDebugLibraries>true</UseDebugLibraries>
+    <PlatformToolset>v142</PlatformToolset>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'" Label="Configuration">
+    <ConfigurationType>DynamicLibrary</ConfigurationType>
+    <UseDebugLibraries>false</UseDebugLibraries>
+    <PlatformToolset>v142</PlatformToolset>
+    <WholeProgramOptimization>true</WholeProgramOptimization>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+  <ImportGroup Label="ExtensionSettings">
+  </ImportGroup>
+  <ImportGroup Label="Shared">
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+  </ImportGroup>
+  <PropertyGroup Label="UserMacros" />
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
+    <LinkIncremental>true</LinkIncremental>
+    <OutDir>$(SolutionDir)$(Platform)\$(Configuration)\modules\</OutDir>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
+    <LinkIncremental>false</LinkIncremental>
+    <OutDir>$(SolutionDir)$(Platform)\$(Configuration)\modules\</OutDir>
+  </PropertyGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
+    <ClCompile>
+      <PrecompiledHeader>Use</PrecompiledHeader>
+      <WarningLevel>Level3</WarningLevel>
+      <Optimization>Disabled</Optimization>
+      <SDLCheck>true</SDLCheck>
+      <PreprocessorDefinitions>_DEBUG;EXAMPLEPOWERTOY_EXPORTS;_WINDOWS;_USRDLL;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <ConformanceMode>true</ConformanceMode>
+      <PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile>
+      <AdditionalIncludeDirectories>..\..\common\inc;..\..\common\Telemetry;..\;..\..\;..\..\..\deps\cpprestsdk\include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
+      <LanguageStandard>stdcpplatest</LanguageStandard>
+    </ClCompile>
+    <Link>
+      <SubSystem>Windows</SubSystem>
+      <GenerateDebugInformation>true</GenerateDebugInformation>
+      <OutputFile>$(OutDir)$(TargetName)$(TargetExt)</OutputFile>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
+    <ClCompile>
+      <PrecompiledHeader>Use</PrecompiledHeader>
+      <WarningLevel>Level3</WarningLevel>
+      <Optimization>MaxSpeed</Optimization>
+      <FunctionLevelLinking>true</FunctionLevelLinking>
+      <IntrinsicFunctions>true</IntrinsicFunctions>
+      <SDLCheck>true</SDLCheck>
+      <PreprocessorDefinitions>NDEBUG;EXAMPLEPOWERTOY_EXPORTS;_WINDOWS;_USRDLL;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <ConformanceMode>true</ConformanceMode>
+      <PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile>
+      <AdditionalIncludeDirectories>..\..\common\inc;..\..\common\Telemetry;..\;..\..\;..\..\..\deps\cpprestsdk\include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
+      <LanguageStandard>stdcpplatest</LanguageStandard>
+    </ClCompile>
+    <Link>
+      <SubSystem>Windows</SubSystem>
+      <EnableCOMDATFolding>true</EnableCOMDATFolding>
+      <OptimizeReferences>true</OptimizeReferences>
+      <GenerateDebugInformation>true</GenerateDebugInformation>
+      <OutputFile>$(OutDir)$(TargetName)$(TargetExt)</OutputFile>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemGroup>
+    <ClInclude Include="pch.h" />
+    <ClInclude Include="resource.h" />
+    <ClInclude Include="trace.h" />
+  </ItemGroup>
+  <ItemGroup>
+    <ClCompile Include="dllmain.cpp" />
+    <ClCompile Include="pch.cpp">
+      <PrecompiledHeader Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">Create</PrecompiledHeader>
+      <PrecompiledHeader Condition="'$(Configuration)|$(Platform)'=='Release|x64'">Create</PrecompiledHeader>
+      <PrecompiledHeaderFile Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">pch.h</PrecompiledHeaderFile>
+      <PrecompiledHeaderFile Condition="'$(Configuration)|$(Platform)'=='Release|x64'">pch.h</PrecompiledHeaderFile>
+    </ClCompile>
+    <ClCompile Include="trace.cpp" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\common\common.vcxproj">
+      <Project>{74485049-c722-400f-abe5-86ac52d929b3}</Project>
+    </ProjectReference>
+  </ItemGroup>
+  <ItemGroup>
+    <ResourceCompile Include="example_powertoy.rc" />
+  </ItemGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
+  <ImportGroup Label="ExtensionTargets">
+  </ImportGroup>
+</Project>

src/modules/example_powertoy/example_powertoy.vcxproj.filters

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <ItemGroup>
+    <ClCompile Include="pch.cpp" />
+    <ClCompile Include="dllmain.cpp" />
+    <ClCompile Include="trace.cpp" />
+  </ItemGroup>
+  <ItemGroup>
+    <ClInclude Include="pch.h" />
+    <ClInclude Include="trace.h" />
+    <ClInclude Include="resource.h" />
+  </ItemGroup>
+  <ItemGroup>
+    <ResourceCompile Include="example_powertoy.rc" />
+  </ItemGroup>
+</Project>

src/modules/example_powertoy/pch.cpp

@@ -0,0 +1,2 @@
+#include "pch.h"
+#pragma comment(lib, "windowsapp")

src/modules/example_powertoy/pch.h

@@ -0,0 +1,5 @@
+#pragma once
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <common/common.h>
+#include <ProjectTelemetry.h>

src/modules/example_powertoy/trace.cpp

@@ -0,0 +1,26 @@
+#include "pch.h"
+#include "trace.h"
+
+TRACELOGGING_DEFINE_PROVIDER(
+  g_hProvider,
+  "Microsoft.PowerToys",
+  // {38e8889b-9731-53f5-e901-e8a7c1753074}
+  (0x38e8889b, 0x9731, 0x53f5, 0xe9, 0x01, 0xe8, 0xa7, 0xc1, 0x75, 0x30, 0x74),
+  TraceLoggingOptionProjectTelemetry());
+
+void Trace::RegisterProvider() {
+  TraceLoggingRegister(g_hProvider);
+}
+
+void Trace::UnregisterProvider() {
+  TraceLoggingUnregister(g_hProvider);
+}
+
+void Trace::MyEvent() {
+  TraceLoggingWrite(
+    g_hProvider,
+    "PowerToyName::Event::MyEvent",
+    ProjectTelemetryPrivacyDataTag(ProjectTelemetryTag_ProductAndServicePerformance),
+    TraceLoggingBoolean(TRUE, "UTCReplace_AppSessionGuid"),
+    TraceLoggingKeyword(PROJECT_KEYWORD_MEASURE));
+}

src/modules/example_powertoy/trace.h

@@ -0,0 +1,8 @@
+#pragma once
+
+class Trace {
+public:
+  static void RegisterProvider();
+  static void UnregisterProvider();
+  static void MyEvent();
+};