Devdocs reorganisation (#913)

* docs: split usage and dev docs * # This is a combination of 2 commits. # This is the 1st commit message: docs: split usage and dev docs # The commit message #2 will be skipped: # fixup add docs * docs: add runner documentation and move hooks documentation to devdocs * docs: add stubs for modules technical description * docs: add paragraph about event thread-safety * docs: add 'Current modules' section header
2025-12-15 19:27:56 +01:00 · 2019-12-12 12:25:19 +03:00
parent c31262b97e
commit f385e46927
20 changed files with 432 additions and 348 deletions
--- a/doc/devdocs/common.md
+++ b/doc/devdocs/common.md
@@ -0,0 +1,45 @@
+# Classes and structures
+
+#### class Animation: [header](/src/common/animation.h) [source](/src/common/animation.cpp)
+Animation helper class with two easing-in animations: linear and exponential.
+
+#### class AsyncMessageQueue: [header](/src/common/async_message_queue.h)
+Header-only asynchronous message queue. Used by `TwoWayPipeMessageIPC`.
+
+#### class TwoWayPipeMessageIPC: [header](/src/common/two_way_pipe_message_ipc.h)
+Header-only asynchronous IPC messaging class. Used by the runner to communicate with the settings window.
+
+#### class D2DSVG: [header](/src/common/d2d_svg.h) [source](/src/common/d2d_svg.cpp)
+Class for loading, rendering and for some basic modifications of SVG graphics.
+
+#### class D2DText: [header](/src/common/d2d_text.h) [source](/src/common/d2d_text.cpp)
+Class for rendering text using DirectX.
+
+#### class D2DWindow: [header](/src/common/d2d_window.h) [source](/src/common/d2d_window.cpp)
+Base class for creating borderless windows, with DirectX enabled rendering pipeline.
+
+#### class DPIAware: [header](/src/common/dpi_aware.h) [source](/src/common/dpi_aware.cpp)
+Helper class for creating DPI-aware applications.
+
+#### struct MonitorInfo: [header](/src/common/monitors.h) [source](/src/common/monitors.cpp)
+Class for obtaining information about physical displays connected to the machine.
+
+#### class Settings, class PowerToyValues, class CustomActionObject: [header](/src/common/settings_objects.h) [source](/src/common/settings_objects.cpp)
+Classes used to define settings screens for the PowerToys modules.
+
+#### class Tasklist: [header](/src/common/tasklist_positions.h) [source](/src/common/tasklist_positions.cpp)
+Class that can detect the position of the windows buttons on the taskbar. It also detects which window will react to pressing `WinKey + number`.
+
+#### struct WindowsColors: [header](/src/common/windows_colors.h) [source](/src/common/windows_colors.cpp)
+Class for detecting the current Windows color scheme.
+
+# Helpers
+
+#### Common helpers: [header](/src/common/common.h) [source](/src/common/common.cpp)
+Various helper functions.
+
+#### Settings helpers: [header](/src/common/settings_helpers.h)
+Helper methods for the settings.
+
+#### Start visible helper: [header](/src/common/start_visible.h) [source](/src/common/start_visible.cpp)
+Contains function to test if the Start menu is visible.
--- a/doc/devdocs/modules/example_powertoy.md
+++ b/doc/devdocs/modules/example_powertoy.md
@@ -0,0 +1,5 @@
+#### [`dllmain.cpp`](/src/modules/example_powertoy/dllmain.cpp)
+Contains DLL boilerplate code and implementation of the [PowerToys interface](/src/modules/interface/).
+
+#### [`trace.cpp`](/src/modules/example_powertoy/trace.cpp)
+Contains code for telemetry.
--- a/doc/devdocs/modules/fancyzones.md
+++ b/doc/devdocs/modules/fancyzones.md
@@ -0,0 +1,85 @@
+## FancyZones Lib
+
+#### [`FancyZones.cpp`](/src/modules/fancyzones/lib/FancyZones.cpp)
+TODO
+
+#### [`Settings.cpp`](/src/modules/fancyzones/lib/Settings.cpp)
+TODO
+
+#### [`trace.cpp`](/src/modules/fancyzones/lib/trace.cpp)
+TODO
+
+#### [`Zone.cpp`](/src/modules/fancyzones/lib/Zone.cpp)
+TODO
+
+#### [`ZoneSet.cpp`](/src/modules/fancyzones/lib/ZoneSet.cpp)
+TODO
+
+#### [`ZoneWindow.cpp`](/src/modules/fancyzones/lib/ZoneWindow.cpp)
+TODO
+
+## FancyZones Editor
+
+#### [`App.xaml.cs`](/src/modules/fancyzones/editor/App.xaml.cs)
+TODO
+
+#### [`Properties\AssemblyInfo.cs`](/src/modules/fancyzones/editor/Properties\AssemblyInfo.cs)
+TODO
+
+#### [`CanvasEditor.xaml.cs`](/src/modules/fancyzones/editor/CanvasEditor.xaml.cs)
+TODO
+
+#### [`CanvasEditorWindow.xaml.cs`](/src/modules/fancyzones/editor/CanvasEditorWindow.xaml.cs)
+TODO
+
+#### [`Models\CanvasLayoutModel.cs`](/src/modules/fancyzones/editor/Models\CanvasLayoutModel.cs)
+TODO
+
+#### [`CanvasZone.xaml.cs`](/src/modules/fancyzones/editor/CanvasZone.xaml.cs)
+TODO
+
+#### [`EditorOverlay.xaml.cs`](/src/modules/fancyzones/editor/EditorOverlay.xaml.cs)
+TODO
+
+#### [`EditorWindow.cs`](/src/modules/fancyzones/editor/EditorWindow.cs)
+TODO
+
+#### [`GridEditor.xaml.cs`](/src/modules/fancyzones/editor/GridEditor.xaml.cs)
+TODO
+
+#### [`GridEditorWindow.xaml.cs`](/src/modules/fancyzones/editor/GridEditorWindow.xaml.cs)
+TODO
+
+#### [`Models\GridLayoutModel.cs`](/src/modules/fancyzones/editor/Models\GridLayoutModel.cs)
+TODO
+
+#### [`GridResizer.xaml.cs`](/src/modules/fancyzones/editor/GridResizer.xaml.cs)
+TODO
+
+#### [`GridZone.xaml.cs`](/src/modules/fancyzones/editor/GridZone.xaml.cs)
+TODO
+
+#### [`Models\LayoutModel.cs`](/src/modules/fancyzones/editor/Models/LayoutModel.cs)
+TODO
+
+#### [`LayoutPreview.xaml.cs`](/src/modules/fancyzones/editor/LayoutPreview.xaml.cs)
+TODO
+
+#### [`MainWindow.xaml.cs`](/src/modules/fancyzones/editor/MainWindow.xaml.cs)
+TODO
+
+#### [`Properties\Resources.Designer.cs`](/src/modules/fancyzones/editor/Properties/Resources.Designer.cs)
+TODO
+
+#### [`RowColInfo.cs`](/src/modules/fancyzones/editor/RowColInfo.cs)
+TODO
+
+#### [`Models\Settings.cs`](/src/modules/fancyzones/editor/Models/Settings.cs)
+TODO
+
+#### [`Properties\Settings.Designer.cs`](/src/modules/fancyzones/editor/Properties/Settings.Designer.cs)
+TODO
+
+#### [`WindowLayout.xaml.cs`](/src/modules/fancyzones/editor/WindowLayout.xaml.cs)
+TODO
+
--- a/doc/devdocs/modules/interface.md
+++ b/doc/devdocs/modules/interface.md
@@ -0,0 +1,407 @@
+# Interface definition
+
+```cpp
+class PowertoyModuleIface {
+public:
+  virtual const wchar_t* get_name() = 0;
+  virtual const wchar_t** get_events() = 0;
+  virtual bool get_config(wchar_t* buffer, int *buffer_size) = 0;
+  virtual void set_config(const wchar_t* config) = 0;
+  virtual void call_custom_action(const wchar_t* action) {};
+  virtual void enable() = 0;
+  virtual void disable() = 0;
+  virtual bool is_enabled() = 0;
+  virtual intptr_t signal_event(const wchar_t* name, intptr_t data) = 0;
+  virtual void register_system_menu_helper(PowertoySystemMenuIface* helper) = 0;
+  virtual void signal_system_menu_action(const wchar_t* name) = 0;
+  virtual void destroy() = 0;
+};
+
+typedef PowertoyModuleIface* (__cdecl *powertoy_create_func)();
+```
+
+# Runtime logic
+
+The PowerToys runner will, for each PowerToy DLL:
+  - load the DLL,
+  - call [`powertoy_create()`](#powertoy_create_func) to create the PowerToy.
+
+On the received object, the runner will call:
+  - [`get_name()`](#get_name) to get the name of the PowerToy,
+  - [`get_events()`](#get_events) to get the list of the events the PowerToy wants to subscribe to,
+  - [`enable()`](#enable) to initialize the PowerToy.
+
+While running, the runner might call the following methods between create_powertoy()
+and destroy():
+  - [`disable()`](#disable)/[`enable()`](#enable)/[`is_enabled()`](#is_enabled) to change or get the PowerToy's enabled state,
+  - [`get_config()`](#get_config) to get the available configuration settings,
+  - [`set_config()`](#set_config) to set settings after they have been edited in the Settings editor,
+  - [`call_custom_action()`](#call_custom_action) when the user selects a custom action in the Settings editor,
+  - [`signal_event()`](#signal_event) to send an event the PowerToy registered to.
+  - [`register_system_menu_helper()`](#register_system_menu_helper) to pass object, responsible for handling customized system menus, to module.
+  - [`signal_system_menu_action()`](#signal_system_menu_action) to send an event when action is taken on system menu item.
+
+When terminating, the runner will:
+  - call [`disable()`](#disable),
+  - call [`destroy()`](#destroy) which should free all the memory and delete the PowerToy object,
+  - unload the DLL.
+
+
+## Method definition
+
+This section contains a more detailed description of each of the interface methods.
+
+### powertoy_create_func
+
+```cpp
+typedef PowertoyModuleIface* (__cdecl *powertoy_create_func)()
+```
+
+Typedef of the factory function that creates the PowerToy object.
+Must be exported by the DLL as `powertoy_create()`.
+
+Called by the PowerToys runner to initialize each PowerToy.
+It will be called only once before a call to [`destroy()`](#destroy) is made.
+
+The returned PowerToy should be in the disabled state. The runner will call the [`enable()`](#enable) method to start the PowerToy.
+
+In case of errors returns `nullptr`.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+extern "C" __declspec(dllexport) PowertoyModuleIface*  __cdecl powertoy_create() {
+  return new ExamplePowertoy();
+}
+
+ExamplePowertoy::ExamplePowertoy() {
+  init_settings();
+}
+```
+
+### get_name
+
+```cpp
+virtual const wchar_t* get_name()
+```
+
+Returns the name of the PowerToy, it will be cached by the runner.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+```cpp
+  virtual const wchar_t* get_name() override {
+    return L"Example Powertoy";
+  }
+```
+
+### get_events
+
+```cpp
+virtual const wchar_t** get_events()
+```
+
+Returns a null-terminated table of the names of the events the PowerToy wants to subscribe to. Available events:
+  * ll_keyboard
+  * win_hook_event
+
+A nullptr can be returned to signal that the PowerToy does not want to subscribe to any event.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  virtual const wchar_t** get_events() override {
+    static const wchar_t* events[] = { ll_keyboard,
+                                       win_hook_event,
+                                       nullptr };
+    return events;
+  }
+```
+
+### get_config
+
+```
+virtual bool get_config(wchar_t* buffer, int *buffer_size)
+```
+
+Fills a buffer with the available configuration settings.
+
+If `buffer` is a null pointer or the buffer size is not large enough sets the required buffer size in 'buffer_size' and return false.
+
+Returns true if successful.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  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.");
+
+    // Add an overview link to show in the Settings.
+    settings.set_overview_link(L"https://github.com/microsoft/PowerToys");
+
+    // Add a video link to show in the Settings.
+    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.
+      test_bool_prop // property value.
+    );
+
+// More settings
+...
+
+    // Add a custom action property. When using this settings type, the "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);
+  }
+```
+
+### set_config
+
+```cpp
+virtual void set_config(const wchar_t* config)
+```
+
+After the user has changed the module settings in the Settings editor, the runner calls this method to pass to the module the updated values. It's a good place to save the settings as well.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  virtual void set_config(const wchar_t* config) override {
+    try {
+      // Parse the PowerToysValues object from the received json string.
+      PowerToysSettings::PowerToyValues _values =
+        PowerToysSettings::PowerToyValues::from_json_string(config);
+
+      // Update the bool property.
+      if (_values.is_bool_value(L"test bool_toggle")) {
+        test_bool_prop = _values.get_bool_value(L"test bool_toggle");
+      }
+
+// More settings
+...
+
+      save_settings();
+    }
+    catch (std::exception ex) {
+      // Improper JSON.
+    }
+  }
+```
+
+### call_custom_action
+
+```cpp
+  virtual void call_custom_action(const wchar_t* action)
+```
+
+Calls a custom action in response to the user pressing the custom action button in the Settings editor.
+This can be used to spawn custom editors defined by the PowerToy.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  virtual void call_custom_action(const wchar_t* action) override {
+    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.
+        ++this->test_custom_action_num_calls;
+        std::wstring msg(L"I have been called ");
+        msg += std::to_wstring(this->test_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.
+    }
+  }
+```
+
+### enable
+
+```cpp
+  virtual void enable()
+```
+
+Enables the PowerToy.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  virtual void enable() {
+    m_enabled = true;
+  }
+```
+
+### disable
+
+```cpp
+  virtual void disable()
+```
+
+Disables the PowerToy, should free as much memory as possible.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  virtual void disable() {
+    m_enabled = false;
+  }
+```
+
+### is_enabled
+
+```cpp
+  virtual bool is_enabled() = 0;
+```
+
+Returns the PowerToy state.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  virtual bool is_enabled() override {
+    return m_enabled;
+  }
+```
+### signal_event
+
+```cpp
+  virtual intptr_t signal_event(const wchar_t* name, intptr_t data) = 0;
+```
+
+Handle event. Only the events the PowerToy subscribed to will be signaled.
+The data argument and return value meaning are event-specific:
+  * ll_keyboard: see [`lowlevel_keyboard_event_data.h`](./lowlevel_keyboard_event_data.h).
+  * win_hook_event: see [`win_hook_event_data.h`](./win_hook_event_data.h)
+
+Please note that some of the events are currently being signalled from a separate thread.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  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;
+  }
+```
+
+## register_system_menu_helper
+
+```cpp
+  virtual void register_system_menu_helper(PowertoySystemMenuIface* helper) = 0;
+```
+
+Register helper class to handle all system menu items related actions. Creation, deletion
+and all other actions taken on system menu item will be handled by provided class.
+Module will be informed when action is taken on any item created on request of the module.
+
+## signal_system_menu_action
+
+```cpp
+  virtual void signal_system_menu_action(const wchar_t* name) = 0;
+```
+
+Runner invokes this API when action is taken on item created on request from the module.
+Item name is passed as an argument, so that module can distinguish between different menu items.
+
+### destroy
+
+```cpp
+  virtual void destroy()
+```
+Destroy the PowerToy and free all memory.
+
+Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
+
+```cpp
+  virtual void destroy() override {
+    delete this;
+  }
+```
+
+## Powertoys system menu helper interface
+
+Interface for helper class responsible for handling all system menu related actions.
+```cpp
+class PowertoySystemMenuIface {
+public:
+  struct ItemInfo {
+    std::wstring name{};
+    bool enable{ false };
+    bool checkBox{ false };
+  };
+  virtual void SetConfiguration(PowertoyModuleIface* module, const std::vector<ItemInfo>& config) = 0;
+  virtual void ProcessSelectedItem(PowertoyModuleIface* module, HWND window, const wchar_t* itemName) = 0;
+};
+```
+
+## ItemInfo
+
+```cpp
+  struct ItemInfo {
+    std::wstring name{};
+    bool enable{ false };
+    bool checkBox{ false };
+  };
+```
+
+Structure containing all relevant information for system menu item: name (and hotkey if available), item
+status at creation (enabled/disabled) and whether check box will appear next to item name when action is taken.
+
+## SetConfiguration
+
+```cpp
+  virtual void SetConfiguration(PowertoyModuleIface* module, const std::vector<ItemInfo>& config) = 0;
+```
+
+Module should use this interface to inform system menu helper class which custom system menu items to create.
+
+## ProcessSelectedItem
+
+```cpp
+  virtual void ProcessSelectedItem(PowertoyModuleIface* module, HWND window, const wchar_t* itemName) = 0;
+```
+
+Process action taken on specific system menu item.
+
+# Code organization
+
+### [`powertoy_module_interface.h`](/src/modules/example_powertoy/powertoy_module_interface.h)
+Contains the PowerToys interface definition.
+
+### [`powertoy_system_menu.h`](/src/modules/example_powertoy/powertoy_system_module.h)
+Contains the PowerToys system menu helper interface definition.
+
+### [`lowlevel_keyboard_event_data.h`](/src/modules/example_powertoy/lowlevel_keyboard_event_data.h)
+Contains the `LowlevelKeyboardEvent` structure that's passed to `signal_event` for `ll_keyboard` events.
+
+### [`win_hook_event_data.h`](/src/modules/example_powertoy/win_hook_event_data.h)
+Contains the `WinHookEvent` structure that's passed to `signal_event` for `win_hook_event` events.
+
--- a/doc/devdocs/modules/powerrename.md
+++ b/doc/devdocs/modules/powerrename.md
@@ -0,0 +1,26 @@
+#### [`dllmain.cpp`](/src/modules/powerrename/dll/dllmain.cpp)
+TODO
+
+#### [`PowerRenameExt.cpp`](/src/modules/powerrename/dll/PowerRenameExt.cpp)
+TODO
+
+#### [`Helpers.cpp`](/src/modules/powerrename/lib/Helpers.cpp)
+TODO
+
+#### [`PowerRenameItem.cpp`](/src/modules/powerrename/lib/PowerRenameItem.cpp)
+TODO
+
+#### [`PowerRenameManager.cpp`](/src/modules/powerrename/lib/PowerRenameManager.cpp)
+TODO
+
+#### [`PowerRenameRegEx.cpp`](/src/modules/powerrename/lib/PowerRenameRegEx.cpp)
+TODO
+
+#### [`Settings.cpp`](/src/modules/powerrename/lib/Settings.cpp)
+TODO
+
+#### [`trace.cpp`](/src/modules/powerrename/lib/trace.cpp)
+TODO
+
+#### [`PowerRenameUI.cpp`](/src/modules/powerrename/ui/PowerRenameUI.cpp)
+TODO
--- a/doc/devdocs/modules/shortcut_guide.md
+++ b/doc/devdocs/modules/shortcut_guide.md
@@ -0,0 +1,17 @@
+#### [`dllmain.cpp`](/src/modules/shortcut_guide/dllmain.cpp)
+Contains DLL boilerplate code.
+
+#### [`shortcut_guide.cpp`](/src/modules/shortcut_guide/shortcut_guide.cpp)
+Contains the module interface code. It initializes the settings values and the keyboard event listener.
+
+#### [`overlay_window.cpp`](/src/modules/shortcut_guide/overlay_window.cpp)
+Contains the code for loading the SVGs, creating and rendering of the overlay window.
+
+#### [`keyboard_state.cpp`](/src/modules/shortcut_guide/keyboard_state.cpp)
+Contains helper methods for checking the current state of the keyboard.
+
+#### [`target_state.cpp`](/src/modules/shortcut_guide/target_state.cpp)
+State machine that handles the keyboard events. It’s responsible for deciding when to show the overlay, when to suppress the Start menu (if the overlay is displayed long enough), etc.
+
+#### [`trace.cpp`](/src/modules/shortcut_guide/trace.cpp)
+Contains code for telemetry.
--- a/doc/devdocs/readme.md
+++ b/doc/devdocs/readme.md
@@ -0,0 +1,79 @@
+# Code Organization
+
+## Rules
+
+- **Follow the pattern of what you already see in the code**
+- Try to package new ideas/components into libraries that have nicely defined interfaces
+- Package new ideas into classes or refactor existing ideas into a class as you extend
+
+## Code Overview
+
+General project organization:
+
+#### The [`doc`](/doc) folder
+Documentation for the project, including a [coding guide](/doc/coding) and [design docs](/doc/specs).
+
+#### The [`installer`](/installer) folder
+Contains the source code of the PowerToys installer.
+
+#### The [`src`](/src) folder
+Contains the source code of the PowerToys runner and of all of the PowerToys modules. **This is where the most of the magic happens.**
+
+#### The [`tools`](/tools) folder
+Various tools used by PowerToys. Includes the Visual Studio 2019 project template for new PowerToys.
+
+# Implementation details
+
+### [`Runner`](/doc/devdocs/runner.md)
+The PowerToys Runner contains the project for the PowerToys.exe executable.
+It's responsible for:
+- Loading the individual PowerToys modules.
+- Passing registered events to the PowerToys.
+- Showing a system tray icon to manage the PowerToys.
+- Bridging between the PowerToys modules and the Settings editor.
+
+![Image of the tray icon](/doc/images/runner/tray.png)
+
+### [`Interface`](/doc/devdocs/modules/interface.md)
+Definition of the interface used by the [`runner`](/src/runner) to manage the PowerToys. All PowerToys must implement this interface.
+
+### [`Common`](/doc/devdocs/common.md)
+The common lib, as the name suggests, contains code shared by multiple PowerToys components and modules, e.g. [json parsing](/src/common/json.h) and [IPC primitives](/src/common/two_way_pipe_message_ipc.h).
+
+
+### [`Settings`](/doc/devdocs/settings.md)
+WebView project for editing the PowerToys settings.
+
+The html portion of the project that is shown in the WebView is contained in [`settings-html`](/src/settings/settings-heml).
+Instructions on how build a new version and update this project are in the [Web project for the Settings UI](./settings-web.md).
+
+While developing, it's possible to connect the WebView to the development server running in localhost by setting the `_DEBUG_WITH_LOCALHOST` flag to `1` and following the instructions near it in `./main.cpp`.
+
+### [`Settings-web`](/doc/devdocs/settings-web.md)
+This project generates the web UI shown in the [PowerToys Settings](/src/editor).
+It's a `ReactJS` project created using [UI Fabric](https://developer.microsoft.com/en-us/fabric#/).
+
+## Current modules
+### [`FancyZones`](/doc/devdocs/modules/fancyzones.md)
+The FancyZones PowerToy that allows users to create custom zones on the screen, to which the windows will snap when moved.
+
+### [`PowerRename`](/doc/devdocs/modules/powerrename.md)
+PowerRename is a Windows Shell Context Menu Extension for advanced bulk renaming using simple search and replace or more powerful regular expression matching.
+
+### [`Shortcut Guide`](/doc/devdocs/modules/shortcut_guide.md)
+The Windows Shortcut Guide, displayed when the WinKey is held for some time.
+
+### _obsolete_ [`example_powertoy`](/doc/devdocs/modules/example_powertoy.md)
+An example PowerToy, that demonstrates how to create new ones. Please note, that this is going to become a Visual Studio project template soon.
+
+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)
--- a/doc/devdocs/runner.md
+++ b/doc/devdocs/runner.md
@@ -0,0 +1,36 @@
+#### [`main.cpp`](/src/runner/main.cpp)
+Contains the executable starting point, initialization code and the list of known PowerToys. All singletones are also initialized here at the start. Loads all the powertoys by scanning the `./modules` folder and `enable()`s those makred as enabled in `%LOCALAPPDATA%\Microsoft\PowerToys\settings.json` config. Then it runs [a message loop](https://docs.microsoft.com/en-us/windows/win32/winmsg/using-messages-and-message-queues) for the tray UI. Note that this message loop also [handles lowlevel_keyboard_hook events](https://github.com/microsoft/PowerToys/blob/1760af50c8803588cb575167baae0439af38a9c1/src/runner/lowlevel_keyboard_event.cpp#L24).
+
+#### [`general_settings.cpp`](./general_settings.cpp)
+#### [`powertoy_module.h`](/src/runner/powertoy_module.h) and [`powertoy_module.cpp`](/src/runner/powertoy_module.cpp)
+Contains code for initializing and managing the PowerToy modules. `PowertoyModule` is a RAII-style holder for the `PowertoyModuleIface` pointer, which we got by [invoking module DLL's `powertoy_create` function](https://github.com/microsoft/PowerToys/blob/1760af50c8803588cb575167baae0439af38a9c1/src/runner/powertoy_module.cpp#L13-L24).
+
+#### [`powertoys_events.cpp`](/src/runner/powertoys_events.cpp)
+Contains code that handles the various events listeners, and forwards those events to the PowerToys modules. You can learn more about the current event architecture [here](/doc/devdocs/shared-hooks.md).
+
+#### [`lowlevel_keyboard_event.cpp`](/src/runner/lowlevel_keyboard_event.cpp)
+Contains code for registering the low level keyboard event hook that listens for keyboard events. Please note that `signal_event` is called from the main thread for this event.
+
+#### [`win_hook_event.cpp`](/src/runner/win_hook_event.cpp)
+Contains code for registering a Windows event hook through `SetWinEventHook`, that listens for various events raised when a window is interacted with. Please note, that `signal_event` is called from a separate `dispatch_thread_proc` worker thread, so you must provide thread-safety for your `signal_event` if you intend to receive it. This is a subject to change.
+
+#### [`tray_icon.cpp`](/src/runner/tray_icon.cpp)
+Contains code for managing the PowerToys tray icon and its menu commands. Note that `dispatch_run_on_main_ui_thread` is used to 
+transfer received json message from the [Settings window](/doc/devdocs/settings.md) to the main thread, since we're communicating with it from [a dedicated thread](https://github.com/microsoft/PowerToys/blob/7357e40d3f54de51176efe54fda6d57028837b8c/src/runner/settings_window.cpp#L267-L271).
+#### [`settings_window.cpp`](/src/runner/settings_window.cpp)
+Contains code for starting the PowerToys settings window and communicating with it. Settings window is a separate process, so we're using [Windows pipes](https://docs.microsoft.com/en-us/windows/win32/ipc/pipes) as a transport for json messages.
+
+#### [`general_settings.cpp`](/src/runner/general_settings.cpp)
+Contains code for loading, saving and applying the general setings.
+
+#### [`auto_start_helper.cpp`](/src/runner/auto_start_helper.cpp)
+Contains helper code for registering and unregistering PowerToys to run when the user logs in.
+
+#### [`unhandled_exception_handler.cpp`](/src/runner/unhandled_exception_handler.cpp)
+Contains helper code to get stack traces in builds. Can be used by adding a call to `init_global_error_handlers` in [`WinMain`](./main.cpp).
+
+#### [`trace.cpp`](/src/runner/trace.cpp)
+Contains code for telemetry.
+
+#### [`svgs`](/src/runner/svgs/)
+Contains the SVG assets used by the PowerToys modules.
--- a/doc/devdocs/settings-web.md
+++ b/doc/devdocs/settings-web.md
@@ -0,0 +1,179 @@
+## Build Commands
+
+Here are the commands to build and test this project:
+
+### To start the development server
+
+```
+npm install
+npm run start
+```
+
+### Building and integrating into PowerToys settings project
+
+```
+npm run build
+```
+
+## Updating the icons
+
+Icons inside [`src/icons/`](/src/settings-web/src/icons/) were generated from the [Office UI Fabric Icons subset generation tool.](https://uifabricicons.azurewebsites.net/)
+
+In case the subset needs to be changed, additional steps are needed to include the icon font in the built `dist/bundle.js`:
+- Copy the inline font data taken from [`src/icons/css/fabric-icons-inline.css`](src/icons/css/fabric-icons-inline.css) and place it in the `fontFace` `src` value in [`src/icons/src/fabric-icons.ts`](src/icons/src/fabric-icons.ts).
+
+A list of the current icons in the subset can be seen in the `icons` object in [`src/icons/src/fabric-icons.ts`](src/icons/src/fabric-icons.ts).
+
+SVG icons, including the icons for each PowerToy listed in the Settings, are contained in [`src/svg/`](src/svg/). To add additional SVG icons add them to [`src/svg/`](src/svg/) and register them in [`src/setup_icons.tsx`](src/setup_icons.tsx).
+
+## Code Structure
+
+The project structure is based on the [`UI Fabric` scaffold](https://developer.microsoft.com/en-us/fabric#/get-started/web#option-1-quick-start) obtained by initializing it with `npm init uifabric`.
+
+#### [index.html](/src/settings-web/index.html)
+The HTML entry-point of the project.
+Loads the `ReactJS` distribution script.
+Defines JavaScript functions to receive and send messages to the [PowerToys Settings](/src/editor) window.
+
+#### [src/index.tsx](/src/settings-web/src/index.tsx)
+Main `ReactJS` entrypoint, initializing the `ReactDOM`.
+
+#### [src/setup_icons.tsx](/src/settings-web/src/setup_icons.tsx)
+Defines the `setup_powertoys_icons` function that registers the icons to be used in the components.
+
+#### [src/components/](/src/settings-web/src/components/)
+Contains the `ReactJS` components, including the Settings controls for each type of setting.
+
+#### [src/components/App.tsx](/src/settings-web/src/components/App.tsx)
+Defines the main App component, containing the UI layout, navigation menu, dialogs and main load/save logic.
+
+#### [src/components/GeneralSettings.tsx](/src/settings-web/src/components/GeneralSettings.tsx)
+Defines the PowerToys General Settings component, including logic to construct the object sent to PowerToys to change the General settings.
+
+#### [src/components/ModuleSettings.tsx](/src/settings-web/src/components/ModuleSettings.tsx)
+Defines the component that generates the settings screen for a PowerToy depending on its settings definition.
+
+#### [src/components/BaseSettingsControl.tsx](/src/settings-web/src/components/BaseSettingsControl.tsx)
+Defines the base class for a Settings control.
+
+#### [src/css/layout.css](/src/settings-web/src/css/layout.css)
+General layout styles.
+
+#### [src/icons/](/src/settings-web/src/icons/)
+Icons generated from the [Office UI Fabric Icons subset generation tool.](https://uifabricicons.azurewebsites.net/)
+
+#### [src/svg/](/src/settings-web/src/svg/)
+SVG icon assets.
+
+## Creating a new settings control
+
+The [`BaseSettingsControl` class](/src/settings-web/src/components/BaseSettingsControl.tsx) can be extended to create a new Settings control type.
+
+```tsx
+export class BaseSettingsControl extends React.Component <any, any> {
+  parent_on_change: Function;
+  constructor(props:any) {
+    super(props);
+    this.parent_on_change=props.on_change;
+  }
+  public get_value():any {
+    return null;
+  }
+}
+```
+
+A settings control overrides the `get_value` function to return the value to be used for the Setting the control is representing.
+It will use the `parent_on_change` property to signal that the user made some changes to the settings.
+
+Here's the [`StringTextSettingsControl`](/src/settings-web/src/components/StringTextSettingsControl.tsx) component to serve as an example:
+
+```tsx
+export class StringTextSettingsControl extends BaseSettingsControl {
+  textref:any = null; // Keeps a reference to the corresponding TextField in the DOM.
+
+  constructor(props:any) {
+    super(props);
+    this.textref = null;
+    this.state={
+      property_values: props.setting
+    }
+  }
+
+  componentWillReceiveProps(props: any) {
+    // Fully controlled component.
+    // Reacting to a property change so that the control is redrawn properly.
+    this.setState({ property_values: props.setting })
+  }
+
+  public get_value() : any {
+    // Returns the TextField value.
+    return {value: this.textref.value};
+  }
+
+  public render(): JSX.Element {
+    // Renders a UI Fabric TextField.
+    return (
+      <TextField
+        onChange = {
+          (_event,_new_value) => {
+            // Updates the state with the new value introduced in the TextField.
+            this.setState( (prev_state:any) => ({
+                property_values: {
+                  ...(prev_state.property_values),
+                  value: _new_value
+                }
+              })
+            );
+            // Signal the parent that the user changed a value.
+            this.parent_on_change();
+          }
+        }
+        value={this.state.property_values.value}
+        label={this.state.property_values.display_name}
+        componentRef= {(input) => {this.textref=input;}}
+      />
+    );
+  }
+}
+```
+
+Each settings property has a `editor_type` field that's used to differentiate between the Settings control types:
+```js
+'test string_text': {
+  display_name: 'This is what a string_text looks like',
+  editor_type: 'string_text',
+  value: 'A sample string value'
+}
+```
+
+A new Settings control component can be added to [`src/components/`](/src/settings-web/src/components/).
+To render the new Settings control, its `editor_type` and component instance need to be added to the [`ModuleSettings` component render()](/src/settings-web/src/components/ModuleSettings.tsx):
+```tsx
+import React from 'react';
+import {StringTextSettingsControl} from './StringTextSettingsControl';
+
+...
+
+export class ModuleSettings extends React.Component <any, any> {
+  references: any;
+  parent_on_change: Function;
+...
+  public render(): JSX.Element {
+    let power_toys_properties = this.state.powertoy.properties;
+    return (
+      <Stack tokens={{childrenGap:20}}>
+...
+        {
+          Object.keys(power_toys_properties).
+          map( (key) => {
+            switch(power_toys_properties[key].editor_type) {
+...
+              case 'string_text':
+                return <StringTextSettingsControl
+                  setting = {power_toys_properties[key]}
+                  key={key}
+                  on_change={this.parent_on_change}
+                  ref={(input) => {this.references[key]=input;}}
+                  />;
+...
+```
--- a/doc/devdocs/settings.md
+++ b/doc/devdocs/settings.md
@@ -0,0 +1,8 @@
+#### [main.cpp](/src/settings/main.cpp)
+Contains the main executable code, initializing and managing the Window containing the WebView and communication with the main PowerToys executable.
+
+#### [StreamURIResolverFromFile.cpp](/src/settings/StreamURIResolverFromFile.cpp)
+Defines a class implementing `IUriToStreamResolver`. Allows the WebView to navigate to filesystem files in this Win32 project.
+
+#### [settings-html/](/src/settings/settings-html/)
+Contains the assets file from building the [Web project for the Settings UI](/src/settings./settings-web). It will be loaded by the WebView.
--- a/doc/devdocs/shared-hooks.md
+++ b/doc/devdocs/shared-hooks.md
@@ -0,0 +1,85 @@
+# Shared hooks
+
+To minimize the performance impact on the machine only `runner` installs global hooks, passing the events to registered callbacks in each PowerToy module.
+
+When a PowerToy module is loaded, the `runner` calls the [`get_events()`](/src/modules/interface/powertoy_module_interface.h#L40) method to get a NULL-terminated array of NULL-terminated strings with the names of the events that the PowerToy wants to subscribe to. A `const wchar_t*` string is provided for each of the event names.
+
+Events are signalled by the `runner` calling the [`signal_event(name, data)`](/src/modules/interface/powertoy_module_interface.h#L53) method of the PowerToy module. The `name` parameter contains the NULL-terminated name of the event. The `data` parameter and the method return value are specific for each event.
+
+Currently supported hooks:
+ * `"ll_keyboard"` - [Low Level Keyboard Hook](#low-level-keyboard-hook)
+ * `"win_hook_event"` - [Windows Event Hook](#windows-event-hook)
+
+## Low Level Keyboard Hook
+
+This event is signaled whenever the user presses or releases a key on the keyboard. To subscribe to this event, add `"ll_keyboard"` to the table returned by the `get_events()` method.
+
+The PowerToys runner installs low-level keyboard hook using `SetWindowsHookEx(WH_KEYBOARD_LL, ...)`. See [this MSDN page](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms644985(v%3Dvs.85)) for details.
+
+When a keyboard event is signaled and `ncCode` equals `HC_ACTION`, the `wParam` and `lParam` event parameters are passed to all subscribed clients in the [`LowlevelKeyboardEvent`](/src/modules/interface/lowlevel_keyboard_event_data.h#L38-L41) struct.
+
+The `intptr_t data` event argument is a pointer to the `LowlevelKeyboardEvent` struct.
+
+A non-zero return value from any of the subscribed PowerToys will cause the runner hook proc to return 1, thus swallowing the keyboard event.
+
+Example usage, that makes Windows ignore the L key:
+
+```c++
+virtual const wchar_t** get_events() override {
+  static const wchar_t* events[2] = { ll_keyboard,
+                                      nullptr };
+  return events;
+}
+
+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));
+    // The L key has vkCode of 0x4C, see:
+    // https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes
+    if (event.wParam == WM_KEYDOWN && event.lParam->vkCode == 0x4C) {
+      return 1;
+    } else {
+      return 0;
+    }
+  } else {
+    return 0;
+  }
+}
+```
+
+## Windows Event Hook
+
+This event is signaled for [a range of events](https://docs.microsoft.com/pl-pl/windows/win32/winauto/event-constants). To subscribe to this event, add `"win_hook_event"` to the table returned by the `get_events()` method. See [this MSDN doc](https://docs.microsoft.com/pl-pl/windows/win32/api/winuser/nf-winuser-setwineventhook) for details.
+  
+The `intptr_t data` event argument is a pointer to the [`WinHookEvent`](/src/modules/interface/win_hook_event_data.h#L43-L50) struct.
+
+The return value of the event handler is ignored.
+
+Example usage, that detects a window being resized:
+
+```c++
+virtual const wchar_t** get_events() override {
+  static const wchar_t* events[2] = { win_hook_event,
+                                      nullptr };
+  return events;
+}
+
+virtual intptr_t signal_event(const wchar_t* name, intptr_t data) override {
+  if (wcscmp(name, win_hook_event) == 0) {
+    auto& event = *(reinterpret_cast<WinHookEvent*>(data));
+    switch (event.event) {
+    case EVENT_SYSTEM_MOVESIZESTART:
+      size_start(event.hwnd);
+      break;
+    case EVENT_SYSTEM_MOVESIZEEND:
+      size_end(event.hwnd);
+      break;
+    default:
+      break;
+    }
+  }
+  return 0;
+}
+```
+
+Taking too long to process the events has negative impact on the whole system performance. To address this, the events are signaled from a different thread, not from the event hook callback itself.
--- a/doc/devdocs/style.md
+++ b/doc/devdocs/style.md
@@ -0,0 +1,12 @@
+# Coding Style
+
+## Philosophy
+1. If it's inserting something into the existing classes/functions, try to follow the existing style as closely as possible.
+1. If it's brand new code or refactoring a complete class or area of the code, please follow as Modern C++ of a style as you can and reference the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines) as much as you possibly can.
+
+## Formatting
+
+- We use [`.clang-format`](https://github.com/microsoft/PowerToys/blob/master/.clang-format) style file to enable automatic code formatting. You can [easily format source files from Visual Studio](https://devblogs.microsoft.com/cppblog/clangformat-support-in-visual-studio-2017-15-7-preview-1/). For example, `CTRL+K CTRL+D` formats the current document.
+- If you prefer another text editor or have ClangFormat disabled in Visual Studio, you could invoke [`format_sources`](https://github.com/microsoft/PowerToys/blob/master/format_sources.ps1) powershell script from command line. It gets a list of all currently modified files from `git` and invokes clang-format on them.
+Please note that you should also have `clang-format.exe` in `%PATH%` for it to work. The script can infer the path of `clang-format.exe` version which is shipped with Visual Studio at `%VCINSTALLDIR%\Tools\Llvm\bin\`, if you launch it from the *Native Tools Command Prompt for VS*.
+- CI doesn't enforce code formatting yet, since we're gradually applying code formatting to the codebase, but please adhere to our formatting style for any new code.