Navigation Aids

A Navigation Aid is a user interface control that moves the user's perspective around within a specific Content View. There are two navigation aids provided in the @itwin/appui-react package:

Active Navigation Aid

The active Navigation Aid is determined by the active Content View. The ContentControl class contains a navigationAidControl property that indicates the ID of the associated Navigation Aid. The default Navigation Aid is blank. When a Viewport is the active content, the ViewportContentControl class determines the associated Navigation Aid based on the viewport.view.classFullName property of the active Viewport. If you are developing your own Navigation Aid for a particular content type, you will also more than likely develop your own ContentControl subclass, and that custom ContentControl will indicate the associated Navigation Aid in the navigationAidControl property.

Developing a Navigation Aid

A Navigation Aid is comprised of two parts:

1. A NavigationAidControl subclass. This custom class is registered as a Navigation Aid using ConfigurableUiManager.registerControl.
2. A React component that the NavigationAidControl subclass references in its reactNode property. This component renders the Navigation Aid and responds to user interaction.

NavigationAidControl

The NavigationAidControl class is the base class for the first part of a Navigation Aid, the Navigation Aid control. The reactNode property returns the React component part of the Navigation Aid as a React.ReactNode. The getSize method optionally overrides the default size of "64px".

ConfigurableUiManager.registerControl

Each NavigationAidControl subclass should be registered by calling the ConfigurableUiManager.registerControl method.

    ConfigurableUiManager.registerControl(SampleNavigationAidControl.navigationAidId, SampleNavigationAidControl);

The ConfigurableUiManager.initialize function calls ConfigurableUiManager.registerControl for the two navigation aids provided in the @itwin/appui-react package:

    ConfigurableUiManager.registerControl(DrawingNavigationAidControl.navigationAidId, DrawingNavigationAidControl);
    ConfigurableUiManager.registerControl(CubeNavigationAidControl.navigationAidId, CubeNavigationAidControl);

Sample Navigation Aid

A sample Navigation Aid would be comprised of the two parts. The NavigationAidControl subclass for our sample Navigation Aid might look something like this:

// Simple Navigation Aid
export class SampleNavigationAidControl extends NavigationAidControl {
  public static navigationAidId = "SampleNavigationAid";

  constructor(info: ConfigurableCreateInfo, options: any) {
    super(info, options);
    this.reactNode = <SampleNavigationAid />;
  }
}

If the current iModelConnection or the active Viewport are supported by the Navigation Aid, it might look something like this:

// Navigation Aid supports iModelConnection and Viewport
export class SampleNavigationAidControl extends NavigationAidControl {
  public static navigationAidId = "SampleNavigationAid";

  constructor(info: ConfigurableCreateInfo, options: any) {
    super(info, options);

    // Provide iModelConnection and Viewport to Navigation Aid
    this.reactNode = <SampleNavigationAid iModelConnection={options.imodel} viewport={options.viewport} />;
  }

  // Override default size (64px)
  public override getSize(): string | undefined { return "96px"; }
}

The NavigationWidgetComposer and the NavigationAidHost pass the current iModelConnection and active Viewport to the NavigationAidControl subclass when it's created. Events such as ViewportComponentEvents.onViewRotationChangeEvent and ViewManager.onSelectedViewportChanged provide an updated Viewport.

The React component part of our Navigation Aid might look something like this:

export interface SampleNavigationAidProps extends CommonProps {
  iModelConnection: IModelConnection;
  viewport?: Viewport;
}

export function SampleNavigationAid(props: SampleNavigationAidProps) {
  const { className, style, ...rest } = props;

  return (
    <div className={className} style={style}>
      . . .
    </div>
  );
}

API Reference

• NavigationAids in appui-react
• NavigationAids in imodel-components-react

Last Updated: 30 November, 2023