RadControls for WPF
Contents

Telerik RadRibbonBar provides a simple and consistent way for building interfaces similar to the RibbonBar used in Microsoft Office. The RadRibbonBar consists of various elements, one of which is the Application Menu. This topic discusses concepts fundamental to the Application Menu at first and then goes into the usage of the ApplicationMenu class and its features.

Tip
Before proceeding with this tutorial, it is recommended to get familiar with the Visual Structure of the RadRibbonBar control.

Application Menu - Fundamentals

The Application Menu is equivalent to the File menu of the traditional menu UIs. By default it is represented by the circular button (named Application Button) on the upper-left corner of the RadRibbonBar control.

The Application Menu appears when a user clicks the Application Button. This menu displays controls used to perform actions on the entire document, like Save, Print and Send. The Application Menu also provides a list of recent documents, access to application options for changing user settings and preferences, and application exit.

Note

The class that represents the application menu is Telerik.Windows.Controls.ApplicationMenu.

The ApplicationMenu is an ItemsControl (it derives from ItemsControl), which consists of three parts:

  • Menu Items - they are populated by using the ApplicationMenu's Items property. For items it is handy to use the RadRibbonButton, RadRibbonSplitButton and RadRibbonDropDownButton controls. They will be styled automatically to fit into the ApplicationMenu styles.
  • Content - this is the right pane of the application menu. To populate it you should use the ApplicationMenu's Content property and set the content you like.
  • Footer Content - this is the bottom pane of the application menu. Here are usually placed application options and exit buttons. In order to populate this area you need to use the ApplicationMenu's FooterContent property and set the content you like.

Check out the rest of this topic, which is entirely dedicated to the ApplicationMenu.

Adding Application Menu to a RadRibbonBar Control

In order to add an application menu to your RadRibbonBar control you need to set the RadRibbonBar's ApplicationMenu property. The next several code-snippets show you how to do that in XAML, as well as in the code-behind.

CopyXAML
<telerik:RadRibbonBar x:Name="radRibbonBar">
    <telerik:RadRibbonBar.ApplicationMenu>

        <telerik:ApplicationMenu>
        </telerik:ApplicationMenu>

    </telerik:RadRibbonBar.ApplicationMenu>
</telerik:RadRibbonBar>
CopyC#
this.radRibbonBar.ApplicationMenu = new ApplicationMenu();
CopyVB.NET
Me.radRibbonBar.ApplicationMenu = New ApplicationMenu()

Setting an Application Button Image

The default look of the application button is an empty circular button similar to the next snapshot.

When you want to add an image to the application button, you can do it through the RadRibbonBar's ApplicationButtonImageSource property.

CopyXAML
<telerik:RadRibbonBar x:Name="radRibbonBar" ApplicationButtonImageSource="/RadRibbonBarSample;component/Images/IconMSOffice/AppIcon.png">
    <telerik:RadRibbonBar.ApplicationMenu>
        <telerik:ApplicationMenu>
        </telerik:ApplicationMenu>
    </telerik:RadRibbonBar.ApplicationMenu>
</telerik:RadRibbonBar>
CopyC#
this.radRibbonBar.ApplicationButtonImageSource = new BitmapImage( new Uri( ImagePath, UriKind.Relative ) );
CopyVB.NET
Me.radRibbonBar.ApplicationButtonImageSource = New BitmapImage(New Uri(ImagePath, UriKind.Relative))

Changing the Application Button Type

The default type of the application button is the Office2007, illustrated bellow:

If you want to use the Office2010 Application Button type instead, you can set the RadRibbonBar's ApplicationButtonType property. The property is an ApplicationButtonType enumeration which exposes the following members:

  • Office2007- use it to set a circle Application Button type.
  • Office2010 - use it to set the Office2010 rectangle Application Button type.

CopyXAML
<telerik:RadRibbonBar x:Name="radRibbonBar" ApplicationButtonType="Office2010">
    <telerik:RadRibbonBar.ApplicationMenu>
        <telerik:ApplicationMenu>
        </telerik:ApplicationMenu>
    </telerik:RadRibbonBar.ApplicationMenu>
</telerik:RadRibbonBar>
CopyC#
this.radRibbonBar.ApplicationButtonType = ApplicationButtonType.Office2010;
CopyVB.NET
Me.radRibbonBar.ApplicationButtonType = ApplicationButtonType.Office2010;

Adding Menu Items

When you want to add menu items to your RadRibbonBar's application menu, you need to populate the ApplicationMenu's Items collection. It is handy to use the RadRibbonButton, RadRibbonSplitButton, RadRibbonDropDownButton and Separator controls.

