Unpackaged 0.0.21
dotnet add package Unpackaged --version 0.0.21
NuGet\Install-Package Unpackaged -Version 0.0.21
<PackageReference Include="Unpackaged" Version="0.0.21" />
paket add Unpackaged --version 0.0.21
#r "nuget: Unpackaged, 0.0.21"
// Install Unpackaged as a Cake Addin #addin nuget:?package=Unpackaged&version=0.0.21 // Install Unpackaged as a Cake Tool #tool nuget:?package=Unpackaged&version=0.0.21
CppXAML
CppXAML aims to make usage of XAML and XAML islands in C++ more natural and idiomatic.
C++/WinRT provides a projection of a Windows Runtime component's API, but one that isn’t always easy to use (esp. for XAML). It also is unopinionated about how to implement properties. This added flexibility can be useful, but is often unnecessary and results in overly-verbose code.
CppXAML provides several kinds of higher-level helpers. Some usage information can be found below; for more details, see the API reference.
GitHub repo: https://github.com/asklar/xaml-islands
Table of Contents
- Facilities for writing XAML controls
- Facilities for using XAML controls
- Facilities for using XAML islands
Facilities for writing XAML controls {#facilities-for-writing-xaml-controls}
Property and event helpers
XamlProperty<T>
SimpleNotifyPropertyChanged<F>
XamlPropertyWithNPC<T>
XamlEvent<T>
TypedXamlEvent<TSender, TArgs>
These provide stock/simple property objects that remove the need for verbose hand-written options.
Example
Suppose you have the following Page defined in IDL:
namespace Foo {
runtimeclass MainPage : Windows.UI.Xaml.Controls.Page, Windows.UI.Xaml.Data.INotifyPropertyChanged {
MainPage();
event Windows.Foundation.EventHandler<String> OkClicked;
String InterfaceStr;
Int32 MyInt;
}
}
Before (plain C++/WinRT)
struct MainPage : MainPageT<MainPage> {
winrt::event<winrt::Windows::Foundation::EventHandler<winrt::hstring>> m_okClicked{};
winrt::event_token OkClicked(winrt::Windows::Foundation::EventHandler<winrt::hstring> h) {
return m_okClicked.add(h);
}
void OkClicked(winrt::event_token token) {
m_okClicked.remove(token);
}
winrt::hstring m_InterfaceStr;
winrt::hstring InterfaceStr() {
return m_InterfaceStr;
}
void InterfaceStr(winrt::hstring v) {
m_InterfaceStr = v;
}
winrt::event<winrt::Windows::UI::Xaml::Data::PropertyChangedEventHandler> m_propertyChanged;
winrt::event_token PropertyChanged(winrt::Windows::Xaml::Data::PropertyChangedEventHandler const& value) {
return m_propertyChanged.add(value);
}
void PropertyChanged(winrt::event_token const& token) {
m_propertyChanged.remove(token);
}
int32_t m_MyInt;
int32_t MyInt() {
return m_MyInt;
}
void MyInt(int32_t v) {
m_MyInt = v;
m_propertyChanged(*this, { L"MyInt" });
}
};
After (with CppXaml)
struct MainPage : MainPageT<MainPage>, cppxaml::SimpleNotifyPropertyChanged<MainPage> {
cppxaml::XamlEvent<winrt::hstring> OkClicked;
cppxaml::XamlProperty<winrt::hstring> InterfaceStr;
cppxaml::XamlPropertyWithNPC<int32_t> MyInt;
MainPage() : INIT_PROPERTY(MyInt, 42) {
InitializeComponent();
// Properties can be assigned to and read from with the operator= too!
InterfaceStr = winrt::hstring{ L"This string comes from the implementation" };
winrt::hstring v = InterfaceStr;
}
void MyPage::DoSomething() {
// when MyInt is modified, it automatically sends NPC!
MyInt = 39;
// if we want to manually send a notification:
RaisePropertyChanged(L"MyInt");
}
};
Facilities for using XAML controls {#facilities-for-using-xaml-controls}
Control helpers
CppXAML includes some primitives to make it more natural to write XAML UI in code.
xaml Namespace alias
Since we want CppXAML to be future proof and work with WinUI 3, CppXAML creates a namespace alias cppxaml::xaml
which points at either Windows::UI::Xaml
or Microsoft::UI::Xaml
for system XAML or WinUI 3, respectively.
Builder-style programming
C++/WinRT enables setting properties on a type by calling a property setter method, e.g. myTextBlock.Text(L"text");
. If you then want to set another property, then you have to make another call myTextBlock.XYZ(...);
. This can get verbose when having to set multiple properties. CppXAML enables writing builder-style code instead of the former imperative-style:
Before (plain C++/WinRT)
auto myTextBlock = winrt::Windows::UI::Xaml::Controls::TextBlock{};
myTextBlock.Text(L"Hello world");
myTextBlock.Margin(winrt::Windows::UI::Xaml::ThicknessHelper::FromUniformLength(4));
myTextBlock.Padding(winrt::Windows::UI::Xaml::ThicknessHelper::FromUniformLength(6));
myTextBlock.Name(L"myTB");
After (with CppXAML)
auto myTextBlock = cppxaml::TextBlock(L"Hello world")
.Margin(4)
.Padding(6)
.Name(L"myTB");
TextBlock
Most commonly, you will want to construct a TextBlock
from a string of text. This can be a bit cumbersome if you are using C++/WinRT directly.
With cppxaml, as you've seen above, you can just write:
auto tb = cppxaml::TextBlock(L"Hello");
StackPanel
Panels in XAML can have zero or more children. CppXAML makes it easy to naturally describe a panel's children with an initializer list. For example:
Before (plain C++/WinRT)
auto sp = winrt::Windows::UI::Xaml::Controls::StackPanel();
auto tb1 = winrt::Windows::UI::Xaml::Controls::TextBlock();
tb1.Text(L"Hello");
auto tb2 = winrt::Windows::UI::Xaml::Controls::TextBlock();
tb2.Text(L"world!");
sp.Children().Append(tb1);
sp.Children().Append(tb2);
After (with CppXaml)
auto sp = cppxaml::StackPanel({
cppxaml::TextBlock(L"Hello"),
cppxaml::TextBlock(L"world!")
});
You can also set its Orientation
:
auto sp cppxaml::StackPanel({
cppxaml::TextBlock(L"Hello"),
cppxaml::TextBlock(L"world!").Name(L"worldTB")
}).Orientation(cppxaml::xaml::Controls::Orientation::Horizontal);
ContentControl (Button, etc.)
Sub-classes of XAML's ContentControl
enable nesting one control into another via the Content
property. CppXAML makes this easier:
auto scrollViewer = cppxaml::MakeContentControl<cppxaml::xaml::Controls::ScrollViewer>({
cppxaml::StackPanel({
cppxaml::TextBlock(L"Hello"),
cppxaml::TextBlock(L"world!").Name(L"worldTB")
})
});
Locating elements by name
Sometimes you will need to perform some operation on an element that is deeply nested in a builder-style declaration. You can use FindChildByName
to find an element in a XAML tree with a given name:
auto worldTB = cppxaml::FindChildByName<Controls::TextBlock>(*scrollViewer, L"worldTB");
Grid
Declaring a Grid
in XAML via code is cumbersome as one has to create and set its RowDefinitions
and ColumnDefinitions
.
Before (plain C++/WinRT)
winrt::Windows::UI::Xaml::Controls::Grid g;
auto rd1 = winrt::Windows::UI::Xaml::Controls::RowDefinition();
rd1.Height(winrt::Windows::UI::Xaml::GridLengthHelper::FromPixels(40));
auto rd2 = winrt::Windows::UI::Xaml::Controls::RowDefinition();
rd2.Height(winrt::Windows::UI::Xaml::GridLengthHelper::FromValueAndType(1,
winrt::Windows::UI::Xaml::GridUnitType::Star));
g.RowDefinitions().Append(rd1);
g.RowDefinitions().Append(rd2);
auto cd1 = winrt::Windows::UI::Xaml::Controls::ColumnDefinition();
cd1.Width(winrt::Windows::UI::Xaml::GridLengthHelper::Auto());
auto cd2 = winrt::Windows::UI::Xaml::Controls::ColumnDefinition();
cd2.Width(winrt::Windows::UI::Xaml::GridLengthHelper::Auto());
g.ColumnDefinitions().Append(cd1);
g.ColumnDefinitions().Append(cd2);
auto tb1 = winrt::Windows::UI::Xaml::Controls::TextBlock();
tb1.Text(L"first");
tb1.SetValue(winrt::Windows::UI::Xaml::Controls::Grid::RowProperty(), winrt::box_value(0));
tb1.SetValue(winrt::Windows::UI::Xaml::Controls::Grid::ColumnProperty(), winrt::box_value(0));
g.Children().Append(tb1);
// repeat 3 more times... :-(
After (with CppXaml)
auto grid = cppxaml::Grid({"40, *"}, {"Auto, Auto"}, {
{0, 0, cppxaml::TextBlock(L"first") },
{0, 1, cppxaml::TextBlock(L"second") },
{1, 0, cppxaml::TextBlock(L"third") },
{1, 1, cppxaml::TextBlock(L"fourth") },
}),
Here we defined a 2x2 Grid
. The rows have heights of 40 px and *
, and the columns are Auto
. Then each child of the Grid is added in the cell designated by each entry in the initializer list, read as "row, column, child".
In addition to the string syntax (which requires some parsing/tokenizing), this also works:
auto grid = cppxaml::Grid({40, {"*"}}, {{"Auto"}, {"Auto"}}, {
{0, 0, cppxaml::TextBlock(L"first") },
{0, 1, cppxaml::TextBlock(L"second") },
{1, 0, cppxaml::TextBlock(L"third") },
{1, 1, cppxaml::TextBlock(L"fourth") },
}),
Attached properties
You can set arbitrary dependency properties, including attached properties, on a cppxaml wrapper:
auto tb = cppxaml::TextBlock(L"something")
.Set(Grid::RowProperty(), 1)
.Set(Grid::ColumnSpanProperty(), 2);
AutoSuggestBox
You can easily create an AutoSuggestBox
from a std::vector<std::wstring>
; make sure the vector's lifetime extends for at least as long as the XAML UI is up.
EnableDefaultSearch()
will provide a reasonable default search experience (filters the list of items down to those that contain the search string). This behavior is case insensitive by default, but can be made case sensitive by passing false
.
auto asb = cppxaml::AutoSuggestBox(GetFontFamilies())
.EnableDefaultSearch()
.Margin(0, 16, 0, 4)
.Name(L"fontTB");
Visual State change notifications
You can easily set up visual state change notifications:
auto button = cppxaml::Button(L"click me")
.VisualStates( {
{ L"PointerOver", [](auto&sender, cppxaml::xaml::VisualStateChangedEventArgs args) {
auto x = args.NewState().Name();
auto button = sender.as<Controls::Button>();
button.Content(winrt::box_value(x));
} },
{ L"Normal", [](auto&sender, auto&) {
auto button = sender.as<Controls::Button>();
button.Content(winrt::box_value(L"click me"));
} },
{ L"Pressed", [](auto& sender, auto&) {
auto button = sender.as<Controls::Button>();
button.Content(winrt::box_value(L"pressed"));
} },
});
Initializing Panels from collections
As we saw earlier, you can initialize a panel from its children. You can also use transforms, to map elements from a data model into its corresponding view.
For example:
auto strs = std::vector<std::wstring>{ L"first", L"second", L"third", L"fourth" };
auto grid = cppxaml::Grid({"40, *"}, {"Auto, Auto"},
cppxaml::utils::transform_with_index(strs, [](const std::wstring& t, auto index) {
return cppxaml::TextBlock(t)
.Set(Grid::RowProperty(), (int)index / 2)
.Set(Grid::ColumnProperty(), (int)index % 2);
};
})
);
For more details see cppxaml::transform
and cppxaml::transform_with_index
in utils.h.
Menus and icons
You can easily compose MenuFlyoutItems into a MenuFlyout, and also have a centralized menu handler callback:
auto menuFlyout = cppxaml::MenuFlyout(
cppxaml::MenuFlyoutItem(L"Exit")
.IconElement(cppxaml::FontIcon(0xe8bb))
.Click([hwnd = xw->hwnd()](auto&...) {
DestroyWindow(hwnd);
}),
cppxaml::MenuFlyoutItem(L"Cancel")
.IconElement(cppxaml::FontIcon(L"\xE8A7"))
)
.CentralizedHandler([](Windows::Foundation::IInspectable sender, auto&) {
auto mfi = sender.as<Controls::MenuFlyoutItem>();
auto x = mfi.Text();
});
Facilities for using XAML Islands {#facilities-for-using-xaml-islands}
XamlWindow
XamlWindow
implements an HWND based host for XAML Islands. You can create a XamlWindow
from one of three overloads of Make:
- Host a build-time XAML
UIElement
(usually defined in a runtime component project, often will be aPage
) API:
Usage:template<typename TUIElement> static XamlWindow& Make(PCWSTR id, AppController* controller = nullptr);
auto& mainWindow = cppxaml::XamlWindow::Make<MarkupSample::MainPage>(L"MarkupSample", &controller);
- Host UI created from markup at runtime:
API:
Usage:static XamlWindow& Make(PCWSTR id, std::wstring_view markup, AppController* c = nullptr)
auto& xw = cppxaml::XamlWindow::Make(L"MyPage", LR"( <StackPanel> <TextBlock>Hello</TextBlock> </StackPanel>)", &controller);
- Host UI created programmatically at runtime:
API:
Usage:static XamlWindow& Make(PCWSTR id, winrt::Windows::UI::Xaml::UIElement(*getUI)(const XamlWindow&), AppController* c = nullptr);
auto& xw = cppxaml::XamlWindow::Make(L"Foo", [](auto&...) { return winrt::Windows::UI::Xaml::Controls::Button(); });
Parenting flyouts
To parent a flyout or context menu, you may use one of the InitializeWithWindow
methods:
- Initialize with a WinUI 3
Window
-like object:template<typename TWindow> std::enable_if_t<!std::is_assignable_v<TWindow, cppxaml::XamlWindow*>> InitializeWithWindow(winrt::Windows::Foundation::IInspectable obj, TWindow /*winrt::Microsoft::UI::Xaml::Window*/ w)
- Initialize with an
HWND
:bool InitializeWithWindow(cppxaml::xaml::FrameworkElement obj, HWND hwnd)
- Initialize with a
XamlWindow
:void InitializeWithWindow(cppxaml::xaml::FrameworkElement obj, const cppxaml::XamlWindow* xw)
AppController
AppController
is responsible for coordinating XamlWindow instances, can extend their wndproc, and provides an opportunity to hook up event handlers once a XAML UI becomes live
Learn more about Target Frameworks and .NET Standard.
-
- Microsoft.Windows.CppWinRT (>= 2.0.211028.7)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.0.21 | 361 | 3/18/2023 |
0.0.20 | 401 | 11/14/2022 |
0.0.19 | 333 | 11/13/2022 |
0.0.18 | 329 | 11/12/2022 |
0.0.17 | 474 | 9/23/2022 |
0.0.16 | 10,957 | 1/8/2022 |
0.0.15 | 259 | 1/8/2022 |
0.0.13 | 261 | 1/7/2022 |
0.0.12 | 277 | 1/7/2022 |
0.0.11 | 260 | 1/4/2022 |
0.0.10 | 267 | 12/28/2021 |
0.0.9 | 278 | 12/27/2021 |
0.0.8 | 284 | 12/26/2021 |
0.0.7 | 265 | 12/23/2021 |
0.0.6 | 253 | 12/22/2021 |
0.0.5 | 266 | 12/22/2021 |
0.0.4 | 272 | 12/14/2021 |
0.0.3 | 273 | 12/8/2021 |
0.0.2 | 415 | 12/8/2021 |
0.0.1 | 537 | 8/27/2021 |