Docs through CommandResult

Author: zadjii

hub/dev-environment/toc.yml

@@ -133,6 +133,8 @@ items:
               items:
                 - name: Creating an extension  
                   href: ../powertoys/command-palette/creating-an-extension.md
+                - name: Adding commands  
+                  href: ../powertoys/command-palette/adding-commands.md
                 - name: Update a list of commands
                   href: ../powertoys/command-palette/update-a-list-of-commands.md
                 - name: Command results
@@ -143,10 +145,10 @@ items:
                   href: ../powertoys/command-palette/using-markdown-content.md
                 - name: Get user input with forms
                   href: ../powertoys/command-palette/using-form-pages.md
-                - name: Handle the search text
-                  href: ../powertoys/command-palette/dynamic-lists.md
-                - name: "Advanced: Adding an extension to your package" 
-                  href: ../powertoys/command-palette/adding-an-extension-to-your-package.md
+                # - name: Handle the search text
+                #   href: ../powertoys/command-palette/dynamic-lists.md
+                # - name: "Advanced: Adding an extension to your package" 
+                #   href: ../powertoys/command-palette/adding-an-extension-to-your-package.md
             - name: Publishing your extension
               href: ../powertoys/command-palette/publish-extension.md
             - name: Extension samples

hub/powertoys/command-palette/add-top-level-commands-to-your-extension.md

@@ -9,7 +9,7 @@ no-loc: [PowerToys, Windows, Insider]
 
 # Adding top-level commands
 
-**Previous**: [Command Results](command-results.md)
+**Previous**: [Update a list of commands](update-a-list-of-commands.md).
 
 So far, we've only added commands to a single page, within your extension. You can also add more commands directly to the top-level list of commands too. 
 
@@ -57,7 +57,7 @@ Once you've determined that you need to change the top level list, call [`RaiseI
 > [!TIP]
 > Create the `CommandItem`s for the top-level commands before calling `RaiseItemsChanged()`. This will ensure that the new commands are available when Command Palette asks for the top-level commands. This will help keep the work being done in call to `TopLevelCommands()` method to a minimum.
 
-### Next up: [Display markdown content](using-markdown-content.md)
+### Next up: [Command Results](command-results.md)
 
 ## Related content
 

hub/powertoys/command-palette/command-results.md