Tip
For more information about the different types of RadRibbonButtons and their properties, take a look at the Ribbon Buttons topic.

The next example demonstrates how to add several buttons as menu items to your application menu.

CopyXAML
<telerik:RadRibbonBar Margin="8" x:Name="radRibbonBar" >
    <telerik:RadRibbonBar.ApplicationMenu>
        <telerik:ApplicationMenu>

            <telerik:RadRibbonButton
    Text="New" LargeImage="/RadRibbonBarSample;component/Images/IconPaint/menu/new.png"/>
            <telerik:RadRibbonButton
    Text="Open" LargeImage="/RadRibbonBarSample;component/Images/IconPaint/menu/open.png"/>
            <telerik:RadRibbonButton
    Text="Save" LargeImage="/RadRibbonBarSample;component/Images/IconPaint/menu/save.png"/>

            <telerik:RadRibbonSplitButton Text="Save As" LargeImage="/RadRibbonBarSample;component/Images/IconPaint/menu/save_as.png">
                <telerik:RadRibbonSplitButton.DropDownContent>
                    <StackPanel HorizontalAlignment="Stretch" >
                        <telerik:RadGroupHeader Content="Save as"/>
                        <telerik:RadRibbonButton Margin="1 0 2 0"  Width="292" >
                            <StackPanel Orientation="Horizontal"  Margin="3 0  5 0">
                                <Image Stretch="None"  Source="/RadRibbonBarSample;component/Images/IconMSOffice/ApplicationMenu/worddoc.png" />
                                <StackPanel Margin="5 5 0 0">
                                    <TextBlock  Text="Word Document " FontWeight="Bold"/>
                                    <TextBlock TextWrapping="Wrap" Width="220"  Text="Save the file as a Word Document." />
                                </StackPanel>
                            </StackPanel>
                        </telerik:RadRibbonButton>
                    </StackPanel>
                </telerik:RadRibbonSplitButton.DropDownContent>
            </telerik:RadRibbonSplitButton>

            <telerik:Separator />

            <telerik:RadRibbonDropDownButton  Text="Prepare" LargeImage="/RadRibbonBarSample;component/Images/IconMSOffice/ApplicationMenu/Prepare32.png">
                <telerik:RadRibbonDropDownButton.DropDownContent>
                    <StackPanel HorizontalAlignment="Stretch" >
                        <telerik:RadGroupHeader Content="Prepare"/>
                        <telerik:RadRibbonButton Margin="1 0 2 0"  Width="292" >
                            <StackPanel Orientation="Horizontal"  Margin="3 0  5 0">
                                <Image Stretch="None"  Source="/RadRibbonBarSample;component/Images/IconPaint/menu/print.png" />
                                <StackPanel Margin="5 5 0 0">
                                    <TextBlock  Text="Properties " FontWeight="Bold"/>
                                    <TextBlock TextWrapping="Wrap" Width="220" Text="View and edit document properties." />
                                </StackPanel>
                            </StackPanel>
                        </telerik:RadRibbonButton>
                    </StackPanel>
                </telerik:RadRibbonDropDownButton.DropDownContent>
            </telerik:RadRibbonDropDownButton>

        </telerik:ApplicationMenu>
    </telerik:RadRibbonBar.ApplicationMenu>
</telerik:RadRibbonBar>

Three ordinary RadRibbonButtons, one RadRibbonSplitButton and one RadRibbonDropDownButton are added. Also note the way for adding a separator element - <telerik:Separator />. The result can be seen on the snapshot below.

Adding Content

The second element you may want to initialize when building an application menu is the Content. This is the right pane of the application menu. To populate it you should use the ApplicationMenu's Content property and set the content you like.

The next example shows you how to set the ApplicationMenu's Content property. Note that in this example the initialization of the menu items is skipped.

CopyXAML
<telerik:RadRibbonBar x:Name="radRibbonBar">
    <telerik:RadRibbonBar.ApplicationMenu>
        <telerik:ApplicationMenu>

            <telerik:ApplicationMenu.Content>

                <StackPanel Width="300">
                    <telerik:RadGroupHeader Content="Recent Documents"/>
                    <telerik:RadRibbonButton Content="1 RIAServices.docx" HorizontalAlignment="Stretch"/>
                    <telerik:RadRibbonButton Content="2 SL4 Survey.docx" HorizontalAlignment="Stretch"/>
                    <telerik:RadRibbonButton Content="3 RadTileView Features.docx" HorizontalAlignment="Stretch"/>
                    <telerik:RadRibbonButton Content="4 RadTreeView TOC.docx" HorizontalAlignment="Stretch"/>
                    <telerik:RadRibbonButton Content="5 RadRibbonBar API.docx" HorizontalAlignment="Stretch"/>
                    <telerik:RadRibbonButton Content="6 Profile.docx" HorizontalAlignment="Stretch"/>
                </StackPanel>

            </telerik:ApplicationMenu.Content>

        </telerik:ApplicationMenu>
    </telerik:RadRibbonBar.ApplicationMenu>
