diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 0903ec5a84..bd03c954ed 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -1,31 +1,43 @@ name: Bug report description: File a bug report title: "Bug title" -labels: [bug] +labels: ["bug", "needs-triage"] +type: Bug body: - - type: markdown - attributes: - value: | - For bugs related to UWP or the app models, please open a bug on the [Windows App SDK repository](https://github.com/microsoft/WindowsAppSDK) - type: textarea validations: required: true attributes: label: Describe the bug - description: Please enter a short, clear description of the bug. + description: In a few sentences, please enter a short, clear description of the bug. + placeholder: E.g. When clicking on a togggle button, '...' happens instead of '...' when '...' is enabled. + - type: textarea + validations: + required: true + attributes: + label: Why is this important? + description: Please provide the impact/scenario of this issue to yourself or the end-user of an application. What is it that is trying to be accomplished that this bug prevents from happening? (For context, this helps us understand if this is the root issue of your problem. See https://xyproblem.info/ for more info.) + placeholder: E.g. My user needs to click on the toggle button to switch the state of our setting, but we're not seeing our ViewModel update in this scenario. Their environment needs to be '...' as they're in another locale. - type: textarea validations: required: true attributes: label: Steps to reproduce the bug - description: Please provide any required setup and steps to reproduce the behavior. + description: Please provide any required setup and steps to reproduce the behavior. It is best if you can either reproduce the issue in the [WinUI Gallery](https://aka.ms/winuigallery) or create a new WinUI project that minimally reproduces the issue to attach here. (Providing a simple to follow reproduction with an example project, without extraneous code, makes it easier for anyone to quickly reproduce the issue and spend time investigating/fixing the issue over understanding how to reproduce it.) placeholder: | 1. Go to '...' 2. Click on '....' + 3. See issue '...' + - type: textarea + attributes: + label: Actual behavior + description: Please provide a description of what does happen when you follow the repro steps above + placeholder: FooEvent doesn't fire. - type: textarea attributes: label: Expected behavior description: Please provide a description of what you expected to happen + placeholder: FooEvent should fire. - type: textarea attributes: label: Screenshots @@ -35,10 +47,10 @@ body: label: NuGet package version description: If you are seeing your issue on older versions please try the latest release options: - - "WinUI 3 - Windows App SDK 1.6.3: 1.6.241114003" - - "WinUI 3 - Windows App SDK 1.6 Preview 2: 1.6.240821007-preview2" - - "WinUI 3 - Windows App SDK 1.6 Experimental 2: 1.6.240701003-experimental2" - - "WinUI 2 - Microsoft.UI.Xaml 2.8.2" + - "WinUI 3 - Windows App SDK 1.8 Experimental 4: 1.8.250702007-experimental4" + - "WinUI 3 - Windows App SDK 1.7.3: 1.7.250606001" + - "WinUI 3 - Windows App SDK 1.8 Preview 1: 1.8.250814004-preview1" + - "WinUI 2 - Microsoft.UI.Xaml 2.8.7" - type: dropdown attributes: label: Windows version diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..3d8416e339 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Questions about WinUI? + url: https://github.com/microsoft/microsoft-ui-xaml/discussions/categories/q-a + about: I have a question about how to use something in WinUI. + - name: New Idea? + url: https://github.com/microsoft/microsoft-ui-xaml/discussions/categories/ideas + about: Look to see if your idea has been suggested, up-vote it, or start a new conversation here. + - name: WindowsAppSDK + url: https://aka.ms/windowsappsdk + about: For bugs related to UWP, or the app models, please open a bug on the Windows App SDK repository. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_proposal.md b/.github/ISSUE_TEMPLATE/feature_proposal.md deleted file mode 100644 index a6c4cfd102..0000000000 --- a/.github/ISSUE_TEMPLATE/feature_proposal.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: Feature Proposal -about: Suggest a new feature or idea -title: 'Proposal:' -labels: feature proposal -assignees: '' - ---- - - - -# Proposal: [your title here] - - -## Summary - - -## Rationale - -* {First reason for why we should consider this proposal} -* {Second reason for why we should consider this proposal} -* {etc} - - - - -## Scope - -| Capability | Priority | -| :---------- | :------- | -| This proposal will allow developers to accomplish W | Must | -| This proposal will allow end users to accomplish X | Should | -| This proposal will allow developers to accomplish Y | Could | -| This proposal will allow end users to accomplish Z | Won't | - -## Important Notes - - -## Open Questions - diff --git a/.github/ISSUE_TEMPLATE/feature_proposal.yaml b/.github/ISSUE_TEMPLATE/feature_proposal.yaml new file mode 100644 index 0000000000..5569313fe7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_proposal.yaml @@ -0,0 +1,82 @@ +name: Feature Proposal +description: Suggest a new feature +title: "Proposal:" +labels: ["feature proposal", "needs-triage"] +type: Feature +body: + - type: markdown + attributes: + value: | + This is a template for new feature or API proposals. Please search the existing [Ideas discussion](https://github.com/microsoft/microsoft-ui-xaml/discussions/categories/ideas) + and issue list first to see if someone else has made a similar proposal. + + This form should be used if you have a more concrete idea of what to propose or have already discussed an idea in the discussion forum. + + For example you can use this to propose a new API on an existing type, or an idea for a new UI control. + For feature proposals related to UWP or the app models, please open an issue in the [Windows App SDK repository](https://github.com/microsoft/WindowsAppSDK). + + It's fine if you don't have all the details: you can start with the Summary and Rationale. + + This link describes the WinUI feature/API proposal process: + https://github.com/Microsoft/microsoft-ui-xaml/blob/main/docs/feature_proposal_process.md + - type: textarea + validations: + required: true + attributes: + label: Title + description: Please enter a short, clear title for your feature or API proposal. + placeholder: | + e.g. "Add a new property to the X control to control Y" + - type: textarea + validations: + required: true + attributes: + label: Summary + description: Include 1-2 sentences summarizing your feature or API proposal + - type: textarea + validations: + required: true + attributes: + label: Rationale + description: | + Create a list that describes WHY the feature should be added to WinUI for all developers and users. + Proposals often have multiple motives for why we should do the work, so list each one as a separate bullet. + If applicable you can also describe how the proposal aligns to the current WinUI roadmap and priorities in a separate paragraph: + https://github.com/Microsoft/microsoft-ui-xaml/blob/main/docs/roadmap.md + * {First reason for why we should consider this proposal} + * {Second reason for why we should consider this proposal} + * {etc} + - type: textarea + attributes: + label: Scope + description: | + Please include a list of what the feature should and shouldn't do by filling in the table below. + 'Must' implies that the feature should not ship without this capability. + 'Should' is something we should push hard for, but is not absolutely required to ship. + 'Could' is a nice-to-have; a good stretch goal that isn't painful if we don't achieve it. + 'Won't' is a clear statement that the proposal/feature will intentionally not have that capability. + This list will evolve and grow as the proposal becomes more refined over time. + A good rule of thumb is to start your proposal with no more than 7 high-level requirements. + value: | + | Capability | Priority | + | :---------- | :------- | + | This proposal will allow developers to accomplish W | Must | + | This proposal will allow end users to accomplish X | Should | + | This proposal will allow developers to accomplish Y | Could | + | This proposal will allow end users to accomplish Z | Won't | + - type: textarea + attributes: + label: Important Notes + description: | + Please include any other important details. + This could include one or more of: + - usage examples + - an API proposal (any supported language or pseudocode is fine) + - design mockups or example screenshots + - other implementation notes + - type: textarea + attributes: + label: Open Questions + description: | + Please list any open issues that you think still need to be addressed. + These could include areas you think would benefit from community or WinUI team input. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fc4f499e3b..8161ddc971 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,41 @@ +## Fixes ##### + + + +## 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 +- [ ] Other (please describe): + ## Description -## Motivation and Context +### Current Behavior + + +### New Behavior + + +### Motivation and Context ## 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): \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 576f928566..cb7a1c86fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,11 +66,11 @@ file in the repository, as needed. You can also read and contribute to the WinUI documentation here: https://docs.microsoft.com/uwp/toolkits/winui -You can find usage examples of the controls available in WinUI in the Xaml Controls Gallery app: - https://github.com/Microsoft/Xaml-Controls-Gallery/ +You can find usage examples of the controls available in WinUI in the WinUI 3 Gallery app: + https://github.com/Microsoft/WinUI-Gallery/ - which can also be installed from the Windows Store: - https://www.microsoft.com/p/xaml-controls-gallery/9msvh128x2zt + Which can also be installed from the Microsoft Store: + https://apps.microsoft.com/detail/9p3jfpwwdzrc ## API spec discussions diff --git a/README.md b/README.md index fda07e5791..6e7e8f9b71 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,13 @@

- Follow @windowsui + Follow @windowsui

About WinUI · - Source code - · Documentation · Release notes @@ -40,7 +38,6 @@ The full documentation of WinUI can be found on [Microsoft Learn](https://learn. - [Get started with WinUI](https://learn.microsoft.com/windows/apps/get-started/start-here) - [Build your first WinUI app](https://learn.microsoft.com/windows/apps/how-tos/hello-world-winui3) - [WinUI & Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) -- [WinUI source code](https://github.com/microsoft/microsoft-ui-xaml/tree/winui3/release/1.5-stable)
@@ -73,7 +70,7 @@ For information on how to contribute, please see [Contributing to WinUI](CONTRIB ## 🛣️ Roadmap -For info on the WinUI release schedule and high level plans please see the [WinUI Roadmap](https://aka.ms/winappsdk/plans). +For info on the WinUI release schedule and high level plans please see the [WinUI roadmap](https://aka.ms/winappsdk/plans).
diff --git a/docs/images/header.png b/docs/images/header.png index 735224498c..a655023c74 100644 Binary files a/docs/images/header.png and b/docs/images/header.png differ diff --git a/docs/images/winui-gallery.png b/docs/images/winui-gallery.png index 606bb9041c..e9f4113c0f 100644 Binary files a/docs/images/winui-gallery.png and b/docs/images/winui-gallery.png differ diff --git a/docs/images/winuiLogo.png b/docs/images/winuiLogo.png index f9ec1ec524..ac9af493ce 100644 Binary files a/docs/images/winuiLogo.png and b/docs/images/winuiLogo.png differ diff --git a/docs/images/winuiLogo.svg b/docs/images/winuiLogo.svg index 5064dd00c3..49a78693f2 100644 --- a/docs/images/winuiLogo.svg +++ b/docs/images/winuiLogo.svg @@ -1,44 +1,57 @@ - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/winui_os.png b/docs/images/winui_os.png index 795f8b20cb..66525f08c4 100644 Binary files a/docs/images/winui_os.png and b/docs/images/winui_os.png differ diff --git a/specs/TitleBar/images/1p-edge-titlebar.png b/specs/TitleBar/images/1p-edge-titlebar.png new file mode 100644 index 0000000000..e35c63ced7 Binary files /dev/null and b/specs/TitleBar/images/1p-edge-titlebar.png differ diff --git a/specs/TitleBar/images/1p-notepad-titlebar.png b/specs/TitleBar/images/1p-notepad-titlebar.png new file mode 100644 index 0000000000..86753bd839 Binary files /dev/null and b/specs/TitleBar/images/1p-notepad-titlebar.png differ diff --git a/specs/TitleBar/images/1p-store-titlebar-minimal.png b/specs/TitleBar/images/1p-store-titlebar-minimal.png new file mode 100644 index 0000000000..ee37377d52 Binary files /dev/null and b/specs/TitleBar/images/1p-store-titlebar-minimal.png differ diff --git a/specs/TitleBar/images/1p-store-titlebar.png b/specs/TitleBar/images/1p-store-titlebar.png new file mode 100644 index 0000000000..86540f9fee Binary files /dev/null and b/specs/TitleBar/images/1p-store-titlebar.png differ diff --git a/specs/TitleBar/images/1p-teams-titlebar.png b/specs/TitleBar/images/1p-teams-titlebar.png new file mode 100644 index 0000000000..ce919dfd2a Binary files /dev/null and b/specs/TitleBar/images/1p-teams-titlebar.png differ diff --git a/specs/TitleBar/images/1p-terminal-titlebar.png b/specs/TitleBar/images/1p-terminal-titlebar.png new file mode 100644 index 0000000000..4943bdef27 Binary files /dev/null and b/specs/TitleBar/images/1p-terminal-titlebar.png differ diff --git a/specs/TitleBar/images/1p-vscode-titlebar.png b/specs/TitleBar/images/1p-vscode-titlebar.png new file mode 100644 index 0000000000..20cdd9a2b5 Binary files /dev/null and b/specs/TitleBar/images/1p-vscode-titlebar.png differ diff --git a/specs/TitleBar/images/1p-winuigallery-titlebar-minimal.png b/specs/TitleBar/images/1p-winuigallery-titlebar-minimal.png new file mode 100644 index 0000000000..cf884a69b2 Binary files /dev/null and b/specs/TitleBar/images/1p-winuigallery-titlebar-minimal.png differ diff --git a/specs/TitleBar/images/1p-winuigallery-titlebar.png b/specs/TitleBar/images/1p-winuigallery-titlebar.png new file mode 100644 index 0000000000..ef0672f820 Binary files /dev/null and b/specs/TitleBar/images/1p-winuigallery-titlebar.png differ diff --git a/specs/TitleBar/images/controls-titlebar.png b/specs/TitleBar/images/controls-titlebar.png new file mode 100644 index 0000000000..5c9eec8b44 Binary files /dev/null and b/specs/TitleBar/images/controls-titlebar.png differ diff --git a/specs/TitleBar/images/default-titlebar.png b/specs/TitleBar/images/default-titlebar.png new file mode 100644 index 0000000000..2537df8670 Binary files /dev/null and b/specs/TitleBar/images/default-titlebar.png differ diff --git a/specs/TitleBar/images/titlebar-backbutton.png b/specs/TitleBar/images/titlebar-backbutton.png new file mode 100644 index 0000000000..eb85fe32c1 Binary files /dev/null and b/specs/TitleBar/images/titlebar-backbutton.png differ diff --git a/specs/TitleBar/images/titlebar-basic.png b/specs/TitleBar/images/titlebar-basic.png new file mode 100644 index 0000000000..3d41c4557f Binary files /dev/null and b/specs/TitleBar/images/titlebar-basic.png differ diff --git a/specs/TitleBar/images/titlebar-header-icongroup.png b/specs/TitleBar/images/titlebar-header-icongroup.png new file mode 100644 index 0000000000..268a59d549 Binary files /dev/null and b/specs/TitleBar/images/titlebar-header-icongroup.png differ diff --git a/specs/TitleBar/images/titlebar-icon.png b/specs/TitleBar/images/titlebar-icon.png new file mode 100644 index 0000000000..4b39218b66 Binary files /dev/null and b/specs/TitleBar/images/titlebar-icon.png differ diff --git a/specs/TitleBar/images/titlebar-navview-minimal.png b/specs/TitleBar/images/titlebar-navview-minimal.png new file mode 100644 index 0000000000..82e481030a Binary files /dev/null and b/specs/TitleBar/images/titlebar-navview-minimal.png differ diff --git a/specs/TitleBar/images/titlebar-navview.png b/specs/TitleBar/images/titlebar-navview.png new file mode 100644 index 0000000000..13ddde4d79 Binary files /dev/null and b/specs/TitleBar/images/titlebar-navview.png differ diff --git a/specs/TitleBar/images/titlebar-personpicture.png b/specs/TitleBar/images/titlebar-personpicture.png new file mode 100644 index 0000000000..854f05fd34 Binary files /dev/null and b/specs/TitleBar/images/titlebar-personpicture.png differ diff --git a/specs/TitleBar/images/titlebar-search.png b/specs/TitleBar/images/titlebar-search.png new file mode 100644 index 0000000000..55e5f93587 Binary files /dev/null and b/specs/TitleBar/images/titlebar-search.png differ diff --git a/specs/TitleBar/images/titlebar-sizevariant.png b/specs/TitleBar/images/titlebar-sizevariant.png new file mode 100644 index 0000000000..fb54abe472 Binary files /dev/null and b/specs/TitleBar/images/titlebar-sizevariant.png differ diff --git a/specs/TitleBar/images/titlebar-subtitle.png b/specs/TitleBar/images/titlebar-subtitle.png new file mode 100644 index 0000000000..528b865274 Binary files /dev/null and b/specs/TitleBar/images/titlebar-subtitle.png differ diff --git a/specs/TitleBar/images/titlebar-title.png b/specs/TitleBar/images/titlebar-title.png new file mode 100644 index 0000000000..ffc1bad4e1 Binary files /dev/null and b/specs/TitleBar/images/titlebar-title.png differ diff --git a/specs/TitleBar/titleBar-dev-spec.md b/specs/TitleBar/titleBar-dev-spec.md new file mode 100644 index 0000000000..5e019c87f1 --- /dev/null +++ b/specs/TitleBar/titleBar-dev-spec.md @@ -0,0 +1,216 @@ + + + + +# Description + + +The WinUI TitleBar is a title bar control that allows easy additions of WinUI components such as AutoSuggestBox, PersonPicture, and Mica theming. +It is to be used in lieu of the Shell title bar for when developers want more than the basic shell title bar functionalities. + +Current implementations of a custom titlebar involves the developer to fully create a user component from scratch. A notable painpoint in this process is +to manually calculate drag regions for when there are interactive elements in the title bar (ie. AutoSuggestBox - refer to WinUI-Gallery sample). WinUI titleBar is meant +to encapsulate the most common design scenarios and streamline this process. + +# Design considerations + +## AppWindow TitleBar versus WinUI TitleBar + +![Basic TitleBar](images/titlebar-basic.png) + +### AppWindow.TitleBar +The AppWindow TitleBar is the default title bar, and downlevels to Win32. + +AppWindow drawn title bar covers the basic functionalities: +- AppWindow.SetIcon +- AppWindow.Title +- Show Max/Min/Close caption buttons +- Respects theme + +
+ +### WinUI TitleBar +Developers will 'opt-in' to the WinUI TitleBar for updated styling and extended functionalities. + +**Functionalities:** +- HeaderArea (ie. BackButton, PaneToggleButton) +![alt text](images/titlebar-header-icongroup.png) + +- Icon +![alt text](images/titlebar-icon.png) + +- Title +![alt text](images/titlebar-title.png) + +- Subtitle +![alt text](images/titlebar-subtitle.png) + +- ContentArea (ie. AutoSuggestBox) +![alt text](images/titlebar-search.png) + +- FooterArea (ie. PersonPicture) +![alt text](images/titlebar-personpicture.png) + +- Transparency for Mica +- Custom Height - 32px as default / 48px if content != null +![TitleBar Size Variants](images/titlebar-sizevariant.png) + +## Considerations + +- Punch hole through Header / Content / Footer for drag regions. Calculations needs to be updated on SizeChanged. + - Regions with hole punched through are non-draggable. + +- Currently TitleBar treats all custom content as interactable and punches a hole through the drag region. +How can we allow such customizations? + - If we add an `IsInteractive` attached property, that means TitleBar will have to walk through the + entire visual tree to calculate the rects every time. + - Can we call it `InteractiveContent` instead? But this limits the customizability of the control. + - Reference Teams forward / backward button. It is draggable when disabled. + +- Interactive content in TitleBar must also be capable of keyboard navigation. +They should be treated as normal elements in the app's visual tree. + +- TitleBar should meet [Windows app design guidelines](https://learn.microsoft.com/en-us/windows/apps/design/basics/titlebar-design#icon): + - A single-click/tap on the icon should show system window menu. + - A double-click/tap should close the window. + +- CoreApplicationViewTitleBar.LayoutMetricsChanged and IsVisibleChanged events from the UWP world is +missing in WinUI3: + - LayoutMetricsChanged: Update Left and Right Inset for on DPI changes. + Right Inset is used to give placeholder space for the caption buttons in WinUI TitleBar. + - IsVisibleChanged: This is used for when a Window is in full screen mode, + and WinUI TitleBar needs to know when to collapse itself. + - Needs exposed events or dependency property so values can be updated dynamically. + +- Minimum drag region for accessibility (ie. Gap between PersonPicture and CaptionButton for Store) + +- TitleBar behaviour with smoke layer with ContentDialog. Should TitleBar still be draggable +when content dialog is visible? If so, a disable drag bool API is needed. +https://github.com/microsoft/microsoft-ui-xaml/issues/6534 for reference. + +- Flyout needs to be aware of TitleBar dimensions so it can calculate whether it should expand up / down. + + +

+ +![Store TitleBar](images/1p-store-titlebar.png) +![Store TitleBar MinimalMode](images/1p-store-titlebar-minimal.png) + +- AutoSuggestBox to collapse as an icon when in minimal mode. + - Argument for having search as part of titleBar +- MinSize for the apps itself: + - Store has set a MinSize which negates the need to fully collapse its AutoSuggestBox + - Design does give window sizing guidance, but should test for worst case scenario +- Which elements collapses on re-size + - Store collapses Title and Subtitle in minimal mode + +

+ +![WinUI-Gallery TitleBar](images/1p-winuigallery-titlebar.png) +![WinUI-Gallery TitleBar Minimal Mode](images/1p-winuigallery-titlebar-minimal.png) +- Handling of BackButton and PaneToggleButton for NavView + - Collapsing and moving pane toggle button to titlebar in Minimal Mode + +

+ +![Teams TitleBar](images/1p-teams-titlebar.png) +- Ability to add non standard elements such as "<", ">" in content, and other buttons in footer + +

+ +![Visual Studio Code TitleBar](images/1p-vscode-titlebar.png) +- Ability to toggle Header content before or after TitleBar icon? +- _Currently not implemented_ + +# Implementation Details + +## Hole-punching through Non-Client Area +Once TitleBar control is set as the Window titlebar in developer codebehind, the entire region's input is marked as non-client +and becomes non-interactable. We need to punch out a "hole" for each interactable region in TitleBar. +Eg. Header, body, and footer content areas. + +`m_interactableElementsList` +- A list of interactable elements is tracked in the lifetime of the TitleBar. +- The list is updated every time the specified elements' visibility changes. + - eg. `BackButton`, `PaneToggleButton`, `Header`, `Content`, `Footer`. + +`UpdateDragRegion()` +- Called every time `SizeChanged` and `LayoutUpdated` events are fired. +- Checks if `m_interactableElementsList` has children, and if so gets the rects of each element. +- Accesses the `InputNonClientPointerSource` at the IXP layer and set rects as pass through regions. + +_Note: a custom "LayoutUpdated" event needs to be written._ +_The Default LayoutUpdated event fires for every little (non-relevant) events._ + + +# Functional spec link + +[Functional Spec](titlebar-functional-spec.md) + +# Architectural overview + +## Key public components + +TitleBar class + +## Key internal components + +TitleBar TemplateSettings + - Calculate DragRegions + +TitleBarAutomationPeer + +## Gesture recognizer handling + +TitleBar must handle mouse, touch, and keyboard scenarios. + +# Appendix + +## Header, Content, Footer API Naming +Alternate naming considerations for `Header`, `Content`, `Footer`: +- Header and Footer aligns with TabView.TabStripHeader and TabView.TabStripFooter +- Start and End (e.g. [Windows.UI.Xaml.TextAlignment](https://learn.microsoft.com/en-us/uwp/api/windows.ui.xaml?view=winrt-26100)) +- Before and After (e.g. CSS, [Fluent Web UI](https://react.fluentui.dev/?path=/docs/components-input--docs#content-before-after)) +- Leading and Trailing (e.g. [Apple SwiftUI Toolbar](https://developer.apple.com/documentation/swiftui/toolbaritemplacement/topbarleading)) + +## Out of Scope + +### Tabbed TitleBar Scenarios +TitleBar is not needed for TabView scenarios - it may be considered as a separate `TabbedTitleBar` control. + +Below scenarios demonstrate that when Tabview occupies the entire width when extending into title bar. +Header icons, buttons, and drag regions can be handled with TabView Header, and FooterArea. + +![Terminal TitleBar](images/1p-terminal-titlebar.png) +![NotePad TitleBar with TabView](images/1p-notepad-titlebar.png) +![Edge TitleBar](images/1p-edge-titlebar.png) +- No backbutton, no other elements, just tabView +- TabView extends into titlebar takes up the whole window +- TabView needs a property to make space for icon or other elements +- TabView also needs to make space for drag region on right. + - FileExplorer currently has their own implement by setting a drag region and CaptionControl placeholder in TabView.FooterArea + +### AppWindow.TitleBar +Improvements to Window class to allow below syntax. This will greatly cut down the amount of code needed to +configure WinUI TitleBar. + +```xml + + + + + +``` +Ideally, this should also expose TitleBar to below properties and methods: +- Window.Title and AppWindow.Title +- AppWindow.SetIcon() + +This is out of scope for WinUI TitleBar hence will not be included in this spec. + diff --git a/specs/TitleBar/titlebar-functional-spec.md b/specs/TitleBar/titlebar-functional-spec.md new file mode 100644 index 0000000000..03908ec21f --- /dev/null +++ b/specs/TitleBar/titlebar-functional-spec.md @@ -0,0 +1,502 @@ + + + + +TitleBar Functional Spec +=== +_Control category: Basic Input_ + +# Background +Motivations for the TitleBar control include: + +- Achieve parity with Fluent Windows Visual Design Library. +- Bridge the gap between Shell / Win32 title bar and a fully custom Xaml titlebar. +- Simplify the developer experience for implementing the modern title bar. + +# Description + +The title bar is a fundamental component of a Windows app’s user interface. Here are its key features and functionalities: + +1. Display Information: + - The title bar prominently displays the name of the app or document currently open. Users can quickly identify which app they are interacting with. + - Additionally, the title bar may include other relevant information, such as the document title or the current state (e.g., “Editing,” “Viewing,” etc.). +2. Window Controls: + - Minimize Button: Clicking the minimize button (usually represented by an underscore icon) reduces the app window to the taskbar or system tray. + - Maximize Button: Clicking the maximize button (usually represented by a square icon) expands the app window to fill the screen. + - Close Button: Clicking the close button (usually represented by an “X” icon) closes the app window. +3. Drag and Move: + - Users can click and drag the title bar to move the app window around the screen. This allows them to position the window wherever they prefer. +4. Theming and Integration: + - The title bar can be customized to match the app’s visual style using Mica theming. + - It also integrates with other WinUI controls, such as NavigationView, AutoSuggestBox, and PersonPicture, providing a cohesive user experience. + + +# Is this the right control? + +A title bar is a core component of a Windows app, and the shell version of the title bar is shipped with the basic WinUI app template by default. + +Use the WinUI TitleBar when you want further customizations such as subtitles, Mica theming, and integrations with WinUI Controls. + +_Note: WinUI TitleBar does not handle Caption Buttons - it simply allocates space where the caption buttons appear, depending on RTL or LTR settings. +Caption Buttons and its customizations are handled by the AppWindow TitleBar._ + +# Sample scenarios + +## Scenario: Default TitleBar +![alt text](images/default-titlebar.png) + +**XAML** +```xml + + + + + + + + + + + + + + + + +``` + +**C#** +```cs +public MainWindow() +{ + this.InitializeComponent(); + + // C# code to set AppTitleBar UIElement as Titlebar + Window window = this; + window.ExtendsContentIntoTitleBar = true; // Hides the default system titlebar. + window.SetTitleBar(this.DefaultTitleBar); // Replace system titlebar with the WinUI Titlebar. + + // Note: If not title bar is specified, the default system titlebar will be rendered, regardles of the ExtendsContentIntoTitleBar property. +} +``` + +_Note: TitleBar currently needs to be set explicitly in the grid.row and referenced_ +_by Window in codebehind as shown above._ +_Improvements to Window are being considered to avoid this extra grid layout and codebehind._ +_Please see Appendix of [Functional Spec](titleBar-functional-spec.md)._ + +## Scenario: TitleBar with WinUI Controls Integration +TitleBar with common WinUI Controls: `AutoSuggestBox`, `PersonPicture`, `AppBarButton`. + +![alt text](images/controls-titlebar.png) + +**XAML** +```xml + + + + + + + + + + + + + + +``` + +## Scenario: TitleBar with NavigationView L-Pattern Integration + + +Titlebar and NavigationView in an L-Pattern. +![alt text](images/titlebar-navview.png) + +TitleBar and NavigationView is in Minimal DisplayMode. +Note that TitleBar IconSource is collapsed in minimal mode. +![alt text](images/titlebar-navview-minimal.png) + +**XAML** +```xml + + + + + + + + + + + + + + + + + 1,1,0,0 + + 8,0,0,0 + + + + + + ... + + + +``` + +_Note: Should the NavView resources be the default to avoid needing the extra code?_ +_This will be a question of what pattern will be shipped in WinUI Templates by default._ + +**C#** +```cs +public MainWindow() +{ + this.InitializeComponent(); + + Window window = this; + window.ExtendsContentIntoTitleBar = true; + window.SetTitleBar(this.DefaultTitleBar); +} + +private void NavViewTitleBar_BackRequested(TitleBar sender, object args) +{ + if (NavFrame.CanGoBack) + { + NavFrame.GoBack(); + } +} + +private void NavViewTitleBar_PaneToggleRequested(TitleBar sender, object args) +{ + NavView.IsPaneOpen = !NavView.IsPaneOpen; +} +``` + +_Note: How can we avoid this extra code-behind?_ + +# API Pages + +## TitleBar class + +Represents a control that provides the title and system buttons for a window or application. It typically appears at the top of the window and +includes core functionalities such as drag, minimize, maximize, and close buttons. + +Namespace: Microsoft.UI.Xaml.Controls + +```cs +public class TitleBar : Control +``` + +## TitleBar.ContentBefore property + +Gets and sets elements within the TitleBar's ContentBefore column. + +```cs +public UIElement ContentBefore { get; set; } +``` + +### Property Value +Represents the ContentBefore content property of the `TitleBar` control which can be populated in both XAML markup and code. The default is `null`. + +### Remarks +The content property of `ContentBefore` can only be set once. Elements are left aligned by default. + +If `IsBackButtonVisible` or `IsPaneToggleButtonVisisble` is true, custom content set in the `ContentBefore` property +will automatically be appended to the ContentBefore column in TitleBar layout. + +If the property is not `null`, TitleBar automatically configures its height to `TitleBarExpandedHeight` in codebehind. See ThemeResources section for further details. + + +## TitleBar.Title property + +Gets or sets the Title text to be displayed on the TitleBar. + +```cs +public String Title { get; set; } +``` + +### Property Value +Represents the title string to be displayed on the `TitleBar`. The default is `null`. + +### Remarks +If TitleBar is in minimal display mode, Title textbox will automatically be collapsed. +If Title string is empty, Title textbox will be collapsed. + +## TitleBar.Subtitle property + +Gets or sets the Subtitle text to be displayed on the TitleBar. This is generally used for versioning, such as "Preview", "Beta", etc. + +```cs +public String Subtitle { get; set; } +``` + +### Property Value +Represents the subtitle string to be displayed on the `TitleBar`. The default is `null`. + +### Remarks +If TitleBar is in minimal display mode, `Subtitle` textbox will automatically be collapsed. +If `Subtitle` string is empty, `Subtitle` textbox will be collapsed. + + +## TitleBar.IconSource property + +Gets or sets the TitleBar's icon. + +```cs +public IconSource IconSource { get; set; } +``` + +### Property Value +Represents the icon associated with the `TitleBar`. The default is `null`. + + +## TitleBar.Content property + +Gets and sets elements within the TitleBar's Content column. + +```cs +public UIElement Content { get; set; } +``` + +### Property Value +Represents the Content property of the `TitleBar` control which can be populated in both XAML markup and code. + +This is typically used to populate controls such as `AutoSuggestBox`. The default is `null`. + +### Remarks +The content property of `Content` can only be set once. Elements are center aligned by default. + +If the property is not `null`, TitleBar automatically configures its height to `TitleBarExpandedHeight` in codebehind. See ThemeResources section for further details. + +## TitleBar.ContentAfter property + +Gets and sets elements within the TitleBar's ContentAfter column. + +```cs +public UIElement ContentAfter { get; set; } +``` + +### Property Value +Represents the ContentAfter property of the `TitleBar` control which can be populated in both XAML markup and code. + +This is typically used to populate controls such as `PersonPicture` and the "More" `AppBarButton`. The default is `null`. + +### Remarks +The content property of `ContentAfter` can only be set once. Elements are right aligned by default. + +If the property is not `null`, TitleBar automatically configures its height to `TitleBarExpandedHeight` in codebehind. See ThemeResources section for further details. + +## TitleBar.IsBackButtonVisible property + +Gets and sets TitleBar's BackButton visiblity. + +```cs +public Boolean IsBackButtonVisible { get; set; } +``` + +### Property Value +Represents the visiblity of TitleBar's BackButton. The default is `false`. + + +## TitleBar.IsBackButtonEnabled property + +Gets and sets BackButton's IsEnabled property. + +```cs +public Boolean IsBackButtonEnabled { get; set; } +``` + +### Property Value +Represents the IsEnabled property of TitleBar's BackButton. The default is `true`. + +### Remarks +This property is typically bound to an accompanying NavFrame's `CanGoBack` property: +`IsBackButtonEnabled="{x:Bind NavFrame.CanGoBack}"` + +## TitleBar.IsPaneToggleButtonVisible property + +Gets and sets TitleBar's PaneToggleButton visiblity. + +```cs +public Boolean IsPaneToggleButtonVisible { get; set; } +``` + +### Property Value +Represents the visiblity of TitleBar's PaneToggleButton. The default is `false`. + +### Remarks +TitleBar's PaneToggleButton is only used with NavigationView and when NavigationView is in `Minimal` DisplayMode. +In other display mode scenarios, the PaneToggleButton is owned and handled by NavigationView. + + +## TitleBar.BackRequested event + +Occurs whenever BackButton is clicked. + +C# +```cs +public event TypedEventHandler BackRequested; +``` + +### Remark +This event is raised when internal BackButton raises a Click event. + + +## TitleBar.PaneToggleRequested event + +Occurs whenever PaneToggleButton is clicked. + +C# +```cs +public event TypedEventHandler PaneToggleRequested; +``` + +### Remark +This event is raised when internal PaneToggleButton raises a Click event. + +## TitleBarTemplateSettings Class + + +## TitleBarAutomationPeer Class + + +Exposes `TitleBar` types to Microsoft UI Automation. + +Namespace: Microsoft.UI.Xaml.Automation.Peers + +```cs +public class TitleBarAutomationPeer : Microsoft.UI.Xaml.Automation.Peers... +``` + +TitleBarAutomationPeer implements ... + +# API Details + +```cs (but really MIDL3) +[MUX_EXPERIMENTAL] +[webhosthidden] +unsealed runtimeclass TitleBar : Microsoft.UI.Xaml.Controls.Control +{ + TitleBar(); + + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + UIElement ContentBefore{ get; set; }; + + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + String Title{ get; set; }; + + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + String Subtitle{ get; set; }; + + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + Microsoft.UI.Xaml.Controls.IconSource IconSource{ get; set; }; + + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + UIElement Content{ get; set; }; + + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + UIElement ContentAfter{ get; set; }; + + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + Boolean IsBackButtonVisible{ get; set; }; + + Boolean IsBackButtonEnabled{ get; set; }; + + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + Boolean IsPaneToggleButtonVisible{ get; set; }; + + TitleBarTemplateSettings TemplateSettings{ get; }; + + event Windows.Foundation.TypedEventHandler BackRequested; + event Windows.Foundation.TypedEventHandler PaneToggleRequested; + + static Microsoft.UI.Xaml.DependencyProperty ContentBeforeProperty{ get; }; + static Microsoft.UI.Xaml.DependencyProperty TitleProperty{ get; }; + static Microsoft.UI.Xaml.DependencyProperty SubtitleProperty{ get; }; + static Microsoft.UI.Xaml.DependencyProperty IconSourceProperty{ get; }; + static Microsoft.UI.Xaml.DependencyProperty ContentProperty{ get; }; + static Microsoft.UI.Xaml.DependencyProperty ContentAfterProperty{ get; }; + static Microsoft.UI.Xaml.DependencyProperty IsBackButtonVisibleProperty{ get; }; + static Microsoft.UI.Xaml.DependencyProperty IsBackButtonEnabledProperty{ get; }; + + static Microsoft.UI.Xaml.DependencyProperty TemplateSettingsProperty{ get; }; +} + +[MUX_EXPERIMENTAL] +[webhosthidden] +unsealed runtimeclass TitleBarTemplateSettings : Microsoft.UI.Xaml.DependencyObject +{ + TitleBarTemplateSettings(); + + Microsoft.UI.Xaml.Controls.IconElement IconElement; + + static Microsoft.UI.Xaml.DependencyProperty IconElementProperty{ get; }; +} + +[MUX_EXPERIMENTAL] +[webhosthidden] +unsealed runtimeclass TitleBarAutomationPeer : Microsoft.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer +{ + TitleBarAutomationPeer(MEU_XC_NAMESPACE.TitleBar owner); +} +``` + +# ThemeResources +This section does not list all of the ThemeResources associated with TitleBar. Only ThemeResources of note that require highlight or further explanation. + +| Resource | Type | Value | Description | +|--|--|--|--| +| `TitleBarCaptionButton`* | Color | - | Defines color resources for the AppWindow caption buttons. | + +TitleBar currently overwrites the resources on theme changes in codebehind. This can be removed once the theme change feature is shipped for AppWindow. + +| Resource | Type | Value | Description | +|--|--|--|--| +| `TitleBarCompactHeight` | Double | 32px | Defines the compact / default height for TitleBar. | +| `TitleBarExpandedHeight` | Double | 48px | Defines the expanded height for TitleBar. | + +There is no TitleBar.Height property. The height for TitleBar is configured in codebehind depending on whether there +is content present in the `ContentBefore`, `Content`, and `ContentAfter` content areas. TitleBar's height is set to `TitleBarCompactHeight` if no elements are present in the mentioned content areas, and `TitleBarExpandedHeight` if +elements are present. As the content areas are empty by default, the default height for TitleBar is +`TitleBarCompactHeight`. + +# Figma link + +[Figma link](https://www.figma.com/file/sxPR9uvUNg6XQKSKOmlbK8/Fluent-Windows-Visual-Library?type=design&node-id=30201-110568&mode=design&t=ke7CzN5LvKzNA8LR-4) + +# Appendix + +Reference: +- Tammy's TitleBar [WIP](https://dev.azure.com/microsoft/WinUI/_git/microsoft-ui-xaml-lift/?path=%2Fcontrols%2Fdev%2FTitleBar%2FTitleBar.idl&version=GBmain&_a=contents) +- Niels Laute's TitleBar in CommunityToolkit: [PR](https://github.com/CommunityToolkit/Labs-Windows/pull/459/files), [Spec](https://github.com/CommunityToolkit/Labs-Windows/discussions/454)