Navigator Class

General-purpose navigation container with on-demand instantiation and recycling of pages.

Note: It is recommended that you first read the Navigation guide for a full overview of Fuse's navigation system.

Pages

Navigator takes a collection of templates as its children. This allows it to instantiate and recycle pages as it needs.

You can declare a node as a template by specifying the ux:Template attribute. The path of the route is matched to the ux:Template value to select a template.

<Page ux:Template="matchPath">

You can read more about templates here.

Non-template pages can also be used. The Name of the page will be used to match the path:

<Page Name="matchPath">

These pages always just have the one instance, will always be reused, and will never be removed. Otherwise they function the same as the template pages.

Here are some general rules that will you help decide whether you want to use a template or non-template page:

  • If you need transitions between pages with the same path, but different parameter, then use a template.
  • If you have pages that impact performance even when inactive, or for other reasons should be removed when unused, then use a template.
  • If you have a page that should always exist to preserve state, or is very frequently navigated to, use a non-template.

Note that templates and non-templates can be mixed within one Navigator.

Transitions

Navigator comes with a set of default transitions that match the behavior of push(), goBack() and goto().

To have complete control over page transitions use the PageView class. It works just like a Navigator but has no standard transitions or state changes.

When using custom transitions be sure to add a ReleasePage action. This instructs the Navigator and PageView on when it can reuse, discard, or add the page to its cache.

Example

The following example illustrates a basic navigation setup using a Router and Navigator. For a complete introduction and proper examples of Fuse's navigation system, see the Navigation guide.

<JavaScript>
    module.exports = {
        gotoFirst: function() { router.goto("firstPage"); },
        gotoSecond: function() { router.goto("secondPage"); }
    };
</JavaScript>

<Router ux:Name="router" />

<DockPanel>
    <Navigator DefaultPath="firstPage">
        <Page ux:Template="firstPage">
            <Text Alignment="Center">This is the first page.</Text>
        </Page>
        <Page ux:Template="secondPage">
            <Text Alignment="Center">This is the second page.</Text>
        </Page>
    </Navigator>

    <Grid Dock="Bottom" Columns="1*,1*">
        <Button Text="First page" Padding="20" Clicked="{gotoFirst}" />
        <Button Text="Second page" Padding="20" Clicked="{gotoSecond}" />
    </Grid>
</DockPanel>

The Navigator uses discrete page progress changes while navigating. The active page will have progress 0. If a page is pushed it will start at 1 and be switched immediately to 0. The previously active page will become -1. A "back" operation will reverse the transition.

Only progresses -1, 0, and 1 are used. Further distance is not calculated, nor are partial values possible.

See Navigation Order

Location

Namespace
Fuse.Controls
Package
Fuse.Controls.Navigation 2.9.1
Show Uno properties and methods

Interface of Navigator

DefaultPath : string ux

Whenever a null or empty path is specified, use this path instead. This can select either a template or non-template.

Pages : IArray ux

The stack of pages that is the history of this navigator. Only the top-most page will be active. Changes in the list will activate/deactive pages.

Remove : RemoveType ux

Specifies when pages are removed from the Navigator. Removed pages are no longer part of the UI tree and can thus release their resources. A removed page may still be reused, refer to Reuse.

Reuse : ReuseType ux

Specifies when a page can be reused in navigation, either with the same, or a different parameter. Only pages of the same type are ever reused. Reusing pages avoids the overhead of instantiating new objects and/or adding new items to the UI tree.

Inherited from NavigationControl

PageHistory : IArray ux

Pages is a stack of pages that controls the local history for a NavigationControl.

Inherited from Panel

Color : float4 ux

