windowsforms-114555-controls-and-libraries-navigation-controls-navigation-pane.md
The Navigation Pane is a multi-page content container that supports collapsed and expanded tabs. Navigation Pane tabs are NavigationPage objects.
Select a Navigation Pane and click the Add Page button.
Open the control’s smart tag menu and click Add Page.
Open the control’s smart tag menu and click Pages. Add and remove pages in the collection editor dialog.
Add pages to the NavigationPane.Pages collection:
using DevExpress.XtraBars.Navigation;
navigationPane1.Pages.Clear();
navigationPane1.Pages.Add(new NavigationPage() { Caption = "My First Page", Name = "page1" });
navigationPane1.Pages.Add(new NavigationPage() { Caption = "My Second Page", Name = "page2" });
navigationPane1.Pages.Clear()
navigationPane1.Pages.Add(New DevExpress.XtraBars.Navigation.NavigationPage() With {.Caption = "My First Page", .Name = "page1"})
navigationPane1.Pages.Add(New DevExpress.XtraBars.Navigation.NavigationPage() With {.Caption = "My Second Page", .Name = "page2"})
Tab headers are arranged according to the control’s position on the form and are anchored to the control’s left edge ( default ). Change the Pane’s Dock property to Right to align headers to the right edge.
Use the NavigationPane.PageProperties.ShowMode property to specify whether the tab header should display text, an image, or both. The NavigationPage.Properties.ShowMode property overrides this setting for an individual page.
Use the following properties to customize page captions:
PageText Specifies the text displayed in the tab header area.CaptionSpecifies the text at the top of the page.ItemOrientationSet this property to Orientation.Vertical to rotate tab header captions 90 degrees clockwise.
The following properties specify images or tooltips:
Image and SvgImage accessible through NavigationPage.ImageOptionsSpecify a tab header image.NavigationPage.ToolTipSpecifies a regular hint.NavigationPage.SuperTipSpecifies a super tooltip.
Use one of the following techniques to fill pages with content:
Drag controls from the Toolbox and drop them onto the page surface to populate a page.
Design page content in a separate XtraUserControl and add this control’s instance to the page’s Controls collection:
Supply page content in the NavigationPane.QueryControl event. This event is raised when a Navigation Pane is about to display an empty Page.
Use the NavigationFrame.SelectedPage or NavigationFrame.SelectedPageIndex property to specify the active navigation page.
The Navigation Pane supports three states:
RegularThe control occupies the area that its Size property specifies.ExpandedThe control occupies the area that its MaximumSize property specifies.CollapsedPages are hidden, and only the tab header area remains visible.
Use the following API to manipulate pages:
NavigationPane.StateSpecifies the control state.NavigationPane.PageProperties.ShowExpandButton / NavigationPane.PageProperties.ShowCollapseButtonSpecifies whether all navigation pages display the expand/collapse button.NavigationPage.Properties.ShowExpandButton / NavigationPage.Properties.ShowExpandButtonSpecifies whether a navigation page displays the expand/collapse button.NavigationPane.AllowResizeSpecifies whether a user can drag the Page’s side border to resize it.
An overlay resize zone specifies the area near the page border that a user can click without interacting with underlying page elements. If this zone is too thin and clickable UI elements are close to the page border, users can accidentally click or resize these elements instead of resizing the page.
Activate the NavigationPane.AllowOverlayResize property to force the Navigation Pane to handle all clicks near its edge.
You can increase the NavigationPane.OverlayResizeZoneThickness property value to increase the overlay resize zone. In the following image, overlay resize zone thickness is set to 30:
Page headers display expand and collapse buttons. To add more buttons, modify the NavigationPage.CustomHeaderButtons collection at design time or in code and handle any of the following events:
using DevExpress.XtraBars.Navigation;
using DevExpress.XtraBars.Docking;
using DevExpress.XtraBars.Docking2010;
public Form1() {
InitializeComponent();
// Create custom buttons
CustomHeaderButton btn1 = new CustomHeaderButton() {
Caption = "Forward",
Style = ButtonStyle.PushButton
};
// Place the button before the "Collapse" button
btn1.VisibleIndex = -1;
CustomHeaderButton btn2 = new CustomHeaderButton() {
Caption = "Back",
Style = ButtonStyle.PushButton
};
// Place the button after the "Expand" button
btn2.VisibleIndex = 101;
// Add custom buttons to a tab header
navigationPage2.CustomHeaderButtons.AddRange(new CustomHeaderButton[] { btn1, btn2 });
navigationPage2.CustomButtonClick += NavigationPage2_CustomButtonClick;
}
// Change the selected page on a button click
void NavigationPage2_CustomButtonClick(object sender, ButtonEventArgs e) {
NavigationPage page = sender as NavigationPage;
NavigationPane pane = page.Parent as NavigationPane;
switch (e.Button.Properties.Caption) {
case ("Back"):
pane.SelectedPageIndex--;
break;
case ("Forward"):
pane.SelectedPageIndex++;
break;
}
}
Imports DevExpress.XtraBars.Navigation
Imports DevExpress.XtraBars.Docking
Imports DevExpress.XtraBars.Docking2010
Public Class Form1
Public Sub New()
InitializeComponent()
' Create custom buttons
Dim btn1 As New CustomHeaderButton() With {
.Caption = "Forward",
.Style = ButtonStyle.PushButton
}
' Place the button before the "Collapse" button
btn1.VisibleIndex = -1
Dim btn2 As New CustomHeaderButton() With {
.Caption = "Back",
.Style = ButtonStyle.PushButton
}
' Place the button after the "Expand" button
btn2.VisibleIndex = 101
' Add custom buttons to a tab header
navigationPage2.CustomHeaderButtons.AddRange(New CustomHeaderButton() {btn1, btn2})
AddHandler navigationPage2.CustomButtonClick, AddressOf NavigationPage2_CustomButtonClick
End Sub
' Change the selected page on a button click
Private Sub NavigationPage2_CustomButtonClick(sender As Object, e As ButtonEventArgs)
Dim page As NavigationPage = TryCast(sender, NavigationPage)
Dim pane As NavigationPane = TryCast(page.Parent, NavigationPane)
Select Case e.Button.Properties.Caption
Case "Back"
pane.SelectedPageIndex -= 1
Case "Forward"
pane.SelectedPageIndex += 1
End Select
End Sub
End Class
Ctrl+Tab and Ctrl+Shift+Tab shortcuts select the next/previous page.
You can activate the NavigationPane.AllowNavigationThroughPages option to allow users to focus page headers and use ←, →, Home, and End keys to navigate between headers.