</telerik:RadRibbonBar>

Adding Footer Content

The last element of the application menu is the Footer Content. This is the bottom pane of the application menu. Here are usually placed application options and exit buttons. In order to initialize it you need to set the ApplicationMenu's FooterContent property like in the example below.

CopyXAML
<telerik:RadRibbonBar x:Name="radRibbonBar">
    <telerik:RadRibbonBar.ApplicationMenu>
        <telerik:ApplicationMenu>

            <telerik:ApplicationMenu.FooterContent>

                <StackPanel Height="25" Orientation="Horizontal" >
                    <telerik:RadButton Width="106" Height="22" Margin="3 0">
                        <telerik:RadButton.Content>
                            <StackPanel Orientation="Horizontal" VerticalAlignment="Center" Margin="3 0  5 0">
                                <Image Width="16" Height="16" Source="/RadRibbonBarSample;component/Images/IconPaint/16/options.png" />
                                <TextBlock Margin="4 0 0 0" VerticalAlignment="Center" Text="Word Options" />
                            </StackPanel>
                        </telerik:RadButton.Content>
                    </telerik:RadButton>
                    <telerik:RadButton Width="86" Height="22" Margin="3 0 2 0">
                        <telerik:RadButton.Content>
                            <StackPanel Orientation="Horizontal" VerticalAlignment="Center" Margin="3 0  5 0">
                                <Image Width="16" Height="16" Source="/RadRibbonBarSample;component/Images/IconPaint/16/exit.png" />
                                <TextBlock Margin="4 0 0 0" VerticalAlignment="Center" Text="Exit Word" />
                            </StackPanel>
                        </telerik:RadButton.Content>
                    </telerik:RadButton>
                </StackPanel>

            </telerik:ApplicationMenu.FooterContent>

        </telerik:ApplicationMenu>
    </telerik:RadRibbonBar.ApplicationMenu>
</telerik:RadRibbonBar>

In this example, it is assumed that you are familiar with initializing the menu items and content of the application menu. If not, check out the previous two sections where the process of adding menu items and content is described. The result of the last example is shown on the snapshot below.

Hiding the Application Menu

Whenever you want to prevent the end-user from using the application menu, you should set the RadRibbonBar's ApplicationButtonVisibility property to Visibility.Collapsed. On the contrary, if you want run-time to enable (show) again the application menu, then set the ApplicationButtonVisibility property to Visibility.Visible.

Tip
The default value of the RadRibbonBar's ApplicationButtonVisibility property is Visibility.Visible.

The next code snippet demonstrates how to completely hide the application menu.

CopyXAML
<telerik:RadRibbonBar x:Name="radRibbonBar" ApplicationButtonVisibility="Collapsed">
CopyC#
radRibbonBar.ApplicationButtonVisibility = Visibility.Collapsed;
CopyVB.NET
radRibbonBar.ApplicationButtonVisibility = Visibility.Collapsed

Events

The RadRibbonBar class exposes the ApplicationButtonDoubleClick event, which is fired when the RibbonBar's ApplicationButton is double-clicked.

CopyXAML
<telerik:RadRibbonBar x:Name="radRibbonBar" ApplicationButtonDoubleClick="radRibbonBar_ApplicationButtonDoubleClick">

The ApplicationButtonDoubleClick event handler receives two arguments:

  • The sender argument contains the RadRibbonBar. This argument is of type object, but can be cast to the RadRibbonBar type.
  • The second argument is a RadRoutedEventArgs object.
CopyC#
private void radRibbonBar_ApplicationButtonDoubleClick( object sender, RadRoutedEventArgs e )
{
    RadRibbonBar ribbonBar = sender as RadRibbonBar;
    // Do some custom logic here.
}
CopyVB.NET
Private Sub radRibbonBar_ApplicationButtonDoubleClick(ByVal sender As Object, ByVal e As RadRoutedEventArgs)
        ' Do some custom logic here.
    Dim ribbonBar As RadRibbonBar = TryCast(sender, RadRibbonBar)
End Sub

One common scenario is to close the application when the user makes a double-click on the application button.

For a full list of the exposed by the RadRibbonBar events, take a look at the Events - Overview topic.

The RadRibbonBar is a complex control and the application menu is only a small part of it. The RadRibbonBar consists of various elements such as:

Additional features that you may find interesting are:

See Also