Learn Universal Windows Programming Via Modern C++ (RelativePanel)

Before reading this article, I highly recommend reading the previous parts of the series.

In this article, we are going to learn about RelativePanel control in Modern C++/WinRT. UWP Control Panels is divided into the following two types,

Linear pattern or Panel.
Non-Liner pattern or Panel.

Linear Pattern

In a Linear Pattern, all the controls should be either Horizontal or Vertical.

For example, a StackPanel.

Non-Linear pattern

In a Non-Linear pattern, all the controls are aligned in any order with relationship to other controls, like top or bottom or right or left etc.

Now, I am going to explain how to implement the Non-Linear pattern. RelativePanel control is called Non-Linear pattern also.

Relative panel

Each control has a relationship with other controls with any relationship (but not a circular dependency).

ReleativePanel Properties

Children

All the itemcontrols have to be added to the children property. "Children" is a UIElementCollection container and by default, all the controls are added into the zero-index order. "Append properties" is used to add the Controls into the container.

RelativePanel RPanel;
RPanel.Children().Append(txtTop);
RPanel.Children().Append(txtBottom);
RPanel.Children().Append(txtLeft);
RPanel.Children().Append(txtRight);
RPanel.Children().Append(txtHorCenter);
RPanel.Children().Append(txtVertical);
RPanel.Children().Append(txtRightOf);
RPanel.Children().Append(txtLeftOf);
RPanel.Children().Append(txtAbove);
RPanel.Children().Append(txtBelow);
RPanel.Children().Append(txtHeader);

Properties' position inside the Panel control

The complete box is a Relative panel.
Inside boxes are child controls.
Arrow is specified as Alignment and Position of the controls.

A RelativePanel is a Parent control, all inside controls are child controls.

There are generally the following two types of relationships,

Parent to child.
Child to child.

Parent -> Child: All panel properties are parent types.

Set the parent related controls, pass the control name, & set as true. It's attached to the parent control.

Parent related APIs

RelativePanel.SetAlignTopWithPanel(control,true);
RelativePanel.SetAlignBottomWithPanel(control, true);
RelativePanel.SetAlignLeftWithPanel(control, true);
RelativePanel.SetAlignRightWithPanel(control, true);
RelativePanel.SetAlignVerticalCenterWithPanel(control, true);
RelativePanel.SetAlignHorizontalCenterWithPanel(control,true);

Child relationship

Child to child (other than panel relationship, properties consider the child to child properties).

Below APIs are used to set the Child to Child relationship. For child relationship APIs, first we need to pass the child argument as first, which child we are attaching (Parent) that should be second arguments.

Child APIs

RelativePanel.SetRightOf(ChildControl, PropertyValue::CreateInspectable(ParentControl));
RelativePanel.SetLeftOf(ChildControl, PropertyValue::CreateInspectable(ParentControl));
RelativePanel.SetAbove(ChildControl, PropertyValue::CreateInspectable(ParentControl));
RelativePanel.SetBelow(ChildControl, PropertyValue::CreateInspectable(ParentControl));

All the alignment properties are high-priority and the remaining (position) properties are low-priority.

Each control's relation with other controls is something. If we did not provide the relative properties, then the first control aligns with the default position and the next controls overwrite the previous control and always set the relative controls. For each control, one or more relationship depends on the requirements.

Sample code to implement RelativePanel in Modern C++ / WinRT

