2.18.0 Change Notes

Scientific visualization

The AnalysisStyle APIs have been cleaned up and promoted to @public. An AnalysisStyle is used to animate a mesh that has been supplemented with PolyfaceAuxData, by recoloring and/or deforming its vertices over time. This enables visualization of the effects of computed, changing variables like stress and temperature.

Section-cut element graphics

TileAdmin.requestElementGraphics can now produce section-cut graphics if GraphicsRequestProps.sectionCut is supplied. The temporary element graphics produced during interactive editing will automatically include section-cut graphics based on the viewport's CutStyle.

Change summary API changes

ChangeSummaryManager.extractChangeSummaries has now been deprecated, and replaced with two methods - ChangeSummaryManager.createChangeSummaries and ChangeSummaryManager.createChangeSummary.

The deprecated method works by creating a range of Change Summaries by starting with the end version, reversing Changesets one by one until the specified start version. Since Changesets containing schema changes cannot be reversed, the method may fail to create some Change Summaries. The new replacement instead walks the versions in the forward direction.

• ChangeSummaryManager.createChangeSummaries creates Change Summaries for a range of Changesets by walking the versions in a forward direction starting with the specified first version.
• ChangeSummaryManager.createChangeSummary creates a single Change Summary for the current version of the iModel, i.e., the last applied Changeset.

ChangeSummaryManager.detachChangeCache can now be used to detach the cache after querying the change summary to continue change summary creation if necessary.

ChangeSummaryExtractOptions was also deprecated as a consequence of the above changes. CreateChangeSummaryArgs serves a similar purpose with the newer methods. ChangeSummaryExtractContext was unused and has been removed.

UI changes

@itwin/appui-abstract package

Added ability for UiItemsProvider to provide widgets to AbstractZoneLocation locations when running is AppUi version 1. Prior to this a widget could only be targeted to a StagePanelLocation location.

Example UiItemsProvider

The example below, shows how to add a widget to a StagePanelLocation if UiFramework.uiVersion === "2" and to the "BottomRight" AbstractZoneLocation if UiFramework.uiVersion === "1". See UiItemsProvider.provideWidgets for new zoneLocation argument.

export class ExtensionUiItemsProvider implements UiItemsProvider {
  public readonly id = "ExtensionUiItemsProvider";
  public static i18n: I18N;
  private _backstageItems?: BackstageItem[];

  public constructor(i18n: I18N) {
    ExtensionUiItemsProvider.i18n = i18n;
  }

  /** provideWidgets() is called for each registered UI provider to allow the provider to add widgets to a specific section of a stage panel.
   *  items to the StatusBar.
   */
  public provideWidgets(_stageId: string, stageUsage: string, location: StagePanelLocation, section: StagePanelSection | undefined, zoneLocation?: AbstractZoneLocation): ReadonlyArray<AbstractWidgetProps> {
    const widgets: AbstractWidgetProps[] = [];
    // section will be undefined if uiVersion === "1" and in that case we can add widgets to the specified zoneLocation
    if ((undefined === section && stageUsage === StageUsage.General && zoneLocation === AbstractZoneLocation.BottomRight) ||
      (stageUsage === StageUsage.General && location === StagePanelLocation.Right && section === StagePanelSection.End && "1" !== UiFramework.uiVersion)) {
      {
        widgets.push({
          id: PresentationPropertyGridWidgetControl.id,
          icon: PresentationPropertyGridWidgetControl.iconSpec,  // icon required if uiVersion === "1"
          label: PresentationPropertyGridWidgetControl.label,
          defaultState: WidgetState.Open,
          getWidgetContent: () => <PresentationPropertyGridWidget />, // eslint-disable-line react/display-name
          canPopout: true,  // canPopout ignore if uiVersion === "1"
        });
      }
    }
    return widgets;
  }
}

@itwin/appui-react package

• The need for an IModelApp to explicitly call ConfigurableUiManager.initialize has been removed. This call is now made when processing UiFramework.initialize. This will not break any existing applications as subsequent calls to ConfigurableUiManager.initialize() are ignored.

• If an application calls UiFramework.setIModelConnection it will no longer need to explicitly call SyncUiEventDispatcher.initializeConnectionEvents as UiFramework.setIModelConnection will call that method as it update the redux store.

• The version prop passed to FrameworkVersion component will update the [UiFramework.uiVersion] if necessary keeping the redux state matching the value defined by the prop.

• The ScheduleAnimationTimelineDataProvider is published for use by AppUi apps. Specifying this data provider to a TimelineComponent allows animation of the RenderSchedule.Script if one exists for the view. A component that automatically detects a schedule script and attaches the data provider to its TimelineComponent can be found in the DefaultViewOverlay.

• The AnalysisAnimationTimelineDataProvider is published for use by AppUi apps. Specifying this data provider to a TimelineComponent allows animation of the information in the AnalysisDisplayProperties if the view's DisplayStyleState contains one. A component that automatically detects analysis data and attaches the data provider to its TimelineComponent can be found in the DefaultViewOverlay.

@itwin/components-react package

• Added component QuantityNumberInput which accepts input for quantity values. The quantity value is shown as a single numeric value and the quantity "display" unit is shown next to the input control. The "display" unit is determined by the active unit system as defined by the QuantityFormatter. The control also provides buttons to increment and decrement the "displayed" value. The value reported by via the onChange function is in "persistence" units that can be stored in the iModel.

• Apps that use the TimelineComponent can now customize their own playback speeds by providing an array of TimelineMenuItemProps to the component. These can either be appended to or prefix the standard items, or they can replace them entirely. An option has also been added to the TimelineComponentProps to allow the app to turn on/off the Repeat menu item in the context menu.

Quantity package

The Format class now provides the method Format.clone to clone an existing Format. CloneOptions may be optionally passed into the clone method to adjust the format.

@itwin/ecschema-metadata changes

To reduce the size and limit the scope of the APIs available in the ecschema-metadata package, all APIs associated with EC Schema editing and validation have been moved to the @itwin/ecschema-editing package. This includes all source code under the Validation and Editing folders. All corresponding @beta types defined in the ecschema-metadata package have been deprecated. All @alpha types have been removed from the ecschema-metadata package. The source code move is the first step of a larger proposal for Schema editing and validation enhancements for connectors and editing applications. You may read and provide feedback on this initial proposal via this github discussion.

Deprecated @beta types (moved to ecschema-editing)

• IDiagnostic, BaseDiagnostic (including all sub-classes), DiagnosticType, DiagnosticCategory, DiagnosticCodes, Diagnostics
• IDiagnosticReporter, SuppressionDiagnosticReporter, FormatDiagnosticReporter, LoggingDiagnosticReporter
• IRuleSet, ECRuleSet
• ISuppressionRule, BaseSuppressionRule, IRuleSuppressionMap, BaseRuleSuppressionMap, IRuleSuppressionSet
• SchemaCompareCodes, SchemaCompareDiagnostics
• SchemaValidater, SchemaValidationVisitor

Removed @alpha types (moved to ecschema-editing)

• SchemaEditResults, SchemaItemEditResults, PropertyEditResults, SchemaContextEditor
• Editors namespace, which includes all editor classes (ie. ECClasses, Entities, Mixins, etc.)
• ISchemaChange, ISchemaChanges, ChangeType
• BaseSchemaChange, BaseSchemaChanges (including all sub-classes)
• ISchemaComparer, SchemaComparer, SchemaCompareDirection, ISchemaCompareReporter

Last Updated: 20 June, 2023