Provide default tool assistance for face/edge/vertex selection phase.

common/api/editor-frontend.api.md

@@ -1135,6 +1135,8 @@ export abstract class LocateSubEntityTool extends ElementGeometryCacheTool {
     protected pickSubEntities(id: Id64String, boresite: Ray3d, maxFace: number, maxEdge: number, maxVertex: number, maxDistance: number, hiddenEdgesVisible: boolean, filter?: SubEntityFilter): Promise<SubEntityLocationProps[] | undefined>;
     // (undocumented)
     processAgenda(ev: BeButtonEvent): Promise<void>;
+    // (undocumented)
+    protected provideToolAssistance(mainInstrText?: string, additionalInstr?: ToolAssistanceInstruction[]): void;
     protected removeSubEntity(_id: Id64String, props?: SubEntityLocationProps): Promise<void>;
     // (undocumented)
     protected get requiredSubEntityCount(): number;

common/changes/@itwin/editor-frontend/locate-subentity-tool-assistance_2022-01-13-13-00.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/editor-frontend",
+      "comment": "Provide default tool assistance for face/edge/vertex selection phase.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/editor-frontend"
+}

editor/frontend/src/ElementGeometryTool.ts

@@ -10,7 +10,7 @@ import { Id64, Id64Arg, Id64Array, Id64String } from "@itwin/core-bentley";
 import { BRepEntityType, editorBuiltInCmdIds, ElementGeometryCacheFilter, ElementGeometryResultOptions, ElementGeometryResultProps, LocateSubEntityProps, SolidModelingCommandIpc, SubEntityFilter, SubEntityGeometryProps, SubEntityLocationProps, SubEntityProps, SubEntityType } from "@itwin/editor-common";
 import { FeatureAppearance, FeatureAppearanceProvider, RgbColor } from "@itwin/core-common";
 import { Point3d, Range3d, Ray3d, Transform } from "@itwin/core-geometry";
-import { AccuDrawHintBuilder, BeButtonEvent, BeModifierKeys, CoordinateLockOverrides, CoordSource, DecorateContext, DynamicsContext, ElementSetTool, EventHandled, FeatureOverrideProvider, FeatureSymbology, GraphicBranch, GraphicBranchOptions, GraphicType, HitDetail, IModelApp, IModelConnection, InputSource, LocateResponse, readElementGraphics, RenderGraphicOwner, SelectionMethod, SelectionSet, Viewport } from "@itwin/core-frontend";
+import { AccuDrawHintBuilder, BeButtonEvent, BeModifierKeys, CoordinateLockOverrides, CoordSource, CoreTools, DecorateContext, DynamicsContext, ElementSetTool, EventHandled, FeatureOverrideProvider, FeatureSymbology, GraphicBranch, GraphicBranchOptions, GraphicType, HitDetail, IModelApp, IModelConnection, InputSource, LocateResponse, readElementGraphics, RenderGraphicOwner, SelectionMethod, SelectionSet, ToolAssistance, ToolAssistanceImage, ToolAssistanceInputMethod, ToolAssistanceInstruction, ToolAssistanceSection, Viewport } from "@itwin/core-frontend";
 import { computeChordToleranceFromPoint } from "./CreateElementTool";
 import { EditTools } from "./EditTool";
 