#include "pch.h"
using namespace winrt;
using namespace Windows::ApplicationModel;
using namespace Windows::ApplicationModel::Activation;
using namespace Windows::Foundation;
using namespace Windows::UI;
using namespace Windows::UI::Xaml;
using namespace Windows::UI::Xaml::Controls;
using namespace Windows::UI::Xaml::Controls::Primitives;
using namespace Windows::UI::Xaml::Interop;
using namespace Windows::UI::Xaml::Navigation;
using namespace Windows::UI::Xaml::Media;
using namespace Windows::Media;
using namespace Windows::Storage;
struct App :ApplicationT<App>
{
public:
virtual ~App() = default;
static TextBlock CreateTextBlock(hstring);
static void OnLaunched(LaunchActivatedEventArgs const&);
static Thickness CreateThickness(int bottom, int left, int right, int top);
};
Thickness App::CreateThickness(int bottom, int left, int right, int top)
{
Thickness think;
think.Bottom = bottom;
think.Left = left;
think.Right = right;
think.Top = top;
return think;
}
TextBlock App::CreateTextBlock(hstring textCaption)
{
TextBlock text;
text.Text(textCaption);
text.TextAlignment(TextAlignment::Center);
text.Margin(CreateThickness(10, 10, 0, 10));
return text;
}
void App::OnLaunched(LaunchActivatedEventArgs const&)
{
auto txtTop = CreateTextBlock(L"AlignTopWithPanel");
txtTop.Margin(CreateThickness(0, 10, 0, 0));
auto txtBottom = CreateTextBlock(L"AlignBottomWithPanel");
txtBottom.Margin(CreateThickness(0, 10, 0, 0));
auto txtLeft = CreateTextBlock(L"AlignLeftWithPanel");
txtLeft.Margin(CreateThickness(10, 0, 5, 50));
auto txtRight = CreateTextBlock(L"AlignRightWithPanel");
auto txtHorCenter = CreateTextBlock(L"AlignHorizontalCenterWithPanel");
auto txtVertical = CreateTextBlock(L"AlignVerticalCenterWithPanel");
auto txtRightOf = CreateTextBlock(L"RightOfControl");
txtRightOf.Foreground(SolidColorBrush(Colors::Red()));
auto txtLeftOf = CreateTextBlock(L"LeftOfControl");
txtLeftOf.Foreground(SolidColorBrush(Colors::Blue()));
auto txtAbove = CreateTextBlock(L"AboveOfControl");
txtAbove.Foreground(SolidColorBrush(Colors::Blue()));
auto txtBelow = CreateTextBlock(L"BelowOfControl");
txtBelow.Foreground(SolidColorBrush(Colors::Green()));
auto txtHeader = CreateTextBlock(L"Modern C++/WinRT");
txtHeader.Foreground(SolidColorBrush(Colors::Red()));
txtHeader.HorizontalAlignment(HorizontalAlignment::Center);
txtHeader.VerticalAlignment(VerticalAlignment::Center);
txtHeader.Margin(CreateThickness(0, 10, 5, 100));
txtHeader.FontSize(25);
RelativePanel RPanel;
RPanel.Children().Append(txtTop);
RPanel.Children().Append(txtBottom);
RPanel.Children().Append(txtLeft);
RPanel.Children().Append(txtRight);
RPanel.Children().Append(txtHorCenter);
RPanel.Children().Append(txtVertical);
RPanel.Children().Append(txtRightOf);
RPanel.Children().Append(txtLeftOf);
RPanel.Children().Append(txtAbove);
RPanel.Children().Append(txtBelow);
RPanel.Children().Append(txtHeader);
RPanel.SetAlignTopWithPanel(txtTop,true);
RPanel.SetAlignBottomWithPanel(txtBottom, true);
RPanel.SetAlignLeftWithPanel(txtLeft, true);
RPanel.SetAlignRightWithPanel(txtRight, true);
RPanel.SetAlignVerticalCenterWithPanel(txtVertical, true);
RPanel.SetAlignHorizontalCenterWithPanel(txtHorCenter,true);
RPanel.SetRightOf(txtRightOf, PropertyValue::CreateInspectable(txtHorCenter));
RPanel.SetLeftOf(txtLeftOf, PropertyValue::CreateInspectable(txtHorCenter));
RPanel.SetAbove(txtAbove, PropertyValue::CreateInspectable(txtVertical));
RPanel.SetBelow(txtBelow, PropertyValue::CreateInspectable(txtVertical));
RPanel.SetRightOf(txtHeader, PropertyValue::CreateInspectable(txtVertical));
RPanel.Margin(CreateThickness(10, 10, 10, 10));
RPanel.BorderThickness(CreateThickness(1, 1, 1, 1));
RPanel.BorderBrush(SolidColorBrush(Colors::Blue()));
Window window = Window::Current();
window.Content(RPanel);
window.Activate();
}
int __stdcall wWinMain(HINSTANCE, HINSTANCE, PWSTR, int)
{
Application::Start([](auto &&) {make<App>(); });
return 0;
}

Output

All the C++/WinRT samples' code is give here.

Conclusion

I hope you understood how to use the RelativePanel control.