Merge pull request #5232 from MicrosoftDocs/cinnamon/pt-cmd-pal

Add Command Palette to PowerToys

Author: alvinashcraft

hub/dev-environment/toc.yml

@@ -0,0 +1,67 @@
+---
+title: Add top-level commands to your extension
+description: Learn how to add new top-level commands to your Command Palette extension.
+ms.date: 3/23/2025
+ms.topic: how-to
+no-loc: [PowerToys, Windows, Insider]
+# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
+---
+
+# Adding top-level commands to your extension
+
+**Previous**: [Update a list of commands](update-a-list-of-commands.md).
+
+So far, you'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. 
+
+## Adding the top-level commands
+
+To do that, head on over to the `ExtensionNameCommandsProvider.cs` file. This file is where you'll add commands that should be shown at the top-level of the Command Palette. As you can see, there's currently only a single item there:
+
+```csharp
+public ExtensionNameCommandsProvider()
+{
+    DisplayName = "My sample extension";
+    Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
+    _commands = [
+        new CommandItem(new ExtensionNamePage()) { Title = DisplayName },
+    ];
+}
+
+public override ICommandItem[] TopLevelCommands()
+{
+    return _commands;
+}
+```
+
+This sample extension creates a list of commands when the extension is created and returns that list whenever it's asked for the top-level commands. This prevents the extension from re-creating the list of commands every time the top-level commands are requested. This is a performance optimization.
+
+If you want to add another command to the top-level list of commands, you can add another **CommandItem**:
+
+```csharp
+public ExtensionNameCommandsProvider()
+{
+    DisplayName = "My sample extension";
+    Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
+    _commands = [
+        new CommandItem(new ExtensionNamePage()) { Title = DisplayName },
+        new CommandItem(new ShowMessageCommand()) { Title = "Send a message" },
+    ];
+}
+```
+
+There you have it. Now you can add additional top-level commands to your extension.
+
+If you'd like to update the list of top-level commands dynamically, you can do so in the same way as you would update a list page. This can be useful for cases like an extension that might first require the user to log in, before showing certain commands. In that case, you can show the "log in" command at the top level initially. Then, once the user logs in successfully, you can update the list of top-level commands to include the commands that required authentication.
+
+Once you've determined that you need to change the top level list, call [RaiseItemsChanged](./microsoft-commandpalette-extensions-toolkit/commandprovider_raiseitemschanged.md) on your **CommandProvider**. Command Palette will then request the top-level commands via **TopLevelCommands** again, and you can return the updated list.
+
+> [!TIP]
+> Create the **CommandItem** objects for the top-level commands before calling **RaiseItemsChanged**. This will ensure that the new commands are available when Command Palette requests the top-level commands. This will ensure that the work being executed in each call to **TopLevelCommands** method to a minimum.
+
+### Next up: [Command Results](command-results.md)
+
+## Related content
+
+- [PowerToys Command Palette utility](overview.md)
+- [Extensibility overview](extensibility-overview.md)
+- [Extension samples](samples.md)

hub/images/command-palette/create-extension-page.png

