Customize system menu items through dedicated API (#677)

Document new interface changes.

src/modules/example_powertoy/dllmain.cpp

@@ -214,6 +214,9 @@ public:
     }
     return 0;
   }
+
+  virtual void register_system_menu_helper(PowertoySystemMenuIface* helper) override { }
+  virtual void signal_system_menu_action(const wchar_t* name) override { }
 };
 
 // Load the settings file.

src/modules/fancyzones/dll/dllmain.cpp

@@ -182,6 +182,9 @@ public:
         return 0;
     }
 
+    virtual void register_system_menu_helper(PowertoySystemMenuIface* helper) override { }
+    virtual void signal_system_menu_action(const wchar_t* name) override { }
+
     // Destroy the powertoy and free memory
     virtual void destroy() override
     {

src/modules/interface/README.md

@@ -19,6 +19,8 @@ public:
   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;
 };
 
@@ -43,6 +45,8 @@ and destroy():
   - [`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),
@@ -313,6 +317,25 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
+### 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
@@ -328,11 +351,59 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
+### 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`](./powertoy_module_interface.h)
 Contains the PowerToys interface definition.
 
+### [`powertoy_system_menu.h`](./powertoy_system_module.h)
+Contains the PowerToys system menu helper interface definition.
+
 #### [`lowlevel_keyboard_event_data.h`](./lowlevel_keyboard_event_data.h)
 Contains the `LowlevelKeyboardEvent` structure that's passed to `signal_event` for `ll_keyboard` events.
 

src/modules/interface/powertoy_module_interface.h

@@ -28,6 +28,8 @@
     - unload the DLL.
  */
 
+class PowertoySystemMenuIface;
+
 class PowertoyModuleIface {
 public:
   /* Returns the name of the PowerToy, this will be cached by the runner. */
@@ -63,6 +65,12 @@ public:
        * win_hook_event: see win_hook_event_data.h
   */
   virtual intptr_t signal_event(const wchar_t* name, intptr_t data) = 0;
+
+  /* Register helper class to handle system menu items related actions. */
+  virtual void register_system_menu_helper(PowertoySystemMenuIface* helper) = 0;
+  /* Handle action on system menu item. */
+  virtual void signal_system_menu_action(const wchar_t* name) = 0;
+
   /* Destroy the PowerToy and free all memory. */
   virtual void destroy() = 0;
 };

src/modules/interface/powertoy_system_menu.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include <string>
+
+class PowertoyModuleIface;
+
+class PowertoySystemMenuIface {
+public:
+  struct ItemInfo {
+    std::wstring name{};
+    bool enable{ false };
+    bool checkBox{ false };
+  };
+  /* 
+   * Set configuration of system menu items for specific powertoy module. Configuration
+   * parameters include item name (and hotkey), item status at creation (enabled/disabled)
+   * and whether check box will appear next to item name when action is taken.
+   */
+  virtual void SetConfiguration(PowertoyModuleIface* module, const std::vector<ItemInfo>& config) = 0;
+  /* Process action on specific system menu item. */
+  virtual void ProcessSelectedItem(PowertoyModuleIface* module, HWND window, const wchar_t* itemName) = 0;
+};

src/modules/powerrename/dll/dllmain.cpp

@@ -227,6 +227,9 @@ public:
         return 0;
     }
 
+    virtual void register_system_menu_helper(PowertoySystemMenuIface* helper) override { }
+    virtual void signal_system_menu_action(const wchar_t* name) override { }
+
     // Destroy the powertoy and free memory
     virtual void destroy() override
     {

src/modules/shortcut_guide/shortcut_guide.h

@@ -21,6 +21,9 @@ public:
   virtual bool is_enabled() override;
   virtual intptr_t signal_event(const wchar_t* name, intptr_t data)  override;
 
+  virtual void register_system_menu_helper(PowertoySystemMenuIface* helper) override { }
+  virtual void signal_system_menu_action(const wchar_t* name) override { }
+
   void on_held();
   void on_held_press(DWORD vkCode);
   void quick_hide();