[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications, and Dialogs
  [Collapse]Editors and Simple Controls
    Included Controls and Components
   [Expand]Common Editor Features and Concepts
   [Expand]Lookup Editors
    Popup Container Editor
   [Expand]Token Edit Control
   [Collapse]Breadcrumb Edit Control
     Breadcrumb Modes
     How to: Create Breadcrumb Nodes at Design Time
     How to: Create Breadcrumb Nodes at Runtime
     How To: Add Custom Buttons to the Breadcrumb Edit Control
     How To: Create a File Explorer
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
    Templated ListBox Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Gantt Control
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Breadcrumb Edit Control

The Breadcrumb Edit Control (represented by the BreadCrumbEdit class object in code) emulates a navigation bar, similar to the one displayed in Microsoft Explorer starting from Windows 7 (see the following figure).

This control allows you to build a node hierarchy, where each node is related to one or many child nodes. At runtime the control displays your current position within this tree. The image below illustrates an example: a sample node hierarchy with the highlighted user position within it. The figure on the right demonstrates the Breadcrumb Edit Control reflecting this position at runtime.

Expanded Integration With TreeList

You can pair a BreadCrumbEdit and TreeList control to implement a breadcrumb navigation through the TreeList hierarchy. In pairing mode, the BreadCrumbEdit automatically syncs its hierarchy and selection with the TreeList. See Breadcrumb Navigation to learn more.

Expanded Concepts and Visual Elements

This section describes Breadcrumb Edit Control's cornerstones, crucial for understanding the editor's mechanics.

  • Nodes

    The fundamental Breadcrumb Edit Control's element is a node - an object of the BreadCrumbNode class that can store other nodes within its BreadCrumbNode.ChildNodes collection. Each node has a caption, value (the BreadCrumbNode.Caption and BreadCrumbNode.Value properties respectively) and image (the BreadCrumbNode.ImageIndex property). Node images are displayed only within the drop-down lists (see below). You can also insert an image before the very first node by specifying the RepositoryItemBreadCrumbEdit.RootGlyph property (see the figure below). Clicking this root glyph raises the RepositoryItemBreadCrumbEdit.RootGlyphClick event.

  • Paths

    The current position within the node tree is called a path and stored within the BreadCrumbEdit.Path property. A path string consists of node values, separated by a separator character, stored within the RepositoryItemBreadCrumbEdit.PathSeparator property.

    At runtime the path is presented as a sequence of click-able node elements, arranged one by one in a single row. These elements display node captions and allow end-users to navigate back to these nodes on clicking. If a node has child nodes within, it displays a small arrow that invokes a drop-down menu on clicking. End-users can click this button to browse node children and navigate to them (see the following figure). If the drop-down list contains a currently selected node, its caption will be highlighted using a bold font style.

    Each node has its own path accessed via the BreadCrumbNode.Path property - this is the sequence of breadcrumb nodes you need to pass before you reach this current node.

  • Persistent nodes

    Persistent nodes are nodes, whose BreadCrumbNode.Persistent properties are set to true. These nodes serve as a prefix, standing above the primary node tree and expose the following unique features:

    • always visible wherever an end-user navigates;
    • excluded from the nodes hierarchy, which means values for these nodes are not included in path strings;
    • provide only one nesting level for child nodes (you can add other nodes to the BreadCrumbNode.ChildNodes collection of a persistent node, but these child nodes should not contain any children themselves);
    • when an end-user selects a child node from the persistent node's drop-down list, it does not navigate you to this child node (the RepositoryItemBreadCrumbEdit.PathChanged event is never raised);
    • node values for persistent nodes' children can store path strings. In this case clicking such a node will navigate you to the desired node without the nessecity to handle the RepositoryItemBreadCrumbEdit.NodeClick event and manually set the required path (see the example below).

    These specifics make persistent nodes more similar to regular drop-down buttons rather than breadcrumb nodes. Their main purpose is to store shortcuts to the most important and/or frequently used nodes or execute any custom actions. For instance, the animation below illustrates an example where a persistent node contains three child nodes, each perform navigation to a specific regular node.

    This example was built by setting the required paths to breadcrumb node's child node values.

  • Dynamically populated nodes

    These are the nodes that raise the RepositoryItemBreadCrumbEdit.QueryChildNodes event when the editor needs to navigate to this node for the first time. This event allows you to populate such nodes dynamically (see the example below). To do so, set the BreadCrumbNode.PopulateOnDemand property for required nodes to true.

  • Validation

    If a Breadcrumb Edit Control has to navigate to a node that does not yet exist (e.g., you have passed an unknown node values sequence to the editor's path), the path validation occurs. This mechanism gives you an opportunity to check this path and either cancel the navigation or create new nodes with the required values. To do so, handle the RepositoryItemBreadCrumbEdit.ValidatePath event and set its e.ValidationResult parameter to the required value. If you choose to create new nodes, they will raise the RepositoryItemBreadCrumbEdit.NewNodeAdding and RepositoryItemBreadCrumbEdit.QueryChildNodes events, which allows you to populate these new nodes dynamically (see the example below).

Expanded Breadcrumb Modes

The Breadcrumb Edit Control can operate in two modes - Select and Edit. See the Breadcrumb Modes document for more details.

Expanded History

Whenever an end-user succesfully navigates to a node in Edit mode, the path to this node is written to a breadcrumb history. At runtime users can click the editor's drop-down button to view these stored paths and select one to navigate to it. The following figure illustrates an example.

To access the breadcrumb history in code, use the RepositoryItemBreadCrumbEdit.History property. This property provides access to the BreadCrumbHistory collection, which stores the BreadCrumbHistoryItem class objects. Each history item has the BreadCrumbHistoryItem.Path property in which the item keeps the path to the related node. The Breadcrumb Edit Control provides multiple methods to navigate through history items.

End-users can navigate through nodes by means different from typing paths in Edit mode, for instance:

  • by using mouse in Select mode;
  • by modifying the editor's path from code;
  • by using shortcuts stored within a persistent node, etc.

Though the regular breadcrumb history, accessed through the RepositoryItemBreadCrumbEdit.History property, does not store any records of such navigation, you can get a complete history by calling the BreadCrumbEdit.GetNavigationHistory method. This method returns the separate BreadCrumbHistory collection that tracks every user's move within the editor.

Expanded Editor Buttons

By default, the Breadcrumb Edit Control has one button that invokes a drop-down menu with history records. You can remove this predefined button and/or add your own custom buttons. To do this at design-time, use the corresponding link on the editor's smart-tag. The button editor that will appear allow you to create, re-arrange, remove buttons and modify their properties using the built-in property grid.

To do this in code, modify the RepositoryItemButtonEdit.Buttons property, accessed through the editor's BreadCrumbEdit.Properties category. Buttons are represented by the EditorButton class objects. Follow the corresponding link in the 'Examples' section of this document to see an example.

Expanded Examples

This section contains links to task-based help regarding the Breadcrumb Edit Control.

Expanded See Also

Is this topic helpful?​​​​​​​