Application Hierarchy and Module Navigation
- 4 minutes to read
To get started with WindowsUIView application hierarchy and navigation, invoke the View Designer and add multiple Documents. Handle the BaseView.QueryControl event to provide sample content for these Documents and run the application.
The start-up application page displays an automatically created Tile Containers with Tiles. Clicking a Tile shows the related Document. Invoke the designer again and switch to the “Navigation Tree” tab to see all these interconnected objects as a hierarchy.
This figure highlights two main properties required to build a WindowsUIView hierarchy and implement a simple navigation:
- Items - stores child items for this container. For example, the Tile Control’s TileContainer.Items collection stores all the Tiles this container owns. In the “Navigation Tree” Designer tab, you can drag-and-drop items in the “Items” collection to populate this container.
- ActivationTarget - points to an object that should be activated when a user clicks a specific Tile.
Simple Navigation: Activation Target
The ActivationTarget property is available for Tiles (Tile.ActivationTarget) and TileContainers (TileContainer.ActivationTarget). In the example above, no ActivationTarget is specified and the View follows an internal logic: when a user clicks a Tile, the View dynamically creates a Page container for the Document assigned to the clicked Tile’s Tile.Document property.
To see how the ActivationTarget works, go to the “Content Containers” Designer tab and create a PageGroup container. Drag-and-drop Documents in this container in the “Navigation Tree” tab, then drag the container itself to the TileContainer’s ActivationTarget line.
Test the application to see that clicking any tile now opens this Page Group. The Page Group also automatically selects the Document, whose related Tile has been clicked.
Individual Tiles’ ActivationTarget_s have priority over the TileContainer’s target. In the figure below, clicking Tiles #1 and #2 still brings a user to the PageGroup, but Tile #3 has a _ActivationTarget - a Page container that displays the Document3.
Important
Note that all containers you drag to an ActivationTarget property automatically receive a BaseContentContainer.Parent property value. If you build an application hierarchy manually in code, remember to specify this property as well. Otherwise, target containers do not display the “Back” header button and users are unable to return to parent containers.
Custom Navigation and Parameters
If you need to track end-user navigation and pass additional parameters, handle the WindowsUIView.NavigatedTo and WindowsUIView.NavigatedFrom events. These events receive the NavigationEventArgs type parameters that allow you to retrieve the following information:
- BaseNavigationEventArgs.Source - the current user location;
- NavigationEventArgs.Target - the content container to which a user navigates (when navigating within one container, for example, cycling through PageGroup tabs, the Target and Source parameters are equal);
- NavigationEventArgs.Document - the Document to which a user navigates;
NavigationEventArgs.NavigationMode - returns the ongoing navigation type:
- Forward - navigating to child containers;
- Back - navigating to parent container;
- Refresh - navigating to a different Document or screen within the same container;
- New - navigating to a newly created container;
- BaseNavigationEventArgs.SourceContextualZoomLevel, NavigationEventArgs.TargetContextualZoomLevel - the WindowsUIView.ZoomLevel for the target and source containers;
- NavigationEventArgs.Tag - the clicked Tile’s tag (the TileItem.Tag property);
- NavigationEventArgs.Parameter - the object passed from a target to a source.
In the example below, a start-up TileContainer holds three Tiles. The container’s ActivationTarget is a Page with one Document that displays the Data Grid with vehicle records.
Tagging Tiles with vehicle category names allows you to pre-filter Data Grid records.
document1Tile.Tag = "Truck";
document2Tile.Tag = "Car";
document3Tile.Tag = "Crossover & SUV";
windowsUIView1.NavigatedTo += WindowsUIView1_NavigatedTo;
private void WindowsUIView1_NavigatedTo(object sender, DevExpress.XtraBars.Docking2010.Views.WindowsUI.NavigationEventArgs e) {
WindowsUIView view = sender as WindowsUIView;
string filterString;
if (view.ActiveDocument != null && view.ActiveDocument.Control != null && e.Tag != null) {
filterString = "[Category_Name] = '" + e.Tag.ToString() + "'";
GridControl grid = view.ActiveDocument.Control.Controls.OfType<GridControl>().First();
(grid.MainView as WinExplorerView).ActiveFilterString = filterString;
page1.Caption = "Category: " + e.Tag.ToString();
}
}
The How To: Pass Specific Data when Navigating Through Containers example illustrates how to pass parameters when navigating from\to containers other than the TileContainer. In this case, you need to implement the ISupportNavigation interface for your Document UserControls to ISupportNavigation.OnNavigatedTo and ISupportNavigation.OnNavigatedFrom methods, which serve the same purpose as the aforementioned NavigatedTo and NavigatedFrom events.