RadialMenu is a ContextMenu. It inherits directly from System.Windows.Controls.ContextMenu and can be set as the context menu of any element. For the most part, what is true about ContextMenu is also true about RadialMenu and if you wish to use it as a context menu it works the same way. Unlike ContextMenu, however, RadialMenu is designed to be opened with the click of a button.

RadialMenuButton is a Button that has been designed to work seamlessly with RadialMenu. Use it in your UI as you would any Button. It has a property named RadialMenu to which you assign the RadialMenu that the button is to open.

The native container type for items in a RadialMenu is RadialMenuItem. RadialMenuItem does not actually inherit from MenuItem, but it does share most of the dependency properties and routed events that are defined by MenuItem. (The reason it doesn’t derive directly from MenuItem is MenuItem makes certain assumptions about how it should behave which are not compatible with RadialMenu.) The base class of RadialMenuItem is HeaderedItemsControl.

Item Hierarchy

Instances of RadialMenuItem can be added directly to a RadialMenu via its Items property. This can be done in Xaml or code. Alternatively, the menu items can be defined via the ItemsSource property, which is of type IEnumerable. ItemsSource members can be objects of any type. When a member of the ItemsSource collection is not a RadialMenuItem, a RadialMenuItem is created which becomes the “container” for the item. When this is the case, you should use a style for the RadialMenuItem which provides a mapping between your data object’s properties and properties of the control such as Header and Icon. There is an example of this in the sample application RadialMenuSample, on the MVVM based sample page.

RadialMenu supports multiple levels. That is, menu items can have children of their own. Both RadialMenu and RadialMenuItem derive from ItemsControl so the mechanism for defining children is the same for both.

There is no limit to the depth of the hierarchy.

Headers and Icons

The two main properties of RadialMenuItem which define its purpose and use for the user are the Header and Icon properties. Both of these properties are of type object, meaning that their values can legally be anything. In the case when the value is not a UI element, then a DataTemplate must be applied which shows how to render the object. When a DataTemplate is not supplied, the fallback behavior is to display the string obtained from calling the object’s ToString method.

To apply a DataTemplate for a menu item’s Header which is applied to all menu items, use the ItemTemplate property of the parent RadialMenu. To define a DataTemplate for the Header of a single RadialMenuItem, use the item’s HeaderTemplate property. Similarly for the icon: To apply a DataTemplate for a menu item’s Icon which is applied to all menu items, use the IconTemplate property of the parent RadialMenu. To define a DataTemplate for the Icon of a single RadialMenuItem, use the item’s IconTemplate property.

There are also icons for the button to consider. The main button icon is defined by the button’s Content property and the data template for it is the ContentTemplate property. Additionally, RadialMenu has a CenterIcon property. It is necessary for when the radial menu is being used as a standard context menu and the button is an integral part of the radial menu itself. The button’s Content takes precedence over the radial menu’s CenterIcon.

If the ContentTemplate property of a RadialMenuButton is not set, then it will be bound to the IconTemplate property of the associated RadialMenu.

There is also an icon of the radial menu button which is displayed when a submenu is open and a click of the button closes the submenu. This is what the BackButtonIcon property of RadialMenuButton is for. There is a default back button icon which is used when BackButtonIcon is not set. Note that, unless the default is used, the data template for BackButtonIcon is the same as it is for the button’s Content or main icon.

Color Theme

In addition to the default appearance, there are six different color themes built-in. They are Red, Blue, Green, Orange, Yellow and Purple. The color theme is specified by the ColorTheme property of RadialMenu. (RadialMenuButton also exposes the ColorTheme property, for added convenience.)

If none of the built-in color themes suit your needs, you can create your own by overriding a few Brush resources which are referenced with DynamicResource. Here is an example which uses all the customizable resources, taken from the sample app RadialMenuSample that ships with DotNetBar.

<SolidColorBrush x:Key="{x:Static dc:RadialMenuItem.HeaderRegionHoverFillKey}" Color="#FF353643" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenuItem.HeaderRegionHighlightGlyphFillKey}" Color
="#FFF1F1F7" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenuItem.ExpanderRegionFillKey}" Color
="#FFA4A4BC" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenuItem.ExpanderRegionGlyphFillKey}" Color
="#424242" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenuItem.ExpanderRegionHoverFillKey}" Color
="#FFF5ECE8" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenu.CenterButtonHoverFillKey}" Color
="#414141" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenu.CenterButtonPressedFillKey}" Color
="#212121" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenu.CenterButtonFillKey}" Color
="#212121" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenu.CenterButtonStrokeKey}" Color
="#FFF1F1F7" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenu.BackgroundKey}" Color
="#212121" />
<
SolidColorBrush x:Key="{x:Static dc:RadialMenu.BorderBrushKey}" Color="#FF5C5D73"
/>

Custom ToolTip Handling

If you assign tool tips to your menu items, you may appreciate the custom tool tip handling, provided by default by RadialMenu, which causes tool tips to be opened at the top of the menu and gives them custom styling. To turn off this feature, set the radial menu’s UseCustomToolTipHandling to false. To further customize the tooltip style, define a style for ToolTip and assign it the ComponentResourceKey RadialMenu.ToolTipStyleKey. Here is an example:

<Style x:Key="{x:Static dc:RadialMenu.ToolTipStyleKey}" TargetType="ToolTip">
    <Setter Property="Padding" Value="10,6" />
    <Setter Property="BorderThickness" Value="2" />
    <Setter Property="Foreground" Value="#FFF1F1F7" />
    <Setter Property="BorderBrush" Value="#FFF1F1F7" />
    <Setter Property="Background" Value
="#FF353643" />
</
Style
>

Number of Segments

By default, the number of segments which the radial menu is divided into is equal to the number of menu items it contains. In other words, if your menu has 6 items, then by default the circle which defines the radial menu will be divided into 6 equally sized pieces, or segments. But what if there are less than 6 items in the menu, but you want the segments to be sized as there were 6? This is what the MinimumSegmentCount property is for. It defines the minimum number of segments that the circle will be divided into, regardless of the number of items being shown. RadialMenuItem also has a MinimumSegmentCount property that, if unset, defaults to the value of the parent menu’s MinimumSegmentCount.

Sizing

  • The radius of a RadialMenu is determined by its Radius property. If both Width and Height are set, then Radius will be automatically set as one half of the minimum of the two.
  • The thickness of the outer ring is determined by the Top of the Thickness of the BorderThickness property.
  • The thickness of the stroke defining the circular radial menu button is determined by the Top of the Thickness of its BorderThickness property.
  • The InnerRadius property specifies the radius of the inner circle, which defines the border between where the center button is activated by the mouse and where a menu item is activated.

Drag Move

A kind of bonus feature of RadialMenuButton is that it can be configured so that the user can reposition it by dragging it with the mouse. To enable this feature, the button’s set the buttton’s IsDragMoveEnabled property to true. What this does is it enables a thumb that is part of the default template for RadialMenuButton. The thumb, when enabled, raises its DragDelta routed event when the user drags it and a handler for the event updates the attached properties Canvas.Top and Canvas.Left on the button. Because of this, the RadialMenuButton needs to be the direct child of a Canvas for drag move to havve an effect. The layout slot of the canvas (obtained via LayoutInformation.GetLayoutSlot) defines the area in which the button can be moved.

An Example

Below is an example of a radial menu defined in Xaml. Notice that the icons are actually characters from the Font Awesome font. (Font Awesome is freely available.) A DataTemplate is used to set up a TextBlock so it uses the custom font for displaying the icon. This snippet was taken from the sample project RadialMenuSample.

