Skip to content

Latest commit

 

History

History
249 lines (210 loc) · 8.2 KB

README.md

File metadata and controls

249 lines (210 loc) · 8.2 KB
Raw

WinUI Essentials

A repo dedicated for simplifying C++ development with WinUI2 (Universal Windows Platform) and WinUI3 (Windows App SDK).

Usage

Warning

Make sure to set your C++ language version to C++20 first!

Open the WinUIEssential.sln containing 4 projects:

  • UWPPackage (project for WinUIEssential.UWP nuget package)
  • UWPExample (example gallery for using the above package)
  • WinUI3Package (project for WinUIEssential.WinUI3 nuget package)
  • WinUI3Example (example gallery for using the above package)

Build the *Package project will build the project and pack it with nuget, then install the nuget to your project and start using it.

To build the *Example project, do the same thing. They did not reference *Package for demo purposes.

Note

Functionalities for UWP and WinUI3 should be exactly the same unless otherwise noted!

It should be useful until the community toolkit provides C++.

Content

Component UWP WinUI3 Type
WinUIIncludes ✅ ❌ Header only
TemplateControlHelper ✅ ✅ Header only
Glyphs ✅ ✅ Header only + Xaml only
BadgeGlyphs ✅ ✅ Header only
ToastTemplates ✅ ✅ Header only
ToastBuilder ✅ ✅ Header only
SettingsExpander WinRT component
CursorController ✅ ✅ WinRT component
PropertyChangeHelper ✅ ✅ Header only
NegateBoolConverter ✅ ✅ WinRT component
BoolToVisibilityConverter ✅ ✅ WinRT component
ContainerToBoolConverter ✅ ✅ WinRT component
StringToBoolConverter ✅ ✅ WinRT component
ReferenceToBoolConverter ✅ ✅ WinRT component
ConverterGroup ✅ ✅ WinRT component
IsEqualStateTrigger ✅ ✅ WinRT component
IsNullOrEmptyStateTrigger ✅ ✅ WinRT component
ControlSizeTrigger ✅ ✅ WinRT component
GroupBox ✅ ✅ Control
SettingsCard ✅ ✅ Control

*means additional settings required, see the sections for info

WinUIIncludes

Include the WinUI2 headers in your pch.h, so you don't waste your time figuring out where the compilation error comming from./

Usage: Add this in your pch.h

#include <WinUIIncludes.hpp>

TemplateControlHelper

Automatically call DefaultStyleKey() for your templated control so you don't waste your time when you forget to include this line and get an empty control.

Usage: Inherit this class in your header file, make the template argument your implementation type.

#include <TemplateControlHelper.hpp>
...
struct MyControl : MyControlT<MyControl>, TemplateControlHelper<MyControl>
{
    ...
};

ToastHelper

Helper for creating toast notifications.

ToastTemplates --- namespace ToastTemplates

The built-in templates re-written to strongly-typed classes that derived from winrt::Windows::UI::Notification::ToastNotification, so that you can directly use them as arguments forwinrt::Windows::UI::Notifications::ToastNotificationManager. Example usage:

#include <ToastTemplates.hpp>
winrt::Windows::UI::Notifications::ToastNotificationManager::CreateToastNotifier()
    .Show(ToastTemplates::ImageWithHeaderAndBody{ L"ms-appx:///Assets/Windows 11.png", L"Header", L"body" });
Type Template Sample
BodyTextOnly ToastText01
SingleLineHeaderWithBody ToastText02
TwoLineHeaderWithBody ToastText03
HeaderWithTwoSingleLineBody ToastText04
ImageWithBodyOnly ToastImageAndText01
ImageWithHeaderAndBody ToastImageAndText02
ImageWithTwoLineHeaderAndBody ToastImageAndText03
ImageWithHeaderAndTwoSingleLineBody ToastImageAndText04

ToastBuilder --- namespace ToastBuilder

Strongly-typed, declarative toast notification elements to quickly build toast notifications, as if you are writing XAML. Schema here. Example usage:

XML C++ 
<toast duration="long" scenario="reminder" useButtonStyle="true">
    <visual>
        <binding template="ToastText04">
            <text id="1">headline</text>
            <text id="2">body text1</text>
            <text id="3">body text2</text>
        </binding>
    </visual>
    <actions>
        <action content="Accept" arguments="accept"/>
    </actions>
</toast>
 
Toast().Duration(Long).Scenario(Reminder).UseButtonStyle(true)
(
    Visual()
    (
        Binding().Template(L"ToastText04")
        (
            Text().Id(1)(L"headline"),
            Text().Id(2)(L"body text1"),
            Text().Id(3)(L"body text2")
        )
    ),
    Actions()
    (
        Action().Content(L"Accept").Arguments(L"accept")
    )
)

<tag>...content...</tag>

Tag()(...content...)

attribute="value"

.Attribute(value)

Glphys --- namespace Glyphs

Font glyphs value for Segoe MDL2 Assets fonts.

CursorController --- namespace CursorController

Xaml helper for controlling the cursor type when mouse enters. Value for Type is CoreCursorType enum. Usage:

xmlns:essential="using:WinUI3Package"
...
<Rectangle Fill="Red" essential:CursorController.Type="Hand"/>

PropertyChangeHelper --- namespace MvvmHelper

Helper for OneWay binding.

Usage:

  1. Inherit Windows.UI.Xaml.Data.INotifyPropertyChanged in idl
[default_interface]
runtimeclass MyPage : Windows.UI.Xaml.Controls.Page, Windows.UI.Xaml.Data.INotifyPropertyChanged
{
    ...
};
  1. Inherit from this class in the implementation class.
/*MyPage.xaml.h*/
#include <include/PropertyChangeHelper.hpp>

namespace winrt::<MyProject>::implementation
{
    struct MyPage : MyMusicT<MyMusic>, MvvmHelper::PropertyChangeHelper<MyMusic>
    {
        int m_value;
        void Value(int newValue)
        {
            compareAndRaise(m_value, newValue, L"Value");
        };
    }
}

Converters

  • bool -> Visibility namespace BoolToVisibilityConverter
  • bool negation namespace NegateBoolConverter
  • container (IVector, IMap) -> bool namespace ContainerToBoolConverter
  • reference (any WinRT runtime type) -> bool namespace ReferenceToBoolConverter
  • String -> bool namespace StringToBoolConverter
  • ConverterGroups namespace ConverterGroups:
    • define series of converters, that convert value from converter1 -> converter2 -> ...
    • usage:
     <essential:ConverterGroup x:Key="StringToVisibilityConverter">
     <essential:StringToBoolConverter/>
     <essential:BoolToVisibilityConverter/>
 </essential:ConverterGroup>

BadgeGlyphs --- namespace BadgeGlyphs

Helpers for creating badge notification xml. Usage:

#include <include/BadgeGlyphs.hpp>

//glyph badge
winrt::Windows::UI::Notifications::BadgeUpdateManager::CreateBadgeUpdaterForApplication()
	.Update(BadgeGlyphs::MakeBadgeNotification(BadgeGlyphs::Alert));

//number badge
winrt::Windows::UI::Notifications::BadgeUpdateManager::CreateBadgeUpdaterForApplication()
	.Update(BadgeGlyphs::MakeBadgeNotification(1));

Triggers

See the same class in Community Toolkit for documentation.

ControlSizeTrigger --- namespace ControlSizeTrigger

IsEqualStateTrigger --- namespace IsEqualStateTrigger

IsNullOrEmptyStateTrigger --- namespace IsNullOrEmptyStateTrigger

SettingsCard

See the same class in Community Tookit for documentation.