The background color of the panel. This property is a shortcut for setting the Background property to a SolidColor brush. Supports being set using a float4 notation, or hexadecimal values(f.ex #FF00AA)

IsFrozen : bool ux

When true the panel is in a frozen state. This means: - layout of the children is blocked - child invalidation does not invalidate this panel - the visual drawing is captured once and used for all future drawing

Inherited from LayoutControl

Inherited from Control

Inherited from Element

ActualPosition : float2 uno

The position of the element, the position of its top-left corner to the top-left corner in the parent.

Anchor : Size2 ux

A point within the element to treat as its "epicenter".

Aspect : float ux

The aspect ratio that an element must fulfill in layout.

Offset : Size2 ux

Offets the position of the element after all other layout has been applied.

Inherited from Visual

bringIntoView() js

Requests that this visual be brought into the visible are of the screen. Typically a containing ScrollView will scroll to ensure it is visible.

Children : IList of Node ux

The children of the visual. All nodes placed inside the visual in UX markup are assigned to this list. The order of Visuals this list determines the order of layout. The Z-order of the children is by default equal to this order, but can be manipulated separately using methods like BringToFront and SendToBack.

InvalidateVisual uno

Indicates the visual for this node has changed. This allows the root-level node to know that it must draw, and any caching that it must invalidate the cache for this node.

InvalidateVisualComposition uno

Indicates the composition of the visual has changed, but that the visual drawing itself is still valid (for example a position change).

IsEnabled : bool ux

Whether this node is currently interactable. Disabled visuals do not receive input focus. However, they can still be visible and block hit test for underlaying objects.

IsLocalVisible : bool uno

Returns whether this visual is visible without concern for whether an ancestor visual is hidden or collapsed.

IsVisible : bool uno

Returns whether this visual is currently visible. Will return false if any of the ancestor visuals are hidden or collapsed. This property can not be used to check whether a visual is hidden because it is occluded by another visual, or is outside the view but otherwise visible.

Parameter : string ux

The parameter data for this visual, encoded as JSON, provided by a router if this visual represents a navigation page.

SnapToPixels : bool ux

Whether to snap the result of layout of this visual to physical device pixels.

ZOffset : float ux

Specifies a Z-Offset, visuals with higher values are in front of other visuals.

Inherited from Node

ContextParent : Node uno

The context parent is the semantic parent of this node. It is where non-UI structure should be resolved, like looking for the DataContext, a Navigation, or other semantic item.

FindNodeByName(Selector, Predicate<Node> (Node)) : Node uno

Finds the first node with a given name that satisfies the given acceptor. The serach algorithm works as follows: Nodes in the subtree are matched first, then it matches the nodes in the subtrees ofthe ancestor nodes by turn all the way to the root. If no matching node is found, the function returns null.

IsRootingStarted : bool uno

Whether rooting of this node has started. Note that even if this property returns true, rooting may not yet be completed for the node. See also IsRootingCompleted.

Name : Selector ux

Run-time name of the node. This property is automatically set using the ux:Name attribute.

OnRooted uno

If you override OnRooted you must call base.OnRooted() first in your derived class. No other processing should happen first, otherwise you might end up in an undefined state.

Inherited from PropertyObject

Inherited from object

Attached UX Attributes

Items (attached by Each) : object ux

The item collection that will be used to populate this visual.

MatchKey (attached by Each) : string ux

Shorthand for setting the MatchKey property on the implicit Each created when using the Items attached property.

Column (attached by Grid) : int ux

The index of the column the element occupies while in a Grid. If not set, the grid will place the element in a cell according to its position in the child list.

Row (attached by Grid) : int ux

The index of the row the element occupies while in a Grid. If not set, the grid will place the element in a cell according to its position in the child list.

GlobalKey (attached by Resource) : string ux

The ux:Global attribute creates a global resource that is accessible everywhere in UX markup.

Implemented Interfaces

INavigation uno

An extended navigation interface implemented by full navigation behaviors.

ISubtreeDataProvider uno

When implemented by a Node, it indicates that the node provides data for its children. hide

IBaseNavigation uno

A minimal interface implemented by simple navigation behaviors and controls.

IScriptObject uno

Interface for objects that can have a script engine representation