microsoft
[API Spec] SplitMenuFlyoutItem control
This is an API Spec PR for the proposed SplitMenuFlyoutItem control.
PR Type
Please check the type of change your PR introduces:
- [ ] Bugfix
- [ ] Feature
- [ ] Code style update (formatting, renaming)
- [ ] Refactoring (no functional changes, no api changes)
- [ ] Build related changes
- [ ] Documentation content changes
- [x] Other (please describe):
Description
The SplitMenuFlyoutItem control is proposed to be a new addition to the WinUI library, designed to provide a split button experience within a menu flyout. This control derives from MenuFlyoutItem and introduces a dual-button interface consisting of a primary button and a flyout button.
Motivation and Context
This functionality will allow developers to expose a default primary action while also offering additional options through an attached dropdown — ideal for condensing complex functionality into a smaller footprint and saving overall menu length.
How Has This Been Tested?
- [ ] I have performed a self-review of my own code
- [ ] I have added tests to cover my changes
Screenshots (if appropriate):
Attached in the document.
I've added this to the public api review process board: https://aka.ms/winappsdk/api-specs-review
This PR will be open for feedback for a month from its opening: October 30th – November 30th
FYI @dipeshmsft
Please consider referencing all resources in XAML with ThemeResource, even values like thickness, height etc. This allows users to overwrite resources for lightweight styling. See https://github.com/microsoft/microsoft-ui-xaml/issues/6945
For example, MenuFlyoutItemThemePaddingNarrow, SplitMenuFlyoutItemSeparatorHeight, SplitMenuFlyoutItemChevronButtonWidth, MenuFlyoutItemChevronMargin seem to be referenced as StaticResource right now. https://github.com/microsoft/microsoft-ui-xaml/compare/3e4702cebee3cb23062b90745c70476758678add...b05521d306c6c5ab749593998c954eac3cec81e2#diff-2ded3dd0ba19e54f4d02039304a6094d2945899e86e8e039e91af5d738da83c9R602
I have UX concerns about the current proposal/implementation where the context menu item reads "Compress to ZIP" but opens a sub-menu with alternative formats (7z, tar.gz, etc.).
The chevron (>) establishes a visual contract that the sub-menu contains sub-options or refinements of the parent item. However, this control actually presents alternative actions that contradict the parent label. When users see "Compress to ZIP >", they reasonably expect ZIP-related options (compression levels, encryption, split archives), not completely different formats.
Example: Imagine a context menu item labeled "Email to John >" that opens a sub-menu with "Slack John", "Call John", "Text John". While all communicate with John, the parent item explicitly promised email.
Are there existing Windows patterns or any other examples to support this "specific action > alternative actions" model that I'm not aware of?
If this control is already in experimental3, which is already in the pipeline for release, what impact will this PR really have?
@riverar
I have UX concerns about the current proposal/implementation where the context menu item reads "Compress to ZIP" but opens a sub-menu with alternative formats (7z, tar.gz, etc.). The chevron (>) establishes a visual contract that the sub-menu contains sub-options or refinements of the parent item. However, this control actually presents alternative actions that contradict the parent label. When users see "Compress to ZIP >", they reasonably expect ZIP-related options (compression levels, encryption, split archives), not completely different formats.
"Compress to ZIP" scenario may not be the best scenario for SplitMenuFlyoutItem and maybe more suited for MenuFlyoutSubItem.
I would like to draw your attention to the Paste example, where there are different ways of performing the paste - "Paste as Text", "Paste with Merge Formatting", "Paste with Source Formatting", etc. This is one of the true examples of what we are trying to achieve using this control. If there are multiple ways of performing one operation and the app developer wants to set one as the default mode operation, those scenarios are the ones that we are trying to support using this control.
In the example of having a menu item "Email to John" and then inside that command having sub-menu items like "Slack to John", "Call John", this is geared towards the default mode of action for a user. Say it is by mail, so we show that in the primary part, and other parts of making contact are secondary, so they are put in the sub menu item.
However, I think the control is general enough to support both the cases : having alternate actions grouped together, and handling different variations of the same action.
In the light of the confusion this is creating I will go ahead and modify the usage examples in the API spec.
If this control is already in experimental3, which is already in the pipeline for release, what impact will this PR really have?
@riverar, we have done 2 passes on internal review for this control, however since this is still in experimental, we are open to suggestions.
@Jay-o-Way
I just wanna say that this document does not follow MS Learn style/formatting guidelines.
This document follows the API Spec template provided in the repo: https://github.com/microsoft/WindowsAppSDK/blob/main/specs/spec_template.md
I will take a look at rest of the formatting issues and update the spec accordingly.
This document follows the API Spec template provided in the repo:
😂 Hasn't been touched in at least 5 years though...
@dipeshmsft Does it support KeyboardAccelerators? I don't see it mentioned here and no screenshot, too
@dipeshmsft
"Compress to ZIP" scenario may not be the best scenario for SplitMenuFlyoutItem and maybe more suited for MenuFlyoutSubItem.
I would like to draw your attention to the Paste example, where there are different ways of performing the paste - "Paste as Text", "Paste with Merge Formatting", "Paste with Source Formatting", etc. This is one of the true examples of what we are trying to achieve using this control. If there are multiple ways of performing one operation and the app developer wants to set one as the default mode operation, those scenarios are the ones that we are trying to support using this control.
That makes more sense, thank you.
In the example of having a menu item "Email to John" and then inside that command having sub-menu items like "Slack to John", "Call John", this is geared towards the default mode of action for a user. Say it is by mail, so we show that in the primary part, and other parts of making contact are secondary, so they are put in the sub menu item.
I don't think this scenario makes sense, unless "Email to John" is renamed to, say, "Tell John" with sub-menu items "Tell John via Email", "Tell John via SMS", etc.
In the light of the confusion this is creating I will go ahead and modify the usage examples in the API spec.
Thanks, I checked and didn't see new images/examples. Are you still working on that?
Thanks, I checked and didn't see new images/examples. Are you still working on that?
After further discussion, we decided to remove the scenario as an example for this control.
@d2phap Keyboard accelerator is supported here. However, the visibility is disabled by default. However, visibility as a tooltip can be enabled at the developer's end.
@dipeshmsft I hope it has an option to show the hotkey, customize the hotkey text, similar to the WinForms's MenuStrip:
Feedback gathering date for this PR has passed; what's the status?
Ping @dipeshmsft
Feedback gathering date for this PR has passed; what's the status?
Based on the comments and discussion, I don't think there are any changes required in the API. Hence I will go ahead and close the PR. I will update the spec with the updated content.
Why are we waiting for @Jay-o-Way? Bit confused about the state of this PR.
Why are we waiting for @Jay-o-Way? Bit confused about the state of this PR.
We have merged the PR. I was a bit of confused regarding the process here.