Navigation Pane
- 5 minutes to read
The Navigation Pane is a multi-page content container that supports collapsed and expanded tabs. Navigation Pane tabs are NavigationPage objects.
Add Pages
At Design Time
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.
In Code
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" });
Customize Pages
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.
Captions, Icons, and Tooltips
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.
- Caption
- Specifies the text at the top of the page.
- ItemOrientation
- Set this property to
Orientation.Verticalto rotate tab header captions 90 degrees clockwise.
The following properties specify images or tooltips:
ImageandSvgImageaccessible through NavigationPage.ImageOptions- Specify a tab header image.
- NavigationPage.ToolTip
- Specifies a regular hint.
- NavigationPage.SuperTip
- Specifies a super tooltip.
Page Content
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
Controlscollection:Supply page content in the NavigationPane.QueryControl event. This event is raised when a Navigation Pane is about to display an empty 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; } }
Manipulate Pages
Change the Selected Page
Use the NavigationFrame.SelectedPage or NavigationFrame.SelectedPageIndex property to specify the active navigation page.
Expand, Collapse, and Resize Pages
The Navigation Pane supports three states:
- Regular
- The control occupies the area that its
Sizeproperty specifies. - Expanded
- The control occupies the area that its
MaximumSizeproperty specifies. - Collapsed
- Pages are hidden, and only the tab header area remains visible.
Use the following API to manipulate pages:
- NavigationPane.State
- Specifies the control state.
NavigationPane.PageProperties.ShowExpandButton/NavigationPane.PageProperties.ShowCollapseButton- Specifies whether all navigation pages display the expand/collapse button.
NavigationPage.Properties.ShowExpandButton/NavigationPage.Properties.ShowExpandButton- Specifies whether a navigation page displays the expand/collapse button.
- NavigationPane.AllowResize
- Specifies whether a user can drag the Page’s side border to resize it.
Overlay Resize
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:
Custom Header Buttons
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:
- NavigationPage.CustomButtonClick
- NavigationPage.CustomButtonChecked
- NavigationPage.CustomButtonUnchecked
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;
}
}
Keyboard Navigation
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.