1  # PowerToys GPO (Group Policy Objects) Implementation
  2  
  3  Group Policy Objects (GPOs) allow system administrators to control PowerToys settings across an organization. This document describes how GPOs are implemented in PowerToys.
  4  
  5  ## GPO Overview
  6  
  7  GPO policies allow system administrators to control PowerToys settings. PowerToys ships GPO files as part of the release zip, not installed directly.
  8  
  9  ## GPO File Structure
 10  
 11  ### ADMX File
 12  - Contains policy definitions
 13  - Defines which versions support each policy
 14  - Sets up folder structure
 15  - Defines each policy with:
 16    - Name
 17    - Class (user scope or machine scope)
 18    - Description
 19    - Registry location where policy is stored
 20    - Enabled/disabled values
 21  
 22  ### ADML File
 23  - Contains localized strings for the ADMX file
 24  - Contains revision number that must be updated when changes are made
 25  - Stores strings for:
 26    - Folder names
 27    - Version definitions
 28    - Policy descriptions and titles
 29  - Currently only ships English US version (no localization story yet)
 30  
 31  ## Installation Process
 32  
 33  - Files need to be placed in: `C:\Windows\PolicyDefinitions\`
 34  - ADMX file goes in the root folder
 35  - ADML file goes in the language subfolder (e.g., en-US)
 36  - After installation, policies appear in the Group Policy Editor (gpedit.msc)
 37  
 38  ## Registry Implementation
 39  
 40  - Policies are stored as registry values
 41  - Location: `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\PowerToys` or `HKEY_CURRENT_USER\SOFTWARE\Policies\Microsoft\PowerToys`
 42  - Machine scope takes precedence over user scope
 43  - Policy states:
 44    - Enabled: Registry value set to 1
 45    - Disabled: Registry value set to 0
 46    - Not Configured: Registry value does not exist
 47  
 48  ## Code Integration
 49  
 50  ### Common Files
 51  - Policy keys defined in `common\utils\GPO.h`
 52  - Contains functions to read registry values and get configured values
 53  - WinRT C++ adapter created for C# applications to access GPO settings
 54  
 55  ### WPF Applications
 56  - WPF applications cannot directly load WinRT C++ projects
 57  - Additional library created to allow WPF applications to access GPO values
 58  
 59  ### Module Interface
 60  - Each module must implement policy checking in its interface
 61  - Runner checks this to determine if module should be started or not
 62  
 63  ## UI Implementation
 64  
 65  - When a policy disables a utility:
 66    - UI is locked (cannot be enabled)
 67    - Settings page shows a lock icon
 68    - Dashboard hides the module button
 69    - If user tries to start the executable directly, it exits and logs a message
 70  
 71  ## Types of GPO Policies
 72  
 73  ### Basic Module Enable/Disable Policy
 74  - Most common type
 75  - Controls whether a module can be enabled or disabled
 76  - Shared description text for these policies
 77  
 78  ### Configuration Policies
 79  - Example: Run at startup setting
 80  - Controls specific settings rather than enabling/disabling modules
 81  - Custom description text explaining what happens when enabled/disabled/not configured
 82  
 83  ### Machine-Scope Only Policies
 84  - Example: Mouse Without Borders service mode
 85  - Only makes sense at machine level (not user level)
 86  - Restricts functionality that requires elevated permissions
 87  
 88  ## Steps to Add a New Policy
 89  
 90  1. Update ADMX file:
 91     - Increase revision number
 92     - Add supported version definition
 93     - Define the policy with registry location
 94  
 95  2. Update ADML file:
 96     - Increase revision number
 97     - Add strings for version, title, description
 98  
 99  3. Update code:
100     - Add to GPO.h
101     - Add to GPO wrapper for C# access
102     - Update module interface
103     - Modify settings UI to show lock when policy applied
104     - Add checks in executable to prevent direct launching
105     - Update dashboard helper to respect policy
106  
107  4. Add to bug report tool to capture policy state
108  
109  ## Update-Related GPO Settings
110  
111  - `disable automatic update download` - Prevents automatic downloading
112  - `disable new update toast` - Controls if toast notifications are shown
113  - `suspend new update toast` - Suspends toast notifications for 2 minor releases
114  
115  ## Testing GPO Settings
116  
117  To test GPO settings locally:
118  
119  1. Run `regedit` as administrator
120  2. Navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\PowerToys`
121  3. Create a new DWORD value with the name of the policy
122  4. Set the value to 0 (disabled) or 1 (enabled)
123  5. Restart PowerToys to see the effect
124  
125  For user-scope policies, use `HKEY_CURRENT_USER\SOFTWARE\Policies\Microsoft\PowerToys` instead.