<dc:RadialMenu x:Key="RadialMenu" UseCustomToolTipHandling="True">
    <dc:RadialMenu.IconTemplate>
        <DataTemplate>
            <!-- Using FontAwesome as source for menu item icons. The font is an embedded resource of this project. -->
            <TextBlock Text="{Binding}" FontFamily="/Resources/#FontAwesome" FontSize="17" />
        </DataTemplate>
    </dc:RadialMenu.IconTemplate>
    <dc:RadialMenuItem Header="Camera" Icon="&#xf030;" ToolTip="Camera" />           
    <dc:RadialMenuItem Header="Picture" Icon="&#xf03e;" ToolTip="Picture" />
    <dc:RadialMenuItem Header="Table" Icon="&#xf0ce;" ToolTip="Table" />
    <dc:RadialMenuItem Header="List" Icon="&#xf00b;" ToolTip="List">
        <dc:RadialMenuItem Index="2" Header="Ordered" Icon="&#xf0cb;" ToolTip="OrderedList" />
        <dc:RadialMenuItem Index="3" Header="Unordered" Icon="&#xf0ca;" ToolTip="Unordered List" />
    </dc:RadialMenuItem>
    <dc:RadialMenuItem MinimumSegmentCount="4" Header="Alignment" Icon="&#xf037;" ToolTip="Alignment">
        <dc:RadialMenuItem Header="Center" Icon="&#xf037;" ToolTip="Align Center" />
        <dc:RadialMenuItem Header="Left" Icon="&#xf036;" ToolTip="Align Left" />
        <dc:RadialMenuItem Header="Right" Icon="&#xf038;" ToolTip="Align Right" />
        <dc:RadialMenuItem Header="Justify" Icon="&#xf039;" ToolTip="Align Justify" />
    </dc:RadialMenuItem>
    <dc:RadialMenuItem Header="Undo" Icon="&#xf0e2;" ToolTip="Undo" />
    <dc:RadialMenuItem Header="Tag" Icon="&#xf02b;" ToolTip="Tag">
        <dc:RadialMenuItem Header="To Do" Icon="&#xf046;" ToolTip="To Do" ClickAction="CloseSubmenu" />
        <dc:RadialMenuItem Header="Favorite" Icon="&#xf005;" ToolTip="Favorite" ClickAction="CloseSubmenu" />
        <dc:RadialMenuItem Header="Critical" Icon="&#xf12a;" ToolTip="Critical" ClickAction="CloseSubmenu" />
        <dc:RadialMenuItem Header="Question" Icon="&#xf128;" ToolTip="Question"  ClickAction="CloseSubmenu"/>
        <dc:RadialMenuItem Header="Info" Icon="&#xf179;" ToolTip="Info" ClickAction="CloseSubmenu"/>
        <dc:RadialMenuItem Header="Phone Number" Icon="&#xf095;" ToolTip="Phone Number" ClickAction="CloseSubmenu"/>
    </dc:RadialMenuItem>
    <dc:RadialMenuItem Header="Draw" Icon="&#xf040;" ToolTip
="Draw" />
</
dc:RadialMenu
>

And here is the RadialMenuButton which opens the above RadialMenu. Notice that it is inside a Canvas so that drag/move will work.

Canvas>
    <dc:RadialMenuButton Name="RadialMenuButton" RadialMenu="{StaticResource RadialMenu}"                          
                        ColorTheme="Red" Canvas.Top="100" Canvas.Left="200" 
                        Content="&#xf0f7;" BackButtonIcon="&#xf060;" IsDragMoveEnabled
="True" />
</
Canvas
>

Further Exploration

The best place to begin exploring RadialMenu, other than this document, is with the RadialMenu sample, which is included with the installation of DotNetBar. This is a screen shot of the RadialMenu sample app, running on Windows 8.1:

RadialMenuSample

Related posts:

  1. Brush Control Quick Start Guide
  2. ToggleSwitch Quick Start Guide
  3. Wizard for WPF Quick Start Guide
  4. ProgressSteps Quick Start Guide, DotNetBar for WPF
  5. MobileRibbon Quick Start Guide, DotNetBar for WPF