Responding to User Clicks at Runtime

• Oct 29, 2020
• 6 minutes to read

This article is dedicated to various events that can be handled to respond to end-user clicks at runtime.

In this example, the Navigation Bar will be used in a sample application (see the animation below) that utilizes the Navigation Frame - a single document interface (SDI) container that stores multiple pages, but can display only one page at a time. Clicking different child Navigation Bar items should switch active Navigation Frame pages. To do so, you will need to modify the NavigationFrame.SelectedPage property. Refer to the Navigation Frame article to learn about frame pages and ways to populate them.

A Navigation Bar provides two types of child items: items and groups. Items (and their links) are in turn divided into two more categories: regular push items and selectable items (switch between elevated and pressed states as end-users click them). Depending on what type of child items should be clicked to switch the active Navigation Frame page, you will need to handle different events.

Handling Individual Items’ Events

The most straightforward way to respond to clicking a Navigation Bar item at runtime is to handle the related event, raised by this very item. The only event available on this level is the NavBarItem.LinkClicked event. This event is provided by the item and will occur for any link related with this item. The code sample illustrates how to utilize this specific event.

C#

private void navBarItem1_LinkClicked(object sender, DevExpress.XtraNavBar.NavBarLinkEventArgs e) {
    navigationFrame1.SelectedPage = nfCustomersPage;
}

private void navBarItem2_LinkClicked(object sender, DevExpress.XtraNavBar.NavBarLinkEventArgs e) {
    navigationFrame1.SelectedPage = nfEmployeesPage;
}

VB.NET

Private Sub navBarItem1_LinkClicked(ByVal sender As Object, ByVal e As DevExpress.XtraNavBar.NavBarLinkEventArgs)
    navigationFrame1.SelectedPage = nfCustomersPage
End Sub

Private Sub navBarItem2_LinkClicked(ByVal sender As Object, ByVal e As DevExpress.XtraNavBar.NavBarLinkEventArgs)
    navigationFrame1.SelectedPage = nfEmployeesPage
End Sub

Handling Global Control Events

Handling click events for each particular child item is the most straightforward way to respond to end-users’ clicks. However, it is cumbersome. Any DevExpress navigation control provides one or multiple global events that occur when any child item is clicked. These global events allow you to keep your navigation logic in one spot. For the Navigation Bar control, you can handle one of the following global events.

• NavBarControl.ActiveGroupChanged - fires when a Navigation Bar group becomes active. At runtime this happens when a user clicks a group caption. Handle this event if your navigation elements are groups rather than items.

  C#

  void navBarControl_ActiveGroupChanged(object sender, DevExpress.XtraNavBar.NavBarGroupEventArgs e) {
      navigationFrame.SelectedPageIndex = navBarControl.Groups.IndexOf(e.Group);
  }
  

  VB.NET

  Private Sub navBarControl_ActiveGroupChanged(ByVal sender As Object, ByVal e As DevExpress.XtraNavBar.NavBarGroupEventArgs)
      navigationFrame.SelectedPageIndex = navBarControl.Groups.IndexOf(e.Group)
  End Sub
  

• NavBarControl.LinkClicked and NavBarControl.LinkPressed - fire when an end-user clicks a regular Navigation Bar item. Both events receive an argument of the NavBarLinkEventArgs type, which allows you to identify which specific nav bar item has been clicked. The difference between these events is that the LinkPressed event raises immediately after a user presses a link, while the LinkClick event occurs after the left mouse button is released.

  C#

  private void navBarControl1_LinkClicked(object sender, DevExpress.XtraNavBar.NavBarLinkEventArgs e) {
      navigationFrame1.SelectedPage = (NavigationPage)navigationFrame1.Pages.FindFirst(x => (string)x.Tag == e.Link.Caption);
  }
  

  VB.NET

  Private Sub navBarControl1_LinkClicked(ByVal sender As Object, ByVal e As DevExpress.XtraNavBar.NavBarLinkEventArgs)
      navigationFrame1.SelectedPage = CType(navigationFrame1.Pages.FindFirst(Function(x) CStr(x.Tag) = e.Link.Caption), NavigationPage)
  End Sub
  

• NavBarControl.SelectedLinkChanged - this event occurs when end-users click selectable Navigation Bar link. To enable link selection, utilize the NavBarControl.LinkSelectionMode property. Note that selectable links still raise both individual and global LinkClicked events, just like regular links do.

  C#

  private void navBarControl1_SelectedLinkChanged(object sender, DevExpress.XtraNavBar.ViewInfo.NavBarSelectedLinkChangedEventArgs e) {
      navigationFrame1.SelectedPage = (NavigationPage)navigationFrame1.Pages.FindFirst(x => (string)x.Tag == e.Link.Caption);
  }
  

  VB.NET

  Private Sub navBarControl1_SelectedLinkChanged(ByVal sender As Object, ByVal e As DevExpress.XtraNavBar.ViewInfo.NavBarSelectedLinkChangedEventArgs)
      navigationFrame1.SelectedPage = CType(navigationFrame1.Pages.FindFirst(Function(x) CStr(x.Tag) = e.Link.Caption), NavigationPage)
  End Sub
  