@@ -384,6 +384,59 @@ export abstract class LocateSubEntityTool extends ElementGeometryCacheTool {
   protected _subEntityGraphicPending?: true;
   protected readonly _summaryIds = new Map<Id64String, BRepEntityType[]>();
 
+  protected override provideToolAssistance(mainInstrText?: string, additionalInstr?: ToolAssistanceInstruction[]): void {
+    if (this.wantAdditionalSubEntities) {
+      const faceKey = this.wantSubEntityType(SubEntityType.Face) ? "Face" : "";
+      const edgeKey = this.wantSubEntityType(SubEntityType.Edge) ? "Edge" : "";
+      const vertexKey = this.wantSubEntityType(SubEntityType.Vertex) ? "Vertex" : "";
+      const subEntityKey: string = `${faceKey}${edgeKey}${vertexKey}`;
+
+      if(0 === subEntityKey.length) {
+        super.provideToolAssistance(mainInstrText, additionalInstr);
+        return;
+      }
+
+      if (undefined === mainInstrText)
+        mainInstrText = EditTools.translate(`LocateSubEntities.Identify.${subEntityKey}`);
+
+      const leftMsg = EditTools.translate(`LocateSubEntities.Accept.${subEntityKey}`);
+      const rightMsg = this.haveAcceptedSubEntities && this.allowSubEntitySelectNext ? EditTools.translate(`LocateSubEntities.AcceptNext.${subEntityKey}`) : CoreTools.translate("ElementSet.Inputs.Cancel");
+
+      const mouseInstructions: ToolAssistanceInstruction[] = [];
+      const touchInstructions: ToolAssistanceInstruction[] = [];
+
+      if (!ToolAssistance.createTouchCursorInstructions(touchInstructions))
+        touchInstructions.push(ToolAssistance.createInstruction(ToolAssistanceImage.OneTouchTap, leftMsg, false, ToolAssistanceInputMethod.Touch));
+      mouseInstructions.push(ToolAssistance.createInstruction(ToolAssistanceImage.LeftClick, leftMsg, false, ToolAssistanceInputMethod.Mouse));
+
+      touchInstructions.push(ToolAssistance.createInstruction(ToolAssistanceImage.TwoTouchTap, rightMsg, false, ToolAssistanceInputMethod.Touch));
+      mouseInstructions.push(ToolAssistance.createInstruction(ToolAssistanceImage.RightClick, rightMsg, false, ToolAssistanceInputMethod.Mouse));
+
+      if (this.allowSubEntityControlSelect)
+        mouseInstructions.push(ToolAssistance.createModifierKeyInstruction(ToolAssistance.ctrlKey, ToolAssistanceImage.LeftClickDrag, EditTools.translate(`LocateSubEntities.IdentifyAdditional.${subEntityKey}`), false, ToolAssistanceInputMethod.Mouse));
+
+      if (undefined !== additionalInstr) {
+        for (const instr of additionalInstr) {
+          if (ToolAssistanceInputMethod.Touch === instr.inputMethod)
+            touchInstructions.push(instr);
+          else
+            mouseInstructions.push(instr);
+        }
+      }
+
+      const sections: ToolAssistanceSection[] = [];
+      sections.push(ToolAssistance.createSection(mouseInstructions, ToolAssistance.inputsLabel));
+      sections.push(ToolAssistance.createSection(touchInstructions, ToolAssistance.inputsLabel));
+
+      const mainInstruction = ToolAssistance.createInstruction(this.iconSpec, mainInstrText);
+      const instructions = ToolAssistance.createInstructions(mainInstruction, sections);
+      IModelApp.notifications.setToolAssistance(instructions);
+      return;
+    }
+
+    super.provideToolAssistance(mainInstrText, additionalInstr);
+  }
+
   protected override get wantAgendaAppearanceOverride(): boolean { return true; }
   protected get wantGeometrySummary(): boolean { return false; }
   protected get wantSubEntitySnap(): boolean { return false; }

editor/frontend/src/SolidModelingTools.ts

@@ -610,6 +610,13 @@ export class OffsetFacesTool extends LocateSubEntityTool {
     if (offsetDir.dotProduct(faceData.normal) < 0.0)
       offset = -offset;
 
+    if (!this.useDistance) {
+      this.distance = offset;
+      this.syncToolSettingPropertyValue(this.distanceProperty);
+      if (isAccept)
+        this.saveToolSettingPropertyValue(this.distanceProperty, this.distanceProperty.dialogItemValue);
+    }
+
     try {
       this._startedCmd = await this.startCommand();
       const id = this.agenda.elements[0];
@@ -1562,6 +1569,13 @@ export class SweepFacesTool extends LocateFaceOrProfileTool {
     if (path.magnitude() < Geometry.smallMetricDistance)
       return undefined;
 
+    if (!this.useDistance) {
+      this.distance = path.magnitude();
+      this.syncToolSettingPropertyValue(this.distanceProperty);
+      if (isAccept)
+        this.saveToolSettingPropertyValue(this.distanceProperty, this.distanceProperty.dialogItemValue);
+    }
+
     try {
       this._startedCmd = await this.startCommand();
       const id = this.agenda.elements[0];

editor/frontend/src/public/locales/en/Editor.json

@@ -222,6 +222,44 @@
       "keyin": "editor delete subentities",
       "flyover": "Delete faces and edges of solids and surfaces"
     },
+    "LocateSubEntities": {
+      "Identify": {
+        "Face": "Identify face",
+        "Edge": "Identify edge",
+        "Vertex": "Identity vertex",
+        "FaceEdge": "Identify face or edge",
+        "FaceVertex": "Identify face or vertex",
+        "EdgeVertex": "Identify edge or vertex",
+        "FaceEdgeVertex": "Identity face, edge, or vertex"
+      },
+      "IdentifyAdditional": {
+        "Face": "Identify additional faces",
+        "Edge": "Identify additional edges",
+        "Vertex": "Identity additional vertices",
+        "FaceEdge": "Identify additional faces or edges",
+        "FaceVertex": "Identify additional faces or vertices",
+        "EdgeVertex": "Identify additional edges or vertices",
+        "FaceEdgeVertex": "Identity additional faces, edges, or vertices"
+      },
+      "Accept": {
+        "Face": "Accept face",
+        "Edge": "Accept edge",
+        "Vertex": "Accept vertex",
+        "FaceEdge": "Accept face or edge",
+        "FaceVertex": "Accept face or vertex",
+        "EdgeVertex": "Accept edge or vertex",
+        "FaceEdgeVertex": "Accept face, edge, or vertex"
+      },
+      "AcceptNext": {
+        "Face": "Accept next face",
+        "Edge": "Accept next edge",
+        "Vertex": "Accept next vertex",
+        "FaceEdge": "Accept next face or edge",
+        "FaceVertex": "Accept next face or vertex",
+        "EdgeVertex": "Accept next edge or vertex",
+        "FaceEdgeVertex": "Accept next face, edge, or vertex"
+      }
+    },
     "UndoAll": {
       "keyin": "editor undo all",
       "flyover": "Undo All"