Navigation Pane

  • 6 minutes to read

The NavigationPane is a multi-page content container that supports collapsed and expanded tabs.

NavigationPane - Overview

Pages

Navigation Page tabs are NavigationPage class objects. Dropping a VS Toolbox control onto your form automatically adds two pages. You can add more pages by doing one of the following:

  • Select a Navigation Pane and click the "Add Page" button.

    NavigationPane - AddPage1

  • Invoke the control's smart tag and click the "Add Page" link.

    NavigationPane - AddPage2

  • Invoke the control's smart tag and click the "Pages" link. The invoked collection editor dialog allows you to add and remove pages, as well as specify their properties.

    NavigationPane - AddPage3

  • Add pages to the NavigationFrame.Pages collection in code.

    
    navigationPane1.Pages.Clear();
    navigationPane1.Pages.Add(new DevExpress.XtraBars.Navigation.NavigationPage() { Caption = "My First Page", Name = "page1" });
    navigationPane1.Pages.Add(new DevExpress.XtraBars.Navigation.NavigationPage() { Caption = "My Second Page", Name = "page2" });
    

Use the NavigationFrame.SelectedPage or NavigationFrame.SelectedPageIndex properties to choose the active navigation page.

Design-time Access

You need to modify properties that belong to the control and the individual pages it contains to customize the Navigation Pane. To set up page properties at design-time, click tab headers to bring the page to the front, and click its central area to select it. Page smart tags provide easy access to the most frequently used page settings.

NavigationPane - Designtime access

Page Content

You can drag controls from the VS Toolbox and drop them on a page's surface to populate a page. Or you can design your page content in a separate XtraUserControl and place this User Control instance inside a page. The latter can be done in two ways:

  • Add controls to the Page Controls collection.

    
    navigationPage1.Controls.Add(new MyUserControl1() { Dock = DockStyle.Fill });
    
  • Handle the NavigationFrame.QueryControl event. This event is raised when a Navigation Pane is about to display an empty Page. Event arguments allow you to identify this page and provide content to this page.

    
    private void NavigationPane1_QueryControl(object sender, DevExpress.XtraBars.Navigation.QueryControlEventArgs e) {
        switch (e.Page.Caption) {
            case ("Page 1"):
                e.Control = new MyUserControl1() { Dock = DockStyle.Fill };
                break;
            case ("Page 2"):
                e.Control = new MyUserControl2() { Dock = DockStyle.Fill };
                break;
            //. . .
        }
    }
    

Tab Header Orientation

Tab headers are arranged according to the control's position inside the form and are anchored to the control's left edge by default. Changing the Pane's Dock property to Dock.Right aligns headers to the right edge.

Navigation Pane - Dock

Page Captions and Icons

Navigation pages use the following interconnected properties to specify their captions and icons:

Navigation Pane - Tab Header Content

Expanding, Collapsing and Resizing Pages

End-users can expand and collapse the Navigation Pane using the corresponding buttons at a page's top right corner.

Navigation Pane - States

  • Regular state - the control occupies the area its Size property specifies.
  • Expanded state - the control occupies the area its MaximumSize property specifies.
  • Collapsed state - pages are hidden and only the tab header area remains visible.

Related API

  • NavigationPane.State - modify this property to set the control state manually.

  • NavigationPageDefaultProperties.ShowExpandButton[NavigationPageProperties.ShowExpandButton](xref:DevExpress.XtraBars.Navigation.NavigationPageProperties.ShowExpandButton) - specify whether this individual page\all navigation pages display the expand button.

  • NavigationPageDefaultProperties.ShowCollapseButton[NavigationPageProperties.ShowCollapseButton](xref:DevExpress.XtraBars.Navigation.NavigationPageProperties.ShowCollapseButton) - specify whether this individual page\all navigation pages display the collapse button.

End-users can also drag the Page side border to resize it. This allows the control to be any size between the MinimumSize and MaximumSize. To disable this feature, set the NavigationPane.AllowResize property to false.

Overlay Resize

An overlay resize zone specifies the area at a page's border that users can click without interacting with underlying page elements. If this zone is too thin and clickable UI elements are close to the page's border, users can accidentally click or resize these elements instead of resizing the page.

NavigationPane - Overlay 2

To avoid this, enable the NavigationPane.AllowOverlayResize property which forces the Navigation Pane to handle all clicks near its edge. You can increase the numeric NavigationPane.OverlayResizeZoneThickness property value to enlarge the overlay resize zone. For example, the following figure illustrates the same sample, but with the overlay resize zone thickness set to 30:

NavigationPane - Overlay 3

Custom Header Buttons

Page headers display the expand and collapse buttons by default. You can add more buttons that perform custom actions on the NavigationPage.CustomButtonClick, NavigationPage.CustomButtonChecked and NavigationPage.CustomButtonUnchecked events by modifying the NavigationPage.CustomHeaderButtons collection at design time or in code.


//Add buttons
navigationPage2.CustomHeaderButtons.Add(new DevExpress.XtraBars.Docking.CustomHeaderButton() {
    Caption = "Forward",
    //The Style property allows you to choose between regular (push) and check buttons
    //Check buttons can be grouped into a category to act like radio buttons
    Style = DevExpress.XtraBars.Docking2010.ButtonStyle.PushButton,
    //Tags are any objects that serve as unique page IDs
    Tag = "forward_button",
    //VisibleIndex specifies the button position
    //Set to a negative value to place a button before the default "Collapse" button
    //Set to a value greater than 100 to place a button after the default "Expand" button
    VisibleIndex = -1
});
navigationPage2.CustomHeaderButtons.Add(new DevExpress.XtraBars.Docking.CustomHeaderButton() {
    Caption = "Back",
    Style = DevExpress.XtraBars.Docking2010.ButtonStyle.PushButton,
    Tag = "back_button",
    VisibleIndex = 101
});

//Provide the button functionality
navigationPage2.CustomButtonClick += NavigationPage2_CustomButtonClick;

private void NavigationPage2_CustomButtonClick(object sender, DevExpress.XtraBars.Docking2010.ButtonEventArgs e) {
    NavigationPage page = sender as NavigationPage;
    NavigationPane pane = page.Parent as NavigationPane;
    switch (e.Button.Properties.Tag) {
        case ("back_button"):
            pane.SelectedPageIndex--;
            break;
        case ("forward_button"):
            pane.SelectedPageIndex++;
            break;
    }
}