Dev documentation of SettingsV2 (#7335)

* created a folder for settings and added an overview, hotkey information

* basic structure for communication between settings and runner

* Added information about the IPC communication between settings and runner

* Added information about the communication between the settings process and modules

* Added details on backward compatibility

* brief overview on settings utils

* added an overview of the viewmodels and anomalies

* minor modifications

* Settings v2 dev docs (#7334)

* Added settings architecture and tech stack dev docs

* Added telemetry and updated architecture docs for settings v2

* Fix image link in ui_architecture markdown

* Added table of contents for settings v2

* Correct file path for ui architecture image

* nit fix in table of contents heading

* Add doc for xaml island tweaks

Co-authored-by: Divyansh Srivastava <somm14divi@gmail.com>

doc/devdocs/settingsv2/communication-with-modules.md

@@ -0,0 +1,15 @@
+# Communication with modules
+
+## Through runner
+- The settings process communicates changes in the UI to most modules using the runner through delegates.
+- More details on this are mentioned in [`runner-ipc.md`](settingsv2/runner-ipc.md).
+
+## PT Run
+- Any changes to the UI are saved by the settings process in the `settings.json` file located within the `/Local/Microsoft/PowerToys/Launcher/` folder.
+- PT Run watches for any changes within this file and updates it's general settings or propagates the information to the plugins, depending on the type of information.
+Eg: The maximum number of results drop down updates the maximum number of rows in the results list which updates the general settings of PT Run whereas the drive detection checkbox details are dispatched to the indexer plugin.
+
+## Keyboard Manager
+- The Settings process and keyboard manager share access to a common `default.json` file which contains information about the remapped keys and shortcuts.
+- To ensure that there is no contention while both processes try to access the common file, there is a named file mutex. 
+- The settings process expects the keyboard manager process to create the `default.json` file if it does not exist. It does not create the file in case it is not present.

doc/devdocs/settingsv2/compatibility-legacy-settings.md

@@ -0,0 +1,12 @@
+# Compatibility with legacy settings and runner
+The following must be kept in mind regarding compatibility with settings v1 and runner.
+
+### 1. Folder Naming structure
+- Each of the modules has a folder within the `Local/Microsoft/PowerToys` directory which contains the module configurations within the `settings.json` file. The name of this folder must be the same across settingsv1 and settingsv2. 
+- The name of the settings folder for each powertoy is the same as the `ModuleName`. It is set within each of the viewModel files. This name must not be changed to ensure that the user configurations for each of the powertoys rolls over on update.
+
+### 2. Communication with runner
+- The status of each of the modules is communicated with the runner in the form of a json object. The names of all the powerToys is set in the [`EnableModules.cs`](src/core/Microsoft.PowerToys.Settings.UI.Lib/EnabledModules.cs) file. The `JsonPropertyName` must not be changed to ensure that the information is dispatched properly to all the modules by the runner.
+
+### ImageResizer anomaly
+All the powertoys have the same folder name as well as JsonPropertyName to communicate information with the runner. However that is not the case with ImageResizer. The folder name is `ImageResizer` whereas the JsonPropertyName is `Image Resizer`(Note the additional space). This should not be changed to ensure backward compatibity as well as proper functioning of the module.

doc/devdocs/settingsv2/hotkeycontrol.md

@@ -0,0 +1,46 @@
+# Custom HotKey Control
+
+The Settings project provides a custom hotkey control which consumes key presses. This control can be used to set the hotkey of any PowerToy.
+
+## HotKey Control in FancyZones
+![Image of hotkey control](/doc/images/settingsv2/settingshotkeycontrol.png)
+
+## Hotkey related files
+
+#### [`HotkeySettingsControlHook.cs`](/src/core/Microsoft.PowerToys.Settings.UI.Lib/HotkeySettingsControlHook.cs)
+
+- This function initializes and starts the [`keyboardHook`](src/common/interop/KeyboardHook.cpp) for the hotkey control.
+
+```csharp
+        public HotkeySettingsControlHook(KeyEvent keyDown, KeyEvent keyUp, IsActive isActive, FilterAccessibleKeyboardEvents filterAccessibleKeyboardEvents)
+        {
+            _keyDown = keyDown;
+            _keyUp = keyUp;
+            _isActive = isActive;
+            _filterKeyboardEvent = filterAccessibleKeyboardEvents;
+            _hook = new KeyboardHook(HotkeySettingsHookCallback, IsActive, FilterKeyboardEvents);
+            _hook.Start();
+        }
+        
+```
+
+#### [`HotkeySettingsControl.xaml.cs`](/src/core/Microsoft.PowerToys.Settings.UI/HotkeySettingsControl.xaml.cs)
+
+- The function of this class is to update the state of the keys being pressed within the custom control. This information is stored in `internalSettings`.
+
+- It provides the following callbacks to the `HotKeySettingsControlHook`:
+
+    - `KeyUp`: Resets the key state in `internalSettings` when a key is released.
+    - `KeyDown`: Updates the user facing text of the hotkey control as soon as a key is pressed.
+    - `isActive`: Sets the current status of the keyboard hook.
+    - `FilterAccessibleKeyboardEvents`: This function is used to ignore the `Tab` and `Shift+Tab` key presses to meet the accessibility requirements.
+
+#### [`HotkeySettings.cs`](/src/core/Microsoft.PowerToys.Settings.UI.Lib/HotkeySettings.cs)
+
+- Contains the structure of a HotKey where it is represented as a combination of one of the modifier keys (`Alt`, `Shift`, `Win` and `Ctrl`) and a non-modifier key.
+
+#### Note
+- The control displays all key presses to the user (except Tab and Shift+Tab which move focus out of the control). However, when the focus is being lost from the control, the `lastValidHotkeySettings` is set as the user facing text.
+
+
+

doc/devdocs/settingsv2/project-overview.md

@@ -0,0 +1,17 @@
+# Overview
+`Settingsv2` is WPF .net core desktop application. It uses the `WindowsXamlHost` control from the Windows Community Toolkit to host UWP controls from `WinUI3` library. More details about WinUI can be found [here](https://microsoft.github.io/microsoft-ui-xaml/about.html#what-is-it).
+
+## Settings V2 Project structure
+The Settings project is a XAML island based project which
+follows the [MVVM architectural pattern][MVVM] where the graphical user interface is separated from the view models.
+
+#### [UI Components:](/src/core/Microsoft.PowerToys.Settings.UI)
+The Settings.UI project contains the xaml files for each of the UI components. It also contains the Hotkey logic for the settings control.
+
+#### [Viewmodels:](/src/core/Microsoft.PowerToys.Settings.UI.Lib)
+The Settings.UI.Lib project contains the data that is to be rendered by the UI components.
+
+#### [Settings Runner:](/src/core/Microsoft.PowerToys.Settings.UI.Runner)
+The function of the settings runner project is to communicate all changes that the user makes in the user interface, to the runner so that it can be dispatched and reflected in all the modules.
+
+[MVVM]: https://docs.microsoft.com/en-us/windows/uwp/data-binding/data-binding-and-mvvm

doc/devdocs/settingsv2/readme.md

@@ -0,0 +1,12 @@
+# Table of Contents
+1. [Settings overview](/doc/devdocs/settingsv2/project-overview.md)
+2. [UI Architecture](/doc/devdocs/settingsv2/ui-architecture.md)
+3. [ViewModels](/doc/devdocs/settingsv2/viewmodels.md)
+4. Data flow
+    - [Inter-Process Communication with runner](/doc/devdocs/settingsv2/runner-ipc.md)
+    - [Communication with modules](/doc/devdocs/settingsv2/communication-with-modules.md)
+5. [Settings Utilities](/doc/devdocs/settingsv2/settings-utilities.md)
+6. [Custom Hotkey control and keyboard hook handling](hotkeycontrol.md)
+7. [Compatibility with legacy settings and runner](/doc/devdocs/settingsv2/compatibility-legacy-settings.md)
+8. [XAML Island tweaks](/doc/devdocs/settingsv2/xaml-island-tweaks.md)
+9. [Telemetry](/doc/devdocs/settingsv2/telemetry.md)

doc/devdocs/settingsv2/runner-ipc.md

@@ -0,0 +1,46 @@
+# Inter-Process Communication with Runner
+
+The Settings v2 process uses two way IPC to communicate with the runner process.
+
+## Initialization
+- On the settings' side, the two way IPC delegates are contained with the [`ShellPage.xaml.cs`](/src/core/Microsoft.PowerToys.Settings.UI/Views/ShellPage.xaml.cs) file. The delegates are static and the views for all the powerToys send the ipc information to the viewmodels as `ShellPage.DefaultSndMSGCallBack`.
+- These delegates are initialized within the [`Mainwindow.xaml.cs`](/src/core/Microsoft.PowerToys.Settings.UI.Runner/MainWindow.xaml.cs) file in the `Settings.Runner` project.
+
+
+## Types of IPC delegates
+- There are three types of delegates for the settings to communicate with the runner:
+1. `SendDefaultMessage` - This is used by all the viewmodels to communicate changes in the UI to the runner so that the information can be dispatched to the modules.
+2. `RestartAsAdmin`
+3. `CheckForUpdates`
+
+## Sending information to runner
+- The settings process communicates with the runner by using the delegates defined within the [`ShellPage.xaml.cs`](/src/core/Microsoft.PowerToys.Settings.UI/Views/ShellPage.xaml.cs) file.
+- Depending on the type of object sending the information, the json is created accordingly.
+- If any information has been modified by the user in the GeneralSettings page, then the json file sent to the runner has the name set to `general`, whereas if any information has been modified by the user in any powertoy related settings page, the name of the json file being communicated with the runner is set to `powertoy`.
+
+## Receiving information from runner
+- The `ShellPage`object has a `IPCResponseHandleList` which is a list of functions which handle IPC responses. 
+
+```csharp
+// receive IPC Message
+Program.IPCMessageReceivedCallback = (string msg) =>
+{
+    if (ShellPage.ShellHandler.IPCResponseHandleList != null)
+    {
+        try
+        {
+            JsonObject json = JsonObject.Parse(msg);
+            foreach (Action<JsonObject> handle in ShellPage.ShellHandler.IPCResponseHandleList)
+            {
+                handle(json);
+            }
+        }
+        catch (Exception)
+        {
+        }
+    }
+};
+```
+
+- Whenever any information is sent from the runner each of the functions in the handle list perform their action on that json object.
+- One example of where information sent from the runner is being processed by the settings is in [`GeneralPage.xaml.cs`](/src/core/Microsoft.PowerToys.Settings.UI/Views/GeneralPage.xaml.cs) when the user clicks the check for updates button. The information displayed after, such as the user has the latest version installed is a result of this handle.

doc/devdocs/settingsv2/settings-utilities.md

@@ -0,0 +1,13 @@
+# Settings Utilities
+
+- Abstractions for each of the file/folder related operations are present in [`SettingsUtils.cs`](src/core/Microsoft.PowerToys.Settings.UI.Lib/SettingsUtils.cs).
+- To reduce contention between the settings process and runner while trying to access the `settings.json` file of any powertoy, the settings process tries to access the file only when it needs to load the information for the first time. However, there is still no mechanism in place which ensures that both the settings and runner processes do not access the information simultaneously leading to `IOExceptions`.
+
+## Utilities
+
+### `GetSettings<T>(powertoy, filename)`
+
+- The GetSettings function tries to read the file in the powertoy settings folder and creates a new file with default configurations if it does not exist.
+- Ideally this function should only be called by the [`SettingsRepository`](src/core/Microsoft.PowerToys.Settings.UI.Lib/SettingsRepository`1.cs) which would be accessed only when a powertoy settings object is being loaded for the first time.
+- The reason behind ensuring that it is not accessed elsewhere is to avoid contention with the runner during file access.
+- Each of the objects which are deserialized using this function must implement the `ISettingsConfig` interface.

doc/devdocs/settingsv2/telemetry.md

@@ -0,0 +1,8 @@
+# Telemetry
+## Overview
+[`Microsoft.PowerToys.Settings.UI.Lib/Telemetry`](/src/core/Microsoft.PowerToys.Settings.UI.Lib/Telemetry) contains telemetry events generated by `Settingsv2.` These event classes are derived from the [`EventBase`](/src/common/ManagedTelemetry/Telemetry/Events/EventBase.cs) class and [`IEvent`](/src/common/ManagedTelemetry/Telemetry/Events/IEvent.cs) class. [`IEvent`](/src/common/ManagedTelemetry/Telemetry/Events/IEvent.cs) class provides the lowest level abstraction, containing attributes such as privacy tags needed for every telemetry data. [`EventBase`](/src/common/ManagedTelemetry/Telemetry/Events/EventBase.cs) class provides a higher-level abstraction, having attributes common to all `PowerToys` telemetry events.
+
+## Events
+The following events are generated by `Settingsv2`:
+1. [`SettingsBootEvent`](/src/core/Microsoft.PowerToys.Settings.UI.Lib/Telemetry/Events/SettingsBootEvent.cs): This event captures the time taken by `Settingsv2` to initialize `MainWindow` UI control.
+2. [`SettingsEnabledEvent.cs`](/src/core/Microsoft.PowerToys.Settings.UI.Lib/Telemetry/Events/SettingsEnabledEvent.cs): This event is generated when a module is enabled or disabled.

doc/devdocs/settingsv2/ui-architecture.md

@@ -0,0 +1,9 @@
+# UI Architecture
+
+ The UI code is distributed between two projects: [`Microsoft.PowerToys.Settings.UI.Runner`](/src/core/Microsoft.PowerToys.Settings.UI.Runner) and [`Microsoft.PowerToys.Settings.UI`](/src/core/Microsoft.PowerToys.Settings.UI.Lib). [`Microsoft.PowerToys.Settings.UI.Runner`](/src/core/Microsoft.PowerToys.Settings.UI.Runner) is a WPF .net core application. It contains the parent display window and corresponding code is present in [`MainWindow.xaml.`](/src/core/Microsoft.PowerToys.Settings.UI.Runner/MainWindow.xaml) [`Microsoft.PowerToys.Settings.UI`](/src/core/Microsoft.PowerToys.Settings.UI.Lib) is UWP applications and contains views for base navigation and modules. Fig 1 provides a description of the UI controls hierarchy and each of the controls have been summarized below : 
+- [`MainWindow.xaml`](/src/core/Microsoft.PowerToys.Settings.UI.Runner/MainWindow.xaml) is the parent WPF control.
+- `WindowsXamlHost` control is used to host UWP control to [`MainWindow.xaml`](/src/core/Microsoft.PowerToys.Settings.UI.Runner/MainWindow.xaml)  parent control.
+- [`ShellPage.xaml`](/src/core/Microsoft.PowerToys.Settings.UI/Views/ShellPage.xaml) is a UWP control, consisting of a side navigation panel with an icon for each module. Clicking on a module icon loads the corresponding `setting.json` file and displays the data in the UI.
+
+![Settings UI architecture](/doc/images/settingsv2/ui-architecture.png)
+**Fig 1: UI Architecture for settingsv2**

doc/devdocs/settingsv2/viewmodels.md

@@ -0,0 +1,26 @@
+# Viewmodels
+The viewmodels are located within the [`Microsoft.PowerToys.Settings.UI.Lib`](/src/core/Microsoft.PowerToys.Settings.UI.Lib) project.
+
+## Components
+- Each viewmodel takes in the general `settingsRepository`, the `moduleSettingsRepository` if it exists and the delegates for IPC communication.
+- The general `settingsRepository` contains the general configurations of all powertoys whereas the `moduleSettingsRepository` is spcific to the module. This is to ensure that the configuration details are shared amongst the viewmodels without having to re-open the `settings.json` file.
+- Whenever there is a change in the UI, the `OnPropertyChanged` event is invoked and the viewmodel sends a corresponding IPC message to the runner which would perform the designated action such as dispatching the change to the modules or enabling/disabling the powertoy etc.
+
+#### Difference between viewmodels
+- The [`GeneralViewModel`](/src/core/Microsoft.PowerToys.Settings.UI.Lib/ViewModels/GeneralViewModel.cs) is different from the rest of the view models with regard to the IPC communication wherein it sends special IPC messages to the runner to check for updates and to restart as admin.
+- Each of the powerToy viewmodels have two types of IPC communications, one for the general status of the powerToy and the other for communication powerToy specific change in properties to the runner.
+
+## [`SettingsRepository`](src/core/Microsoft.PowerToys.Settings.UI.Lib/SettingsRepository`1.cs)
+- The [`SettingsRepository`](src/core/Microsoft.PowerToys.Settings.UI.Lib/SettingsRepository`1.cs) is a generic singleton which contains the configurations for each viewmodel.
+- As it is a generic singleton, there can only be one instance of the settings repository of a particular type. This ensures that all the viewmodels are modifying a common object and a change made in one locations reflects everywhere.
+- The singleton implementation is thread-safe. Unit tests have been added for the same.
+
+### Settings viewmodel anomalies
+- The reason behind using the `SettingsRepository` is to ensure that the settings process does not try to access the `settings.json` files directly but rather does it through this class which encapsulates all the file operations from the viewmodels.
+- However, this could not be expanded to all the viewmodels directly for the following reasons. Some refactoring must be done to unify these cases and to bring them under the same model:
+    - The PowerRename viewodel does not save the settings configurations in the same format as the rest of the powertoys, ie. {name, version, properties}. However, it only stores the properties directly.
+    - Some viewmodels expect the runner to create the file instead of creating the file themselves, like in keyboard manager.
+    - The colorpicker powertoy creates the `settings.json` within the module. This must be taken care of when encapsulated within the settingsRepository.
+- Currently, all modules use the `SettingsRepository` to access the General Settings config. 
+- However, only Fancyzones, ShortcutGuide and PowerPreview use the `SettingsRepository` to access the module properties.
+

doc/devdocs/settingsv2/xaml-island-tweaks.md

@@ -0,0 +1,30 @@
+# XAML Island Tweaks
+Few tweaks were made to fix issues with Xaml Islands. These tweaks should be removed after migrating to WINUI3. The tweaks are listed below: 
+1. Workaround to ensure XAML Island application terminates if attempted to close from taskbar while minimized:
+```
+private void MainWindow_Closing(object sender, System.ComponentModel.CancelEventArgs e)
+{
+    isOpen = false;
+
+    // XAML Islands: If the window is closed while minimized, exit the process. Required to avoid process not terminating issue - https://github.com/microsoft/PowerToys/issues/4430
+    if (WindowState == WindowState.Minimized)
+    {
+        // Run Environment.Exit on a separate task to avoid performance impact
+        System.Threading.Tasks.Task.Run(() => { Environment.Exit(0); });
+    }
+}
+```
+2. Workaround to hide the XAML Island blank icon in the taskbar when the XAML Island application is loading:
+```
+var coreWindow = Windows.UI.Core.CoreWindow.GetForCurrentThread(); 
+var coreWindowInterop = Interop.GetInterop(coreWindow); 
+Interop.ShowWindow(coreWindowInterop.WindowHandle, Interop.SW_HIDE); 
+```
+3. Workaround to prevent XAML Island failing to render on Nvidia workstation graphics cards:
+```
+ // XAML Islands: If the window is open, explicity force it to be shown to solve the blank dialog issue https://github.com/microsoft/PowerToys/issues/3384 
+ if (isOpen) 
+ { 
+     Show(); 
+ } 
+ ```