windowsforms-114562-controls-and-libraries-forms-and-user-controls-ribbon-form.md
A RibbonForm integrates the Ribbon Control to deliver a Microsoft Office–inspired UI. This form type also features an Outlook-inspired side navigation.
The fastest way to start a project with a RibbonForm as the main form is to use UI-ready DevExpress templates. All templates that implement a Ribbon-based UI utilize Ribbon Forms.
To add a new Ribbon Form, right-click your project in Visual Studio’s Solution Explorer window and select Add DevExpress Item | New Item…. This will invoke the Template Gallery with new item templates. Select Ribbon Form , enter the form name, and click Add Item.
using DevExpress.XtraBars.Ribbon;
namespace MyApp {
public partial class MainForm : RibbonForm {
public MainForm() {
InitializeComponent();
InitializeRibbon();
}
void InitializeRibbon() {
// Set application and document captions
ribbonControl1.ApplicationCaption = "My Application";
ribbonControl1.ApplicationDocumentCaption = "Home Page";
// Create and customize the BackstageViewControl at design time
// Attach the BackstageViewControl to the RibbonControl
ribbonControl1.ApplicationButtonDropDownControl = backstageViewControl1;
}
}
}
Imports DevExpress.XtraBars.Ribbon
Namespace MyApp
Partial Public Class MainForm
Inherits RibbonForm
Public Sub New()
InitializeComponent()
InitializeRibbon()
End Sub
Private Sub InitializeRibbon()
' Set application and document captions.
ribbonControl1.ApplicationCaption = "My Application"
ribbonControl1.ApplicationDocumentCaption = "Home Page"
' Create and customize the BackstageViewControl at design time
' Attach the BackstageViewControl to the RibbonControl
ribbonControl1.ApplicationButtonDropDownControl = backstageViewControl1
End Sub
End Class
End Namespace
In the form’s smart tag menu, select Convert to Ribbon Form.
To do the same in code, add the DevExpress.XtraBars library and change the form’s base class to RibbonForm.
using DevExpress.XtraBars;
namespace DXApplication1 {
public partial class Form1 : RibbonForm {
public Form1() {
InitializeComponent();
}
}
}
Imports DevExpress.XtraBars
Namespace DXApplication1
Partial Public Class Form1
Inherits RibbonForm
Public Sub New()
InitializeComponent()
End Sub
End Class
End Namespace
The default Ribbon Form title is a text string assigned to the RibbonForm.Text property. You can use the following properties to override the title:
RibbonControl.ApplicationCaptionStores the form caption.RibbonControl.ApplicationDocumentCaptionStores the title of the currently selected MDI document.
To customize the caption color or font, add a DefaultBarAndDockingController to the form. The following properties are accessible through the BarAndDockingController.AppearancesRibbon property:
RibbonAppearances.FormCaptionGets the appearance settings used to paint a RibbonForm’s caption.RibbonAppearances.FormCaptionForeColor2Gets or sets the color used to paint the part of the RibbonForm’s caption specified by the RibbonControl.ApplicationDocumentCaption property.
using DevExpress.XtraBars;
defaultBarAndDockingController1.Controller.AppearancesRibbon.FormCaption.ForeColor = Color.LightGray;
defaultBarAndDockingController1.Controller.AppearancesRibbon.FormCaptionForeColor2 = Color.Lime;
Imports DevExpress.XtraBars
defaultBarAndDockingController1.Controller.AppearancesRibbon.FormCaption.ForeColor = Color.LightGray
defaultBarAndDockingController1.Controller.AppearancesRibbon.FormCaptionForeColor2 = Color.Lime
Use the following properties to replicate the side navigation layout of Microsoft Outlook for Windows:
The following code snippet creates a side navigation inspired by the new Microsoft Outlook:
using DevExpress.XtraBars.Navigation;
using DevExpress.XtraBars.Ribbon;
using System.Windows.Forms;
namespace DXApplication {
public partial class Form1 : RibbonForm {
AccordionControl accordion;
public Form1() {
InitializeComponent();
accordion = new AccordionControl() { Dock = DockStyle.Left };
this.Controls.Add(accordion);
this.NavigationControl = accordion;
this.NavigationControlLayoutMode = RibbonFormNavigationControlLayoutMode.StretchToFormTitle;
CreateAccordionItems();
}
void CreateAccordionItems() {
AccordionControlElement group1 = new AccordionControlElement(ElementStyle.Group) {
Name = "group1",
Text = "Contacts",
Expanded = true
};
AccordionControlElement item1 = new AccordionControlElement(ElementStyle.Item) {
Name = "itemCustomers",
Text = "Customers",
};
AccordionControlElement item2 = new AccordionControlElement(ElementStyle.Item) {
Name = "itemEmployees",
Text = "Employees"
};
group1.Elements.AddRange(new AccordionControlElement[] { item1, item2 });
accordion.Elements.Add(group1);
}
}
}
Imports DevExpress.XtraBars.Navigation
Imports DevExpress.XtraBars.Ribbon
Imports System.Windows.Forms
Namespace DXApplication
Public Partial Class Form1
Inherits RibbonForm
Private accordion As AccordionControl
Public Sub New()
InitializeComponent()
accordion = New AccordionControl() With {.Dock = DockStyle.Left}
Me.Controls.Add(accordion)
Me.NavigationControl = accordion
Me.NavigationControlLayoutMode = RibbonFormNavigationControlLayoutMode.StretchToFormTitle
CreateAccordionItems()
End Sub
Private Sub CreateAccordionItems()
Dim group1 As New AccordionControlElement(ElementStyle.Group) With {
.Name = "group1",
.Text = "Contacts",
.Expanded = True
}
Dim item1 As New AccordionControlElement(ElementStyle.Item) With {
.Name = "itemCustomers",
.Text = "Customers"
}
Dim item2 As New AccordionControlElement(ElementStyle.Item) With {
.Name = "itemEmployees",
.Text = "Employees"
}
group1.Elements.AddRange(New AccordionControlElement() {item1, item2})
accordion.Elements.Add(group1)
End Sub
End Class
End Namespace
Assign a control to the RibbonForm.SidePane property to display this control as a panel to the right of the Ribbon.
Note
Controls collection.The following code snippet assigns a side panel and toggles its visibility on a bar item click:
Note
panelControl1 and the Notifications check item were created and customized at design time.
using DevExpress.XtraBars.Navigation;
using System.Windows.Forms;
using DevExpress.XtraBars.Ribbon;
using DevExpress.XtraGrid.Columns;
using DevExpress.Utils;
using DevExpress.XtraEditors.Repository;
namespace ribbonSidePane {
public partial class Form1 : RibbonForm {
public Form1() {
InitializeComponent();
// Assign a side panel
this.SidePane = panelControl1;
panelControl1.Visible = false;
// Handle the "Notifications" check item's CheckedChanged event
Notifications.CheckedChanged += Notifications_CheckedChanged;
}
private void Notifications_CheckedChanged(object sender, DevExpress.XtraBars.ItemClickEventArgs e) {
// Toggle side panel visibility
this.SidePane.Visible = !this.SidePane.Visible;
}
}
}
Imports DevExpress.XtraBars.Navigation
Imports System.Windows.Forms
Imports DevExpress.XtraBars.Ribbon
Imports DevExpress.XtraGrid.Columns
Imports DevExpress.Utils
Imports DevExpress.XtraEditors.Repository
Namespace ribbonSidePane
Partial Public Class Form1
Inherits RibbonForm
Public Sub New()
InitializeComponent()
' Assign a side panel
Me.SidePane = panelControl1
panelControl1.Visible = False
' Handle the "Notifications" check item's CheckedChanged event
AddHandler Notifications.CheckedChanged, AddressOf Notifications_CheckedChanged
End Sub
Private Sub Notifications_CheckedChanged(sender As Object, e As DevExpress.XtraBars.ItemClickEventArgs)
' Toggle side panel visibility
Me.SidePane.Visible = Not Me.SidePane.Visible
End Sub
End Class
End Namespace
Activate the WindowsFormsSettings.FormThickBorder or WindowsFormsSettings.MdiFormThickBorder property to enlarge Ribbon Form borders and broaden the resize area.
Note
These settings affect all XtraForms and RibbonForms in the application.
Enlarged borders make it easier for users to resize forms when shadow/glow effects are off, and the default form resize area is too small.
If you wish to display the Quick Access Toolbar above the parent Ribbon, this toolbar will be shown within the Ribbon Form’s title bar.
The Ribbon Form integrates the RibbonStatusBar control. A status bar can also display a size grip element, which end users can drag to resize the Ribbon Form in both directions.
The BackstageView Control is the main application menu in a Ribbon.
Note
If the RibbonControl.RibbonStyle is set to Office2007, the main application menu is an ApplicationMenu object.
To customize the application menu, assign a BackstageView control to the RibbonControl.ApplicationButtonDropDownControl property and configure properties of the BackstageView control.
The backstage menu has its own styles. Specify the BackstageViewControl.Style property to change the menu style.
The following styles are available:
Office 2010The backstage menu keeps the form’s title bar and ribbon page headers visible.
Office 2013The BackstageView control occupies the entire form. To display Ribbon items, specify the BackstageViewControl.BackstageViewShowRibbonItems property.
When the Ribbon Control uses the Office 2013 style, the Ribbon Form displays an additional button next to the standard Minimize , Maximize , and Close buttons.
This button opens a menu with available display modes for the Ribbon Control.
RibbonControl.ShowDisplayOptionsMenuButtonDeactivate this option to hide the Display Options button.OptionsExpandCollapseMenu.EnableExpandCollapseMenuActivate this option to enable the Ribbon Display Options popup menu and hide the Display Options button from the form title.
For Windows Vista and 7, Ribbon Forms include built-in support for the Aero Glass effect. If your application runs on one of these operating systems and the Aero effect is enabled in system settings, the form title bar and borders are semi-transparent.
To disable this effect even if the operating system has the Aero interface on, set the RibbonForm.AllowFormGlass property to DefaultBoolean.False.