Adorner Guides

• Apr 20, 2025
• 4 minutes to read

Guides are Adorner UI Manager elements that highlight an area within a parent form and display an optional description for this area.

Run Demo: Guides

Guides are objects of the Guide class. Key elements include:

Target element

The area to highlight (the AdornerElement.TargetElement property).

Flyout panel

The control with the description for the highlighted area (the AdornerUIManager.QueryGuideFlyoutControl event).

End-User Capabilities

A user can perform the following actions:

• Click an area with a guide to display the guide for this area.
• Press Esc to hide all guides.

Note

When guides are shown, a user cannot interact with the form’s UI elements. The adorner layer intercepts all mouse events.

Create a Guide

Design Time

1. Drop an Adorner UI Manager on the form.
2. Click the Edit Elements link in the Adorner UI Manager’s smart tag and create a guide in the Collection Editor dialog.
3. Assign the element you want to highlight to the AdornerElement.TargetElement property.

In Code

Create a Guide class instance, assign the element you want to highlight to the AdornerElement.TargetElement property, and add the guide to the AdornerUIManager.Elements collection:

C#

public Form1() {
    InitializeComponent();
    Guide guide1 = new Guide();
    guide1.TargetElement = ribbonPageGroup2;
    adorneruiManager1.Elements.Add(guide1);
}

VB.NET

Public Sub New()
    InitializeComponent()
    Dim guide1 As New Guide()
    guide1.TargetElement = ribbonPageGroup2
    adorneruiManager1.Elements.Add(guide1)
End Sub

Populate Flyout Panels

Enable a guide’s Properties.AllowFlyoutPanel property to display a flyout panel for this guide.

Handle the Adorner UI Manager’s QueryGuideFlyoutControl event to populate flyout panels. Use the following event parameters:

e.SelectedElement

Identifies the area for which the guide appears.

e.Control

Specifies the control to display within the corresponding guide’s flyout panel.

The following code snippet displays a label with an HTML-formatted text string as a guide flyout panel:

C#

void adornerUIManager1_QueryGuideFlyoutControl(object sender, QueryGuideFlyoutControlEventArgs e) {
    if (e.SelectedElement.TargetElement == ribbonPageGroup2) e.Control = new LabelControl() {
        AllowHtmlString = true,
        Width = 350,
        AutoSizeMode = LabelAutoSizeMode.Vertical,
        Padding = new Padding(20),
        Text = "<b>Skin Palette Gallery</b><br>" +
            "Shows palette options.<br><br>" +
            "You can select any palette in the drop-down menu."
    };
}

VB.NET

Private Sub adornerUIManager1_QueryGuideFlyoutControl(ByVal sender As Object, ByVal e As QueryGuideFlyoutControlEventArgs)
    If e.SelectedElement.TargetElement = ribbonPageGroup2 Then
        e.Control = New LabelControl() With {
            .AllowHtmlString = True,
            .Width = 350,
            .AutoSizeMode = LabelAutoSizeMode.Vertical,
            .Padding = New Padding(20),
            .Text = "<b>Skin Palette Gallery</b><br>" & "Shows palette options.<br><br>" & "You can select any palette in the drop-down menu."
        }
    End If
End Sub

The following image shows the result:

Flyout panels can display more complex content. In the following image, the flyout panel displays three buttons and a WindowsUI Button Panel.

Flyout panels adjust their size automatically to fit their content. To set a flyout display position, use the GuideDefaultProperties.FlyoutLocation property.

Manipulate Guides

Use the following API to show, hide, or select guides:

API	Task
AdornerUIManager.ShowGuides	Enable this property to show guides. Guides are displayed in the order of their TabIndex property values.
AdornerUIManager.SelectNext()	Display the next guide.
AdornerUIManager.SelectPrev()	Display the previous guide.
AdornerUIManager.SelectElement(AdornerElement)	Display a specific guide.

Appearance Settings

You can customize any guide element or the adorner layer:

Setting	Element to customize
Guide.Appearances	An individual guide (borders and the highlighted area).
AdornerUIManager.GuideAppearances	All guides.
AdornerUIManager.GuideProperties	All flyout panels.
Layer accessible in AdornerUIManager.GuideAppearances	The adorner layer.

Important

Use four-number ARGB values to assign semi-transparent colors.

C#

guide1.Appearances.Selected.BackColor = Color.FromArgb(100, 150, 0, 0);

VB.NET

guide1.Appearances.Selected.BackColor = Color.FromArgb(100, 150, 0, 0)

The following code snippet specifies custom colors for a guide, flyout panels, and the adorner layer:

C#

// Customize an individual guide
guide1.Appearances.Selected.BorderColor = Color.BlueViolet;
guide1.Appearances.Selected.BackColor = Color.FromArgb(100, 0, 0, 150);
// Customize the adorner layer
adorneruiManager1.GuideAppearances.Layer.BackColor = Color.FromArgb(100, 0, 50, 150);
// Customize flyout panels
adorneruiManager1.GuideProperties.FlyoutBackColor = Color.LightCyan;
adorneruiManager1.GuideProperties.FlyoutBorderColor = Color.Violet;

VB.NET

' Customize an individual guide
guide1.Appearances.Selected.BorderColor = Color.BlueViolet
guide1.Appearances.Selected.BackColor = Color.FromArgb(100, 0, 0, 150)
' Customize the adorner layer
adorneruiManager1.GuideAppearances.Layer.BackColor = Color.FromArgb(100, 0, 50, 150)
' Customize flyout panels
adorneruiManager1.GuideProperties.FlyoutBackColor = Color.LightCyan
adorneruiManager1.GuideProperties.FlyoutBorderColor = Color.Violet

The following image shows the result: