Mirrors/PowerToys
1
0
Fork 0
mirror of https://github.com/microsoft/PowerToys.git synced 2025-12-16 11:48:06 +01:00
Code Issues Packages Projects Releases Wiki Activity

Replace ASCII diagrams with Mermaid in documentation

Browse Source 
Updated `host-settings-awareness.md` to replace outdated ASCII art diagrams with modern `mermaid` diagrams for improved readability and maintainability.

- Replaced the high-level architecture overview with a `mermaid` flowchart to better illustrate component relationships and cross-process communication.
- Replaced the initial settings delivery process diagram with a `mermaid` sequence diagram, detailing the flow for both OOP extensions and built-in commands.
- Replaced the settings change notification diagram with a `mermaid` sequence diagram, showing the propagation of settings changes and UI updates in extensions.

These changes enhance the clarity and visual appeal of the documentation, making it easier for developers to understand the processes.
This commit is contained in:
Yu Leng
2025-11-26 16:23:36 +08:00
parent a75d9fb9a0
commit ffe69f7a99
1 changed files with 71 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
src/modules/cmdpal/doc/host-settings-awareness/host-settings-awareness.md
View File

@@ -86,47 +86,28 @@ Some extensions may want to provide experiences that align with the host's confi
### Architecture Overview ### Architecture Overview
``` ```mermaid
┌─────────────────────────────────────────────────────────────────┐ flowchart TB
│ Command Palette Host │ subgraph Host["Command Palette Host"]
│ ┌─────────────────┐ ┌──────────────────┐ │ SM[SettingsModel]
│ │ SettingsModel │───▶│HostSettingsConv- │ │ HSC[HostSettingsConverter]
│ │ │ │ erter │ │ ES["ExtensionService<br/>NotifyHostSettingsChanged(IHostSettings)"]
│ └────────┬────────┘ └────────┬─────────┘ │
│ │ │ │ SM -->|SettingsChanged| ES
│ │SettingsChanged │ IHostSettings │ SM --> HSC
│ ▼ ▼ │ HSC -->|IHostSettings| ES
│ ┌─────────────────────────────────────────────────┐ │ end
│ │ ExtensionService │ │
│ │ NotifyHostSettingsChanged(IHostSettings) │ │ ES -->|"Cross-Process (COM/WinRT)"| CP
│ └────────────────────┬────────────────────────────┘ │
│ │ │ subgraph Extension["Extension Process"]
└───────────────────────┼──────────────────────────────────────────┘ CP["CommandProvider<br/>OnHostSettingsChanged(IHostSettings)"]
│ Cross-Process (COM/WinRT) HSM["HostSettingsManager<br/>━━━━━━━━━━━━━━━━━━━━<br/>Current: IHostSettings<br/>SettingsChanged: event Action"]
▼ EPC["Extension Pages / Commands<br/>(Subscribe to HostSettingsManager.SettingsChanged<br/>or read Current)"]
┌───────────────────────────────────────────────────────────────────┐
│ Extension Process │ CP --> HSM
│ ┌────────────────────────────────────────────────┐ │ HSM --> EPC
│ │ CommandProvider │ │ end
│ │ OnHostSettingsChanged(IHostSettings settings) │ │
│ └────────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────┐ │
│ │ HostSettingsManager │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ Current: IHostSettings │ │ │
│ │ │ SettingsChanged: event Action │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ └────────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────┐ │
│ │ Extension Pages / Commands │ │
│ │ (Subscribe to HostSettingsManager. │ │
│ │ SettingsChanged or read Current) │ │
│ └────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘
``` ```
### Key Components ### Key Components
@@ -451,100 +432,61 @@ This design ensures:
This diagram shows how initial host settings are delivered to extensions when they first load: This diagram shows how initial host settings are delivered to extensions when they first load:
``` ```mermaid
┌─────────────────────┐ ┌─────────────────────────┐ ┌────────────────────┐ ┌─────────────────┐ sequenceDiagram
│TopLevelCommandManager│ │CommandProviderWrapper │ │ExtensionWrapper │ │Extension Process│ participant TLCM as TopLevelCommandManager
└──────────┬──────────┘ └────────────┬────────────┘ └─────────┬──────────┘ └────────┬────────┘ participant CPW as CommandProviderWrapper
│ │ │ │ participant EW as ExtensionWrapper
│ LoadTopLevelCommandsFromProvider() │ │ participant EP as Extension Process
│─────────────────────────▶│ │ │
│ │ │ │ TLCM->>CPW: LoadTopLevelCommandsFromProvider()
│ │ LoadTopLevelCommands() │ │ CPW->>EW: LoadTopLevelCommands()
│ │────────────────────────▶│ │ EW-->>CPW: (commands loaded)
│ │ │ │
│ │◀────────────────────────│ │ CPW->>CPW: SendInitialHostSettings()<br/>Get settings
│ │ │ │
│ │ SendInitialHostSettings() │ alt OOP Extension
│ │──────┐ │ │ CPW->>EW: NotifyHostSettingsChanged(settings)
│ │ │ Get settings │ │ EW->>EP: GetApiExtensionStubs()
│ │◀─────┘ │ │ EP-->>EW: [stubs array]
│ │ │ │ EW->>EP: OnHostSettingsChanged(settings)
│ │ [OOP Extension] │ │ EP->>EP: HostSettingsManager.Update(settings)
│ │ NotifyHostSettingsChanged(settings) │ else Built-in Command
│ │────────────────────────▶│ │ CPW->>EP: OnHostSettingsChanged(settings)<br/>(direct call)
│ │ │ │ EP->>EP: HostSettingsManager.Update(settings)
│ │ │ GetApiExtensionStubs() end
│ │ │─────────────────────▶│
│ │ │ │ CPW-->>TLCM: (complete)
│ │ │◀─────────────────────│
│ │ │ [stubs array] │
│ │ │ │
│ │ │ OnHostSettingsChanged(settings)
│ │ │─────────────────────▶│
│ │ │ │
│ │ │ │ HostSettingsManager
│ │ │ │ .Update(settings)
│ │ │ │──────┐
│ │ │ │ │
│ │ │ │◀─────┘
│ │ │ │
│ │ [Built-in Command] │ │
│ │ OnHostSettingsChanged(settings) (direct call) │
│ │───────────────────────────────────────────────▶│
│ │ │ │
│◀─────────────────────────│ │ │
│ │ │ │
``` ```
### Settings Change Notification ### Settings Change Notification
This diagram shows how settings changes are propagated to all extensions: This diagram shows how settings changes are propagated to all extensions:
``` ```mermaid
┌───────────┐ ┌────────────┐ ┌────────────────┐ ┌─────────────────┐ ┌─────────────────┐ sequenceDiagram
│ User │ │SettingsModel│ │ExtensionService│ │ExtensionWrapper │ │Extension Process│ participant User
└─────┬─────┘ └──────┬─────┘ └───────┬────────┘ └────────┬────────┘ └────────┬────────┘ participant SM as SettingsModel
│ │ │ │ │ participant ES as ExtensionService
│ Change setting│ │ │ │ participant EW as ExtensionWrapper
│──────────────▶│ │ │ │ participant EP as Extension Process
│ │ │ │ │
│ │ SettingsChanged event │ │ User->>SM: Change setting
│ │───────────────▶│ │ │ SM->>ES: SettingsChanged event
│ │ │ │ │
│ │ │ ToHostSettings() │ │ ES->>ES: ToHostSettings()<br/>Convert settings
│ │ │──────┐ │ │
│ │ │ │ Convert │ │ ES->>EW: NotifyHostSettingsChanged(settings)
│ │ │◀─────┘ │ │
│ │ │ │ │ loop For each extension
│ │ │ NotifyHostSettingsChanged(settings) │ EW->>EP: GetApiExtensionStubs()
│ │ │───────────────────▶│ │ EP-->>EW: [stubs array]
│ │ │ │ │ EW->>EP: OnHostSettingsChanged(settings)
│ │ │ [For each extension] │
│ │ │ │ │ EP->>EP: HostSettingsManager.Update(settings)
│ │ │ │ GetApiExtensionStubs() EP->>EP: SettingsChanged event fired
│ │ │ │───────────────────▶│ EP->>EP: Extension pages update UI
│ │ │ │ │ end
│ │ │ │◀───────────────────│
│ │ │ │ [stubs array] │
│ │ │ │ │
│ │ │ │ OnHostSettingsChanged(settings)
│ │ │ │───────────────────▶│
│ │ │ │ │
│ │ │ │ │ HostSettingsManager
│ │ │ │ │ .Update(settings)
│ │ │ │ │──────┐
│ │ │ │ │ │
│ │ │ │ │◀─────┘
│ │ │ │ │
│ │ │ │ │ SettingsChanged
│ │ │ │ │ event fired
│ │ │ │ │──────┐
│ │ │ │ │ │
│ │ │ │ │◀─────┘
│ │ │ │ │
│ │ │ │ │ Extension pages
│ │ │ │ │ update UI
│ │ │ │ │
``` ```
## Example Usage ## Example Usage