@@ -0,0 +1,173 @@
+---
+title: Adding commands to your extension
+description: Learn how to add new commands to your Command Palette extension.
+ms.date: 3/23/2025
+ms.topic: how-to
+no-loc: [PowerToys, Windows, Insider]
+# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
+---
+
+# Adding commands to your extension
+
+**Previous**: [Creating an extension](creating-an-extension.md). We'll be starting with the project created in that article.
+
+Now that you've created your extension, it's time to add some commands to it.
+
+## Add some commands
+
+We can start by navigating to the `ExtensionNamePage.cs` file. This file is the [ListPage](./microsoft-commandpalette-extensions-toolkit/listpage.md) that will be displayed when the user selects your extension. In there you should see:
+
+```csharp   
+public ExtensionNamePage()
+{
+    Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
+    Title = "My sample extension";
+    Name = "Open";
+}
+public override IListItem[] GetItems()
+{
+    return [
+        new ListItem(new NoOpCommand()) { Title = "TODO: Implement your extension here" }
+    ];
+}
+```
+
+Here you can see that we've set the icon for the page, the title, and the name that's shown at the top-level when you have the command selected. The **GetItems** method is where you'll return the list of commands that you want to show on this page. Right now, that's just returning a single command that does nothing. Let's instead try making that command open _this_ page in the user's default web browser.
+
+We can change the implementation of **GetItems** to the following:
+
+```csharp
+public override IListItem[] GetItems()
+{
+    var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/adding-commands");
+    return [
+        new ListItem(command)
+        {
+            Title = "Open the Command Palette documentation",
+        }
+    ];
+}
+```
+
+Re-deploy your app, run the "reload" command to refresh the extensions in the palette, and head to your extension. You should see that the command now opens the Command Palette documentation. 
+
+The **OpenUrlCommand** is a helper for opening a URL in the user's default web browser. You can also implement an extension however you want. Let's instead make a new command, that shows a **MessageBox**. To do that, we need to create a new class that implements **IInvokableCommand**.
+
+```csharp
+using System.Runtime.InteropServices;
+
+namespace ExtensionName;
+
+internal sealed partial class ShowMessageCommand : InvokableCommand
+{
+    public override string Name => "Show message";
+    public override IconInfo Icon => new("\uE8A7");
+
+    public override CommandResult Invoke()
+    {
+        // 0x00001000 is MB_SYSTEMMODAL, which will display the message box on top of other windows.
+        _ = MessageBox(0, "I came from the Command Palette", "What's up?", 0x00001000);
+        return CommandResult.KeepOpen();
+    }
+
+
+    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
+    public static extern int MessageBox(IntPtr hWnd, string text, string caption, uint type);
+}
+```
+
+Now we can add this command to the list of commands in the `ExtensionNamePage.cs` file:
+
+```csharp
+public override IListItem[] GetItems()
+{
+    var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
+    var showMessageCommand = new ShowMessageCommand();
+    return [
+        new ListItem(command)
+        {
+            Title = "Open the Command Palette documentation",
+        },
+        new ListItem(showMessageCommand),
+    ];
+}
+```
+
+Deploy and reload, and presto - a command to show a message box!
+
+> [!TIP]
+> At about this point, you'll probably want to initialize a git repo / {other source control method of your choice} for your project. This will make it easier to track changes, and to share your extension with others.
+> 
+> We recommend using GitHub, as it's easy to collaborate on your extension with others, and get feedback, and share it with the world.
+
+## Adding more pages
+
+So far, we've only worked with commands that "do something". However, you can also add commands that show additional pages withing the Command Palette. There are basically two types of "Commands" in the Palette:
+- **IInvokableCommand** - These are commands that *do something*.
+- **IPage** - These are commands that *show something*.
+
+Because **IPage** implementations are **ICommand**'s, you can use them anywhere you can use commands. This means you can add them to the top-level list of commands, or to a list of commands on a page, the context menu on an item, etc. 
+
+There are two different kinds of pages you can show:
+- [ListPage](./microsoft-commandpalette-extensions-toolkit/listpage.md) - This is a page that shows a list of commands. This is what we've been working with so far.
+- [ContentPage](./microsoft-commandpalette-extensions-toolkit/contentpage.md) - This is a page that shows rich content to the user. This allows you to specify abstract content, and let Command Palette worry about rendering the content in a native experience. There are two different types of content supported so far:
+  - [Markdown content](./using-markdown-content.md) - This is content that's written in Markdown, and is rendered in the Command Palette. See [MarkdownContent](./microsoft-commandpalette-extensions-toolkit/markdowncontent.md) for details.
+  - [Form content](./using-form-pages.md) - This is content that shows a form to the user, and then returns the results of that form to the extension. These are powered by [Adaptive Cards](https://aka.ms/adaptive-cards) This is useful for getting user input, or displaying more complex layouts of information. See [FormContent](./microsoft-commandpalette-extensions-toolkit/formcontent.md) for details.
+
+
+Start by adding a new page that shows a list of commands. Create a new class that implements **ListPage**:
+
+```csharp
+using Microsoft.CommandPalette.Extensions.Toolkit;
+using System.Linq;
+
+namespace ExtensionName;
+
+internal sealed partial class MySecondPage : ListPage
+{
+    public MySecondPage()
+    {
+        Icon = new("\uF147"); // Dial2
+        Title = "My second page";
+        Name = "Open";
+    }
+
+    public override IListItem[] GetItems()
+    {
+        // Return 100 CopyText commands
+        return Enumerable
+            .Range(0, 100)
+            .Select(i => new ListItem(new CopyTextCommand($"{i}")) 
+            {
+                Title = $"Copy text {i}" 
+            }).ToArray();
+    }
+}
+```
+
+Next, update the `ExtensionNamePage.cs` to include this new page:
+
+```diff
+    public override IListItem[] GetItems()
+    {
+        OpenUrlCommand command = new("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
+        return [
+            new ListItem(command)
+            {
+                Title = "Open the Command Palette documentation",
+            },
+            new ListItem(new ShowMessageCommand()),
++            new ListItem(new MySecondPage()) { Title = "My second page", Subtitle = "A second page of commands" },
+        ];
+    }
+```
+
+Deploy, reload, and you should now see a new page in your extension that shows 100 commands that copy a number to the clipboard.
+
+### Next up: [Update a list of commands](update-a-list-of-commands.md)
+
+## Related content
+
+- [PowerToys Command Palette utility](overview.md)
+- [Extensibility overview](extensibility-overview.md)
+- [Extension samples](samples.md)

hub/images/command-palette/initial-created-extension-list.png

@@ -0,0 +1,114 @@
+---
+title: Command results
+description: Learn what the different kinds of Command Palette command results do.
+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)
+
+An [IInvokableCommand](./microsoft-commandpalette-extensions/iinvokablecommand.md) is a fundamental unit 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 type 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 command result
+
+The **KeepOpen** 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 command result
+
+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 command result
+
+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 command result
+
+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 command result
+
+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 command result
+
+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 command result
+
+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)