ContextQMD
Back to Devexpress

RibbonForm Class

windowsforms-devexpress-dot-xtrabars-dot-ribbon-bb141f19.md

latest12.6 KB
Original Source

RibbonForm Class

A form that integrates a RibbonControl.

Namespace : DevExpress.XtraBars.Ribbon

Assembly : DevExpress.XtraBars.v25.2.dll

NuGet Package : DevExpress.Win.Navigation

Declaration

csharp
public class RibbonForm :
    XtraForm,
    ISupportGlassRegions,
    IBarObjectContainer,
    ISupportFormShadow,
    ICorrectSetBoundsCoreProvider
vb
Public Class RibbonForm
    Inherits XtraForm
    Implements ISupportGlassRegions,
               IBarObjectContainer,
               ISupportFormShadow,
               ICorrectSetBoundsCoreProvider

Remarks

A RibbonForm derives from the XtraForm class with the integrated Ribbon UI.

Create a RibbonForm

csharp
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;
        }
    }
}
vb
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

Outlook-inspired Side Navigation

Use the following properties to replicate the side navigation layout of Microsoft Outlook for Windows:

  • NavigationControl - specifies the navigation control as a side navigation element (such as an AccordionControl, NavigationPane, or ToolboxControl).
  • NavigationControlLayoutMode - Aligns the side navigation relative to the form’s title.

The following code snippet creates a side navigation inspired by the new Microsoft Outlook:

csharp
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);
        }
    }
}
vb
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

Outlook-inspired Side Pane

Assign a control to the RibbonForm.SidePane property to display this control as a panel to the right of the Ribbon.

Note

  • The side panel control must be added directly to the form’s Controls collection.
  • The Ribbon Form must be a window level control. If the Ribbon Form is a child control (for example, an MDI child form), the side panel control may exhibit unexpected behavior.

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.

In Code

csharp
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;
        }
    }
}
vb
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

Dual Captions

The form header consists of two parts that allow you to specify the application name and the name of the active document:

Application Button

In Office 2007 style, the Application Button is displayed within the title bar. In other styles, the button is displayed below the title bar.

Show/Hide the Button

Use the ShowApplicationButton property to show or hide the Application button:

csharp
// Show the Application Button.
ribbonControl1.ShowApplicationButton = DevExpress.Utils.DefaultBoolean.True;

// Hide the Application Button
ribbonControl1.ShowApplicationButton = DevExpress.Utils.DefaultBoolean.False;

Assign a Drop-Down Control

Use the ApplicationButtonDropDownControl property to display a drop-down control when the user clicks the Application Button. You can attach a BackstageViewControl or a custom menu:

csharp
// Attach a BackstageViewControl created at design time.
ribbonControl1.ApplicationButtonDropDownControl = backstageViewControl1;

// Or attach a custom popup menu.
// ribbonControl.ApplicationButtonDropDownControl = myPopupMenu;

Handle Button Click

Use the ApplicationButtonClick event to run custom code when the user clicks the button:

csharp
ribbonControl1.ApplicationButtonClick += (sender, e) => {
    // Insert your logic here.
    MessageBox.Show("Application Button clicked");
};

Specific Notes

  • The RibbonForm does not support RightToLeftLayout and RightToLeft properties.
  • Do not set the RibbonForm’s FormBorderStyle property to None.
  • Do not add a BarManager to a RibbonForm.

Important

When a DockManager is placed on a RibbonForm, you may notice slow performance during control startup rendering for complex projects. To resolve the issue, call the DockManager.ForceInitialize method on form loading.

Inheritance

Show 14 items

Object MarshalByRefObject Component Control ScrollableControl ContainerControl Form DevExpress.XtraEditors.DForm DevExpress.XtraEditors.MouseWheelContainerForm XtraForm RibbonForm AppointmentRibbonForm

PrintPreviewRibbonFormEx

XRDesignRibbonForm

See Also

RibbonForm Members

Ribbon Form

DevExpress.XtraBars.Ribbon Namespace