From 1978717f92f1011be4ba506597b298be5c80d897 Mon Sep 17 00:00:00 2001 From: yuyoyuppe Date: Wed, 11 Dec 2019 14:29:37 +0300 Subject: [PATCH] # 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 --- doc/devdocs/common.md | 28 ++++++++--------- doc/devdocs/modules/example_powertoy.md | 4 +-- doc/devdocs/runner.md | 41 +++++++++++++------------ doc/devdocs/settings-web.md | 32 +++++++++---------- doc/devdocs/settings.md | 8 ++--- 5 files changed, 57 insertions(+), 56 deletions(-) diff --git a/doc/devdocs/common.md b/doc/devdocs/common.md index 6ab934d71c23..2c89bc75179e 100644 --- a/doc/devdocs/common.md +++ b/doc/devdocs/common.md @@ -1,45 +1,45 @@ # Classes and structures -#### class Animation: [header](./animation.h) [source](./animation.cpp) +#### 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](./async_message_queue.h) +#### class AsyncMessageQueue: [header](/src/common/async_message_queue.h) Header-only asynchronous message queue. Used by `TwoWayPipeMessageIPC`. -#### class TwoWayPipeMessageIPC: [header](./two_way_pipe_message_ipc.h) +#### 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](./d2d_svg.h) [source](./d2d_svg.cpp) +#### 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](./d2d_text.h) [source](./d2d_text.cpp) +#### class D2DText: [header](/src/common/d2d_text.h) [source](/src/common/d2d_text.cpp) Class for rendering text using DirectX. -#### class D2DWindow: [header](./d2d_window.h) [source](./d2d_window.cpp) +#### 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](./dpi_aware.h) [source](./dpi_aware.cpp) +#### class DPIAware: [header](/src/common/dpi_aware.h) [source](/src/common/dpi_aware.cpp) Helper class for creating DPI-aware applications. -#### struct MonitorInfo: [header](./monitors.h) [source](./monitors.cpp) +#### 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](./settings_objects.h) [source](./settings_objects.cpp) +#### 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](./tasklist_positions.h) [source](./tasklist_positions.cpp) +#### 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](./windows_colors.h) [source](./windows_colors.cpp) +#### 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](./common.h) [source](./common.cpp) +#### Common helpers: [header](/src/common/common.h) [source](/src/common/common.cpp) Various helper functions. -#### Settings helpers: [header](./settings_helpers.h) +#### Settings helpers: [header](/src/common/settings_helpers.h) Helper methods for the settings. -#### Start visible helper: [header](./start_visible.h) [source](./start_visible.cpp) +#### 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. diff --git a/doc/devdocs/modules/example_powertoy.md b/doc/devdocs/modules/example_powertoy.md index 26c5319cbb69..e07a07212799 100644 --- a/doc/devdocs/modules/example_powertoy.md +++ b/doc/devdocs/modules/example_powertoy.md @@ -1,5 +1,5 @@ -#### [`dllmain.cpp`](./dllmain.cpp) +#### [`dllmain.cpp`](/src/modules/example_powertoy/dllmain.cpp) Contains DLL boilerplate code and implementation of the [PowerToys interface](/src/modules/interface/). -#### [`trace.cpp`](./trace.cpp) +#### [`trace.cpp`](/src/modules/example_powertoy/trace.cpp) Contains code for telemetry. diff --git a/doc/devdocs/runner.md b/doc/devdocs/runner.md index 50bb0123d20b..9fff233c12df 100644 --- a/doc/devdocs/runner.md +++ b/doc/devdocs/runner.md @@ -1,35 +1,36 @@ -#### [`main.cpp`](./main.cpp) -Contains the executable starting point, initialization code and the list of known PowerToys. +#### [`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). -#### [`powertoy_module.h`](./powertoy_module.h) and [`powertoy_module.cpp`](./powertoy_module.cpp) -Contains code for initializing and managing the PowerToy modules. - -#### [`powertoys_events.cpp`](./powertoys_events.cpp) -Contains code that handles the various events listeners, and forwards those events to the PowerToys modules. +#### [`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). -#### [`lowlevel_keyboard_event.cpp`](./lowlevel_keyboard_event.cpp) -Contains code for registering the low level keyboard event hook that listens for keyboard events. +#### [`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). -#### [`win_hook_event.cpp`](./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. +#### [`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. -#### [`tray_icon.cpp`](./tray_icon.cpp) -Contains code for managing the PowerToys tray icon and its menu commands. +#### [`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. -#### [`settings_window.cpp`](./settings_window.cpp) -Contains code for starting the PowerToys settings window and communicating with it. +#### [`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`](./general_settings.cpp) +#### [`general_settings.cpp`](/src/runner/general_settings.cpp) Contains code for loading, saving and applying the general setings. -#### [`auto_start_helper.cpp`](./auto_start_helper.cpp) +#### [`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`](./unhandled_exception_handler.cpp) +#### [`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`](./trace.cpp) +#### [`trace.cpp`](/src/runner/trace.cpp) Contains code for telemetry. -#### [`svgs`](./svgs/) +#### [`svgs`](/src/runner/svgs/) Contains the SVG assets used by the PowerToys modules. diff --git a/doc/devdocs/settings-web.md b/doc/devdocs/settings-web.md index 5c33ab5a5e05..be5e51a977bf 100644 --- a/doc/devdocs/settings-web.md +++ b/doc/devdocs/settings-web.md @@ -17,7 +17,7 @@ npm run build ## Updating the icons -Icons inside [`src/icons/`](./src/icons/) were generated from the [Office UI Fabric Icons subset generation tool.](https://uifabricicons.azurewebsites.net/) +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). @@ -30,44 +30,44 @@ SVG icons, including the icons for each PowerToy listed in the Settings, are con 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](./index.html) +#### [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/index.tsx) +#### [src/index.tsx](/src/settings-web/src/index.tsx) Main `ReactJS` entrypoint, initializing the `ReactDOM`. -#### [src/setup_icons.tsx](./src/setup_icons.tsx) +#### [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/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/components/App.tsx) +#### [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/components/GeneralSettings.tsx) +#### [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/components/ModuleSettings.tsx) +#### [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/components/BaseSettingsControl.tsx) +#### [src/components/BaseSettingsControl.tsx](/src/settings-web/src/components/BaseSettingsControl.tsx) Defines the base class for a Settings control. -#### [src/css/layout.css](./src/css/layout.css) +#### [src/css/layout.css](/src/settings-web/src/css/layout.css) General layout styles. -#### [src/icons/](./src/icons/) +#### [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/svg/) +#### [src/svg/](/src/settings-web/src/svg/) SVG icon assets. ## Creating a new settings control -The [`BaseSettingsControl` class](./src/components/BaseSettingsControl.tsx) can be extended to create a new Settings control type. +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 { @@ -85,7 +85,7 @@ export class BaseSettingsControl extends React.Component { 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/components/StringTextSettingsControl.tsx) component to serve as an example: +Here's the [`StringTextSettingsControl`](/src/settings-web/src/components/StringTextSettingsControl.tsx) component to serve as an example: ```tsx export class StringTextSettingsControl extends BaseSettingsControl { @@ -146,8 +146,8 @@ Each settings property has a `editor_type` field that's used to differentiate be } ``` -A new Settings control component can be added to [`src/components/`](./src/components/). -To render the new Settings control, its `editor_type` and component instance need to be added to the [`ModuleSettings` component render()](./src/components/ModuleSettings.tsx): +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'; diff --git a/doc/devdocs/settings.md b/doc/devdocs/settings.md index 8042a69a1481..6d1e79335de6 100644 --- a/doc/devdocs/settings.md +++ b/doc/devdocs/settings.md @@ -1,8 +1,8 @@ -#### [main.cpp](./main.cpp) +#### [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](./StreamURIResolverFromFile.cpp) +#### [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/](./settings-html/) -Contains the assets file from building the [Web project for the Settings UI](../settings-web). It will be loaded by the WebView. +#### [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.