@@ -0,0 +1,115 @@
+---
+title: Command results
+description: Learn how to add new commands to your Command Palette extension.
+ms.date: 3/23/2025
+ms.topic: concept-article
+no-loc: [PowerToys, Windows, Insider]
+# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
+---
+
+# Command results
+
+**Previous**: [Add top-level commands to your extension](add-top-level-commands-to-your-extension.md)
+
+
+[`IInvokableCommand`](./microsoft-commandpalette-extensions/iinvokablecommand.md)s are the fundamental units of "do something" in the Command Palette. The [`Invoke`](./microsoft-commandpalette-extensions/iinvokablecommand.md) method is called when the user selects the command, and it's where you _do something_ in your extension. The `Invoke` method returns an `ICommandResult`, which tells the Command Palette what to do after the command has been invoked. This page details what's possible with each kind of command result.
+
+The toolkit provides a number of helper methods to create command results. These are all static methods on the `CommandResult` class. Calling these methods on their own won't do anything - you must return those objects as the result of a `Invoke` method, for Command Palette to handle them. 
+
+<!-- GoToPage currently omitted from these docs, because it's not remotely implemented -->
+
+## `KeepOpen`
+
+This command result does nothing. It leaves the palette in its current state, with the current page stack and query. This can be useful for commands that want to keep the the user in the Command Palette, to keep working with the current page.
+
+> [!NOTE]
+> Even when returing `KeepOpen`, launching a new app or window from the Command Palette will automatically hide the palette the next window recieves focus. 
+
+## `Hide`
+
+This command result keeps the current page open, but hides the Command Palette. This can be useful for commands that want to take the user briefly out of the Command Palette, but then come back to this context. 
+
+## `GoBack`
+
+This result takes the user back a page in the Command Palette, and keeps the window visible. This is perfect for form pages, where doing the command should take you the user back to the previous context.
+
+## `GoHome`
+
+This result takes the user back to the main page of the Command Palette. It will leave the Palette visible (unless the palette otherwise loses focus). Consider using this for scenarios where you've changed your top-level commands. 
+
+## `Dismiss`
+
+This result hides the Command Palette after the action is executed, and takes it back to the hme page. On the next launch, the Command Palette will start from the main page with a blank query. This is useful for commands that are one-off actions, or that don't need to keep the Command Palette open. 
+
+If you don't know what else to use, this should be your default. Ideally, users should come into the palette, find what they need, and be done with it. 
+
+## `ShowToast`
+
+This result displays a transient desktop-level message to the user. This is especially useful for displaying confirmation that an action took place when the palette will be closed. 
+
+Consider the [CopyTextCommand](../microsoft-commandpalette-extensions-toolkit/copytextcommand.md) in the helpers - this command will show a toast with the text "Copied to clipboard", then dismiss the palette. 
+
+By default, [`CommandResult.ShowToast(string)`](./microsoft-commandpalette-extensions-toolkit/commandresult_showtoast_string.md) helper will have a `Result` of `CommandResult.Dismiss`. However, you can instead change the result to any of the other results if you want. This allows you to display a toast and keep the palette open, if you'd like. 
+
+## `Confirm`
+
+This result displays a confirmation dialog to the user. If the user confirms the dialog, then the `PrimaryCommand` of the `ConfirmationArgs` will be performed. 
+
+This is useful for commands that might have destructive actions, or that need to confirm user intent.
+
+## Example
+
+As an example, here's a page with one command for each kind of command result:
+
+```csharp
+
+using Microsoft.CommandPalette.Extensions.Toolkit;
+
+internal sealed partial class CommandResultsPage : ListPage
+{
+    public CommandResultsPage()
+    {
+        Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
+        Title = "Example command results";
+        Name = "Open";
+    }
+
+    public override IListItem[] GetItems()
+    {
+        ConfirmationArgs confirmArgs = new()
+        {
+            PrimaryCommand = new AnonymousCommand(
+                () =>
+                {
+                    ToastStatusMessage t = new("The dialog was confirmed");
+                    t.Show();
+                })
+            {
+                Name = "Confirm",
+                Result = CommandResult.KeepOpen(),
+            },
+            Title = "You can set a title for the dialog",
+            Description = "Are you really sure you want to do the thing?",
+        };
+
+        return
+        [
+            new ListItem(new AnonymousCommand(null) { Result = CommandResult.KeepOpen() }) { Title = "Keep the palette open" },
+            new ListItem(new AnonymousCommand(null) { Result = CommandResult.Hide() }) { Title = "Hide the palette" },
+            new ListItem(new AnonymousCommand(null) { Result = CommandResult.GoBack() }) { Title = "Go back" },
+            new ListItem(new AnonymousCommand(null) { Result = CommandResult.GoHome() }) { Title = "Go home" },
+            new ListItem(new AnonymousCommand(null) { Result = CommandResult.Dismiss() }) { Title = "Dismiss the palette" },
+            new ListItem(new AnonymousCommand(null) { Result = CommandResult.ShowToast("What's up") }) { Title = "Show a toast" },
+            new ListItem(new AnonymousCommand(null) { Result = CommandResult.Confirm(confirmArgs) }) { Title = "Confirm something" },
+        ];
+    }
+}
+```
+
+### Next up: [Display markdown content](using-markdown-content.md)
+
+## Related content
+
+- [PowerToys Command Palette utility](overview.md)
+- [Extensibility overview](extensibility-overview.md)
+- [Extension samples](samples.md)

hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandprovider_raiseitemschanged.md

@@ -14,6 +14,7 @@ Namespace: [Microsoft.CommandPalette.Extensions.Toolkit](microsoft-commandpalett
 
 The **RaiseItemsChanged** method raises the **ItemsChanged** event with the specified change type. This method is typically used to notify the Command Palette of changes in the command provider's items, such as when new commands are added or existing commands are removed.
 
+
 <!-- ## Parameters
 
 *totalItems* **Int**

hub/powertoys/command-palette/update-a-list-of-commands.md

@@ -143,7 +143,7 @@ internal void Increment()
 
 Best practice is to set `IsLoading` to `true` before starting the work. Then do all the work to build all the new `ListItems` you need to display to the user. Then, once the items are ready, call `RaiseItemsChanged` and set `IsLoading` back to `false`. This will ensure that the loading spinner is shown for the entire duration of the work, and that the UI is updated as soon as the work is done (without waiting for your extension to construct new `ListItem` objects).
 
-### Next up: [Command results](command-results.md)
+### Next up: [Add top-level commands to your extension](add-top-level-commands-to-your-extension.md)
 
 ## Related content