External Events

External events are those provided not by the target control itself. In case of a Navigation Bar, there can be two possible scenarios.

• Office Navigation Bar

  The Office Navigation Bar control can be hooked up to your Navigation Bar as its bottom panel (see the Interaction with Navigation Bar article to learn more). In this case, you can handle the OfficeNavigationBar.ItemClick events directly.

  C#

  private void officeNavigationBar1_ItemClick(object sender, NavigationBarItemEventArgs e) {
      navigationFrame1.SelectedPage = (NavigationPage)navigationFrame1.Pages.FindFirst(x => (string)x.Tag == e.Item.Text);
  }
  

  VB.NET

  Private Sub officeNavigationBar1_ItemClick(ByVal sender As Object, ByVal e As NavigationBarItemEventArgs)
      navigationFrame1.SelectedPage = CType(navigationFrame1.Pages.FindFirst(Function(x) CStr(x.Tag) = e.Item.Text), NavigationPage)
  End Sub
  

• Content Containers

  The figure below illustrates a very common scenario, where a Navigation Bar group displays a custom control instead of item links. In this example, the custom control is a Tree List that reflects an application hierarchy.

  

  For this scenario, you obviously cannot use any click events provided by the Navigation Bar. Instead, handle Tree List click events as the code sample below illustrates. This code uses the TreeList.CalcHitInfo method to identify whether or not the clicked Tree List element is a cell. If so, the active Navigation Frame page can be changed. The Frame is accessed through the public parentFrame property, declared in the main form class.

  C#

  //Main form with the Navigation Bar
  using DevExpress.XtraBars.Navigation;
  
  namespace MyApp {
      public partial class Form1 : DevExpress.XtraBars.Ribbon.RibbonForm {
  
          public NavigationFrame parentFrame {
              get {
                  return this.navigationFrame1;
              }
              private set {
              }
          }
  
          public Form1() {
              InitializeComponent();
          }
      }
  }
  
  //UserControl with the TreeList
  using System;
  using System.Windows.Forms;
  using DevExpress.XtraBars.Navigation;
  
  namespace MyApp {
      public partial class UserControl1 : UserControl {
          public UserControl1() {
              InitializeComponent();
              treeList1.Click += treeList1_Click;
  
          }
  
          void treeList1_Click(object sender, EventArgs e) {
              DevExpress.XtraTreeList.TreeList tree = sender as DevExpress.XtraTreeList.TreeList;
              DevExpress.XtraTreeList.TreeListHitInfo info = tree.CalcHitInfo(tree.PointToClient(MousePosition));
              if(info.HitInfoType == DevExpress.XtraTreeList.HitInfoType.Cell) {
                  Form1 parentForm = this.FindForm() as Form1;
                  parentForm.parentFrame.SelectedPage = (NavigationPage)parentForm.parentFrame.Pages.FindFirst(x => (string)x.Tag == info.Node.GetDisplayText(treeListColumn1));
              }
          }
      }
  }
  

  VB.NET

  Imports System.Windows.Forms
  Imports System
  
  'Main form with the Navigation Bar
  Imports DevExpress.XtraBars.Navigation
  
  Namespace MyApp 
      Partial Public Class Form1
          Inherits DevExpress.XtraBars.Ribbon.RibbonForm
  
          Public Property parentFrame() As NavigationFrame
              Get
                  Return Me.navigationFrame1
              End Get
              Private Set(ByVal value As NavigationFrame)
              End Set
          End Property
  
          Public Sub New()
              InitializeComponent()
          End Sub
      End Class
  End Namespace
  
  'UserControl with the TreeList
  
  Namespace MyApp 
      Partial Public Class UserControl1
          Inherits UserControl
  
          Public Sub New()
              InitializeComponent()
              AddHandler treeList1.Click, AddressOf treeList1_Click
  
          End Sub
  
          Private Sub treeList1_Click(ByVal sender As Object, ByVal e As EventArgs)
              Dim tree As DevExpress.XtraTreeList.TreeList = TryCast(sender, DevExpress.XtraTreeList.TreeList)
              Dim info As DevExpress.XtraTreeList.TreeListHitInfo = tree.CalcHitInfo(tree.PointToClient(MousePosition))
              If info.HitInfoType = DevExpress.XtraTreeList.HitInfoType.Cell Then
  
                  Dim parentForm_Renamed As Form1 = TryCast(Me.FindForm(), Form1)
                  parentForm_Renamed.parentFrame.SelectedPage = CType(parentForm_Renamed.parentFrame.Pages.FindFirst(Function(x) CStr(x.Tag) = info.Node.GetDisplayText(treeListColumn1)), NavigationPage)
              End If
          End Sub
      End Class
  End Namespace