@itwin/core-frontend

/** @packageDocumentation * @module Tools */ import { DialogItem, DialogItemValue, DialogProperty, DialogPropertySyncItem } from "@itwin/appui-abstract"; import { GeometryStreamProps } from "@itwin/core-common"; import { Point2d, Point3d, XAndY } from "@itwin/core-geometry"; import { LocateFilterStatus, LocateResponse } from "../ElementLocateManager"; import { FuzzySearchResults } from "../FuzzySearch"; import { HitDetail } from "../HitDetail"; import { DecorateContext, DynamicsContext } from "../ViewContext"; import { ScreenViewport } from "../Viewport"; /** * @public * @extensions */ export type ToolType = typeof Tool; /** * @public * @extensions */ export type ToolList = ToolType[]; /** * @public * @extensions */ export declare enum BeButton { Data = 0, Reset = 1, Middle = 2 } /** * @public * @extensions */ export declare enum CoordinateLockOverrides { None = 0, ACS = 2, Grid = 4,// also overrides unit lock All = 65535 } /** The *source* that generated an event. * @public * @extensions */ export declare enum InputSource { /** Source not defined */ Unknown = 0, /** From a mouse or other pointing device */ Mouse = 1, /** From a touch screen */ Touch = 2 } /** The *source* that generated a coordinate. * @public * @extensions */ export declare enum CoordSource { /** Event was created by an action from the user */ User = 0, /** Event was created by a program or by a precision keyin */ Precision = 1, /** Event was created by a tentative point */ TentativePoint = 2, /** Event was created by snapping to an element */ ElemSnap = 3 } /** Numeric mask for a set of modifier keys (control, shift, and alt). * @public * @extensions */ export declare enum BeModifierKeys { None = 0, Control = 1, Shift = 2, Alt = 4 } /** * @public * @extensions */ export declare class BeButtonState { private readonly _downUorPt; private readonly _downRawPt; downTime: number; isDown: boolean; isDoubleClick: boolean; isDragging: boolean; inputSource: InputSource; get downRawPt(): Point3d; set downRawPt(pt: Point3d); get downUorPt(): Point3d; set downUorPt(pt: Point3d); init(downUorPt: Point3d, downRawPt: Point3d, downTime: number, isDown: boolean, isDoubleClick: boolean, isDragging: boolean, source: InputSource): void; } /** Properties for constructing a BeButtonEvent * @public * @extensions */ export interface BeButtonEventProps { /** The point for this event, in world coordinates. * @note these coordinates may have been *adjusted* for some reason (e.g. snapping, locks, etc.) from the [[rawPoint]]. */ point?: Point3d; /** The *raw* (unadjusted) point for this event, in world coordinates. */ rawPoint?: Point3d; /** The point, in screen coordinates for this event. * @note generally the z value is not useful, but some 3d pointing devices do supply it. */ viewPoint?: Point3d; /** The [[ScreenViewport]] for the BeButtonEvent. If undefined, this event is invalid. */ viewport?: ScreenViewport; /** How the coordinate values were generated (either from an action by the user or from a program.) */ coordsFrom?: CoordSource; keyModifiers?: BeModifierKeys; /** The mouse button for this event. */ button?: BeButton; /** If true, this event was generated from a mouse-down transition, false from a button-up transition. */ isDown?: boolean; /** If true, this is the second down in a rapid double-click of the same button. */ isDoubleClick?: boolean; /** If true, this event was created by pressing, holding, and then moving a mouse button. */ isDragging?: boolean; /** Whether this event came from a pointing device (e.g. mouse) or a touch device. */ inputSource?: InputSource; } /** Object sent to Tools that holds information about button/touch/wheel events. * @public * @extensions */ export declare class BeButtonEvent implements BeButtonEventProps { private readonly _point; private readonly _rawPoint; private readonly _viewPoint; private _movement?; /** The [[ScreenViewport]] from which this BeButtonEvent was generated. If undefined, this event is invalid. */ viewport?: ScreenViewport; /** How the coordinate values were generated (either from an action by the user or from a program.) */ coordsFrom: CoordSource; /** The keyboard modifiers that were pressed when the event was generated. */ keyModifiers: BeModifierKeys; /** If true, this event was generated from a mouse-down transition, false from a button-up transition. */ isDown: boolean; /** If true, this is the second down in a rapid double-click of the same button. */ isDoubleClick: boolean; /** If true, this event was created by pressing, holding, and then moving a mouse button. */ isDragging: boolean; /** The mouse button that created this event. */ button: BeButton; /** Whether this event came from a pointing device (e.g. mouse) or a touch device. */ inputSource: InputSource; constructor(props?: BeButtonEventProps); /** Determine whether this BeButtonEvent has valid data. * @note BeButtonEvents may be constructed as "blank", and are not considered to hold valid data unless the [[viewport]] member is defined. */ get isValid(): boolean; /** The point for this event, in world coordinates. * @note these coordinates may have been *adjusted* for some reason (e.g. snapping, locks, etc.) from the [[rawPoint]]. */ get point(): Point3d; set point(pt: Point3d); /** The *raw* (unadjusted) point for this event, in world coordinates. */ get rawPoint(): Point3d; set rawPoint(pt: Point3d); /** The point, in screen coordinates for this event. * @note generally the z value is not useful, but some 3d pointing devices do supply it. */ get viewPoint(): Point3d; set viewPoint(pt: Point3d); /** The difference in screen coordinates from previous motion event * @internal */ get movement(): XAndY | undefined; set movement(mov: XAndY | undefined); /** Mark this BeButtonEvent as invalid. Can only become valid again by calling [[init]] */ invalidate(): void; /** Initialize the values of this BeButtonEvent. */ init(props: BeButtonEventProps): void; /** Determine whether the control key was pressed */ get isControlKey(): boolean; /** Determine whether the shift key was pressed */ get isShiftKey(): boolean; /** Determine whether the alt key was pressed */ get isAltKey(): boolean; /** Copy the values from another BeButtonEvent into this BeButtonEvent */ setFrom(src: BeButtonEvent): this; /** Make a copy of this BeButtonEvent. */ clone(): this; } /** Properties for initializing a BeTouchEvent * @public * @extensions */ export interface BeTouchEventProps extends BeButtonEventProps { touchEvent: TouchEvent; } /** A ButtonEvent generated by touch input. * @public * @extensions */ export declare class BeTouchEvent extends BeButtonEvent implements BeTouchEventProps { tapCount: number; touchEvent: TouchEvent; get touchCount(): number; get isSingleTouch(): boolean; get isTwoFingerTouch(): boolean; get isSingleTap(): boolean; get isDoubleTap(): boolean; get isTwoFingerTap(): boolean; constructor(props: BeTouchEventProps); setFrom(src: BeTouchEvent): this; static getTouchPosition(touch: Touch, vp: ScreenViewport): Point2d; static getTouchListCentroid(list: TouchList, vp: ScreenViewport): Point2d | undefined; static findTouchById(list: TouchList, id: number): Touch | undefined; } /** Properties for constructing a BeWheelEvent * @public * @extensions */ export interface BeWheelEventProps extends BeButtonEventProps { wheelDelta?: number; time?: number; } /** A BeButtonEvent generated by movement of a mouse wheel. * @note wheel events include mouse location. * @public * @extensions */ export declare class BeWheelEvent extends BeButtonEvent implements BeWheelEventProps { wheelDelta: number; time: number; constructor(props?: BeWheelEventProps); setFrom(src: BeWheelEvent): this; } /** A Tool that performs an action. It has a *toolId* that uniquely identifies it, so it can be found via a lookup in the [[ToolRegistry]]. * Every time a tools run, a new instance of (a subclass of) this class is created and its [[run]] method is invoked. * @see [[InteractiveTool]] for a base Tool class to handle user input events from a Viewport. * @see [Tools]($docs/learning/frontend/tools.md) * @public * @extensions */ export declare class Tool { /** If true, this Tool will not appear in the list from [[ToolRegistry.getToolList]]. This should be overridden in subclasses to hide them. */ static hidden: boolean; /** The unique string that identifies this tool. This must be overridden in every subclass. */ static toolId: string; /** The icon for this Tool. This may be overridden in subclasses to provide a tool icon. * The value is the name of an icon WebFont entry, or if specifying an SVG symbol, use `svg:` prefix. */ static iconSpec: string; /** The namespace that provides localized strings for this Tool. Subclasses should override this. */ static namespace: string; /** @internal */ get ctor(): ToolType; constructor(..._args: any[]); /** The minimum number of arguments allowed by [[parseAndRun]]. If subclasses override [[parseAndRun]], they should also * override this method to indicate the minimum number of arguments their implementation expects. UI controls can use * this information to ensure the tool has enough information to execute. */ static get minArgs(): number; /** The maximum number of arguments allowed by [[parseAndRun]], or undefined if there is no maximum. * If subclasses override [[parseAndRun]], they should also override this method to indicate the maximum * number of arguments their implementation expects. */ static get maxArgs(): number | undefined; /** * Register this Tool class with the [[ToolRegistry]]. * @param namespace optional namespace to supply to [[ToolRegistry.register]]. If undefined, use namespace from superclass. */ static register(namespace?: string): void; private static getLocalizedKey; /** * Get the localized keyin string for this Tool class. This returns the value of "tools." + this.toolId + ".keyin" from * its registered Namespace (e.g. "en/MyApp.json"). */ static get keyin(): string; /** * Get the English keyin string for this Tool class. This returns the value of "tools." + this.toolId + ".keyin" from * its registered Namespace (e.g. "en/MyApp.json"). */ static get englishKeyin(): string; /** * Get the localized flyover for this Tool class. This returns the value of "tools." + this.toolId + ".flyover" from * its registered Namespace (e.g. "en/MyApp.json"). If that key is not in the localization namespace, * [[keyin]] is returned. */ static get flyover(): string; /** * Get the localized description for this Tool class. This returns the value of "tools." + this.toolId + ".description" from * its registered Namespace (e.g. "en/MyApp.json"). If that key is not in the localization namespace, * [[flyover]] is returned. */ static get description(): string; /** * Get the toolId string for this Tool class. This string is used to identify the Tool in the ToolRegistry and is used to localize * the keyin, description, etc. from the current locale. */ get toolId(): string; /** Get the localized keyin string from this Tool's class * @see `static get keyin()` */ get keyin(): string; /** Get the localized flyover string from this Tool's class * @see `static get flyover()` */ get flyover(): string; /** Get the localized description string from this Tool's class * @see `static get description()` */ get description(): string; /** Get the iconSpec from this Tool's class. * @see `static iconSpec` */ get iconSpec(): string; /** * Run this instance of a Tool. Subclasses should override to perform some action. * @returns `true` if the tool executed successfully. */ run(..._args: any[]): Promise<boolean>; /** Run this instance of a tool using a series of string arguments. Override this method to parse the arguments, and if they're * acceptable, execute your [[run]] method. If the arguments aren't valid, return `false`. * @note if you override this method, you must also override the static [[minArgs]] and [[maxArgs]] getters. * @note Generally, implementers of this method are **not** expected to call `super.parseAndRun(...)`. Instead, call your * [[run]] method with the appropriate (parsed) arguments directly. */ parseAndRun(..._args: string[]): Promise<boolean>; } /** * @public * @extensions */ export declare enum EventHandled { No = 0, Yes = 1 } /** A Tool that may be installed, via [[ToolAdmin]], to handle user input. The ToolAdmin manages the currently installed ViewingTool, PrimitiveTool, * InputCollector, and IdleTool. Each must derive from this class and there may only be one of each type installed at a time. * @public * @extensions */ export declare abstract class InteractiveTool extends Tool { /** Used to avoid sending tools up events for which they did not receive the down event. */ receivedDownEvent: boolean; /** Override to execute additional logic when tool is installed. Return false to prevent this tool from becoming active */ onInstall(): Promise<boolean>; /** Override to execute additional logic after tool becomes active */ onPostInstall(): Promise<void>; abstract exitTool(): Promise<void>; /** Override Call to reset tool to initial state */ onReinitialize(): Promise<void>; /** Invoked when the tool becomes no longer active, to perform additional cleanup logic */ onCleanup(): Promise<void>; /** Notification of a ViewTool or InputCollector starting and this tool is being suspended. * @note Applies only to PrimitiveTool and InputCollector, a ViewTool can't be suspended. */ onSuspend(): Promise<void>; /** Notification of a ViewTool or InputCollector exiting and this tool is being unsuspended. * @note Applies only to PrimitiveTool and InputCollector, a ViewTool can't be suspended. */ onUnsuspend(): Promise<void>; /** Called to support operations on pickable decorations, like snapping. */ testDecorationHit(_id: string): boolean; /** Called to allow snapping to pickable decoration geometry. * @note Snap geometry can be different from decoration geometry (ex. center point of a + symbol). Valid decoration geometry for snapping should be "stable" and not change based on the current cursor location. */ getDecorationGeometry(_hit: HitDetail): GeometryStreamProps | undefined; /** * Called to allow an active tool to display non-element decorations in overlay mode. * This method is NOT called while the tool is suspended by a viewing tool or input collector. */ decorate(_context: DecorateContext): void; /** * Called to allow a suspended tool to display non-element decorations in overlay mode. * This method is ONLY called when the tool is suspended by a viewing tool or input collector. * @note Applies only to PrimitiveTool and InputCollector, a ViewTool can't be suspended. */ decorateSuspended(_context: DecorateContext): void; /** Invoked when the reset button is pressed. * @return No by default. Sub-classes may ascribe special meaning to this status. * @note To support right-press menus, a tool should put its reset event processing in onResetButtonUp instead of onResetButtonDown. */ onResetButtonDown(_ev: BeButtonEvent): Promise<EventHandled>; /** Invoked when the reset button is released. * @return No by default. Sub-classes may ascribe special meaning to this status. */ onResetButtonUp(_ev: BeButtonEvent): Promise<EventHandled>; /** Invoked when the data button is pressed. * @return No by default. Sub-classes may ascribe special meaning to this status. */ onDataButtonDown(_ev: BeButtonEvent): Promise<EventHandled>; /** Invoked when the data button is released. * @return No by default. Sub-classes may ascribe special meaning to this status. */ onDataButtonUp(_ev: BeButtonEvent): Promise<EventHandled>; /** Invoked when the middle mouse button is pressed. * @return Yes if event completely handled by tool and event should not be passed on to the IdleTool. */ onMiddleButtonDown(_ev: BeButtonEvent): Promise<EventHandled>; /** Invoked when the middle mouse button is released. * @return Yes if event completely handled by tool and event should not be passed on to the IdleTool. */ onMiddleButtonUp(_ev: BeButtonEvent): Promise<EventHandled>; /** Invoked when the cursor is moving */ onMouseMotion(_ev: BeButtonEvent): Promise<void>; /** Invoked when the cursor begins moving while a button is depressed. * @return Yes if event completely handled by tool and event should not be passed on to the IdleTool. */ onMouseStartDrag(_ev: BeButtonEvent): Promise<EventHandled>; /** Invoked when the button is released after onMouseStartDrag. * @note default placement tool behavior is to treat press, drag, and release of data button the same as click, click by calling onDataButtonDown. * @return Yes if event completely handled by tool and event should not be passed on to the IdleTool. */ onMouseEndDrag(ev: BeButtonEvent): Promise<EventHandled>; /** Invoked when the mouse wheel moves. * @return Yes if event completely handled by tool and event should not be passed on to the IdleTool. */ onMouseWheel(_ev: BeWheelEvent): Promise<EventHandled>; /** Called when Control, Shift, or Alt modifier keys are pressed or released. * @param _wentDown up or down key event * @param _modifier The modifier key mask * @param _event The event that caused this call * @return Yes to refresh view decorations or update dynamics. */ onModifierKeyTransition(_wentDown: boolean, _modifier: BeModifierKeys, _event: KeyboardEvent): Promise<EventHandled>; /** Called when any key is pressed or released. * @param _wentDown up or down key event * @param _keyEvent The KeyboardEvent * @return Yes to prevent further processing of this event * @see [[onModifierKeyTransition]] */ onKeyTransition(_wentDown: boolean, _keyEvent: KeyboardEvent): Promise<EventHandled>; /** Called when user adds a touch point by placing a finger or stylus on the surface. */ onTouchStart(_ev: BeTouchEvent): Promise<void>; /** Called when user removes a touch point by lifting a finger or stylus from the surface. */ onTouchEnd(_ev: BeTouchEvent): Promise<void>; /** Called when the last touch point is removed from the surface completing the current gesture. This is a convenience event sent following onTouchEnd when no target touch points remain on the surface. */ onTouchComplete(_ev: BeTouchEvent): Promise<void>; /** Called when a touch point is interrupted in some way and needs to be dropped from the list of target touches. */ onTouchCancel(_ev: BeTouchEvent): Promise<void>; /** Called when a touch point moves along the surface. */ onTouchMove(_ev: BeTouchEvent): Promise<void>; /** Called after at least one touch point has moved for an appreciable time and distance along the surface to not be considered a tap. * @param _ev The event that caused this call * @param _startEv The event from the last call to onTouchStart * @return Yes if event completely handled by tool and event should not be passed on to the IdleTool. */ onTouchMoveStart(_ev: BeTouchEvent, _startEv: BeTouchEvent): Promise<EventHandled>; /** Called when touch point(s) are added and removed from a surface within a small time window without any touch point moving. * @param _ev The event that caused this call * @return Yes if event completely handled by tool and event should not be passed on to the IdleTool. * @note A double or triple tap event will not be preceded by a single tap event. */ onTouchTap(_ev: BeTouchEvent): Promise<EventHandled>; isCompatibleViewport(_vp: ScreenViewport, _isSelectedViewChange: boolean): boolean; isValidLocation(_ev: BeButtonEvent, _isButtonEvent: boolean): boolean; /** * Called when active view changes. Tool may choose to restart or exit based on current view type. * @param previous The previously active view. * @param current The new active view. */ onSelectedViewportChanged(_previous: ScreenViewport | undefined, _current: ScreenViewport | undefined): void; /** * Invoked before the locate tooltip is displayed to retrieve the information about the located element. Allows the tool to override the toolTip. * @param hit The HitDetail whose info is needed. * @return A Promise for the HTMLElement or string to describe the hit. * @note If you override this method, you may decide whether to call your superclass' implementation or not (it is not required). */ getToolTip(_hit: HitDetail): Promise<HTMLElement | string>; /** Convenience method to check whether control key is currently down without needing a button event. */ get isControlDown(): boolean; /** Fill the supplied button event from the current cursor location. */ getCurrentButtonEvent(ev: BeButtonEvent): void; /** Call to find out if dynamics are currently active. */ get isDynamicsStarted(): boolean; /** Call to initialize dynamics mode. While dynamics are active onDynamicFrame will be called. Dynamics are typically only used by a PrimitiveTool that creates or modifies geometric elements. */ beginDynamics(): void; /** Call to terminate dynamics mode. */ endDynamics(): void; /** Called to allow Tool to display dynamic elements. */ onDynamicFrame(_ev: BeButtonEvent, _context: DynamicsContext): void; /** Invoked to allow tools to filter which elements can be located. * @return Reject if hit is unacceptable for this tool (fill out response with explanation, if it is defined) */ filterHit(_hit: HitDetail, _out?: LocateResponse): Promise<LocateFilterStatus>; /** Helper method to keep the view cursor, display of locate circle, and coordinate lock overrides consistent with [[AccuSnap.isLocateEnabled]] and [[AccuSnap.isSnapEnabled]]. * @param enableLocate Value to pass to [[AccuSnap.enableLocate]]. Tools that locate elements should always pass true to give the user feedback regarding the element at the current cursor location. * @param enableSnap Optional value to pass to [[AccuSnap.enableSnap]]. Tools that don't care about the element pick location should not pass true. Default is false. * @note User must also have snapping enabled [[AccuSnap.isSnapEnabledByUser]], otherwise [[TentativePoint]] is used to snap. * @param cursor Optional tool specific cursor override. Default is either cross or dynamics cursor depending on whether dynamics are currently active. * @param coordLockOvr Optional tool specific coordinate lock overrides. A tool that only identifies elements and does not use [[BeButtonEvent.point]] can set ToolState.coordLockOvr to CoordinateLockOverrides.ACS * or CoordinateLockOverrides.All, otherwise locate is affected by the input point being first projected to the ACS plane. A tool that will use [[BeButtonEvent.point]], especially those that call [[AccuSnap.enableSnap]] * should honor all locks and leave ToolState.coordLockOvr set to CoordinateLockOverrides.None, the default for ViewTool and PrimitiveTool. */ changeLocateState(enableLocate: boolean, enableSnap?: boolean, cursor?: string, coordLockOvr?: CoordinateLockOverrides): void; /** Helper method for tools that need to locate existing elements. * Initializes [[ElementLocateManager]], changes the view cursor to locate, enables display of the locate circle, and sets the appropriate coordinate lock overrides. * @see [[changeLocateState]] */ initLocateElements(enableLocate?: boolean, enableSnap?: boolean, cursor?: string, coordLockOvr?: CoordinateLockOverrides): void; /** @internal */ protected toolSettingProperties?: Map<string, DialogProperty<any>>; /** @internal */ protected restoreToolSettingPropertyValue(property: DialogProperty<any>): boolean; /** @internal */ protected saveToolSettingPropertyValue(property: DialogProperty<any>, itemValue: DialogItemValue): boolean; /** @internal */ protected syncToolSettingPropertyValue(property: DialogProperty<any>, isDisabled?: boolean): void; /** @internal */ protected getToolSettingPropertyByName(propertyName: string): DialogProperty<any>; /** Override to return the property that is locked by the supplied property if it is a lock property. * Used to enable/disable the returned property according to the current lock state. * @note Only applicable when [[getToolSettingLockProperty]] is not being used automatically enable the lock on a change of value. * @see [[changeToolSettingPropertyValue]] * @public */ protected getToolSettingPropertyLocked(_property: DialogProperty<any>): DialogProperty<any> | undefined; /** Override to return the lock property associated with the supplied non-lock property. * Used to enable the lock property after the value of the supplied property is changed. * @see [[changeToolSettingPropertyValue]] * @beta */ protected getToolSettingLockProperty(_property: DialogProperty<any>): DialogProperty<boolean> | undefined; /** Helper method for responding to a tool setting property value change by updating saved settings. * @see [[applyToolSettingPropertyChange]] * @see [[getToolSettingPropertyLocked]] to return the corresponding locked property, if any. * @see [[getToolSettingLockProperty]] to return the corresponding property's lock property, if any. * @public */ protected changeToolSettingPropertyValue(syncItem: DialogPropertySyncItem): boolean; /** Helper method to establish initial values for tool setting properties from saved settings. * @see [[supplyToolSettingsProperties]] * @public */ protected initializeToolSettingPropertyValues(properties: DialogProperty<any>[]): void; /** Used to supply list of properties that can be used to generate ToolSettings. If undefined is returned then no ToolSettings will be displayed. * @see [[initializeToolSettingPropertyValues]] * @public */ supplyToolSettingsProperties(): DialogItem[] | undefined; /** Used to receive property changes from UI. Return false if there was an error applying updatedValue. * @see [[changeToolSettingPropertyValue]] * @public */ applyToolSettingPropertyChange(_updatedValue: DialogPropertySyncItem): Promise<boolean>; /** Called by tool to synchronize the UI with property changes made by tool. This is typically used to provide user feedback during tool dynamics. * If the syncData contains a quantity value and if the displayValue is not defined, the displayValue will be generated in the UI layer before displaying the value. * @public */ syncToolSettingsProperties(syncData: DialogPropertySyncItem[]): void; /** Called by tool to inform UI to reload ToolSettings with new set of properties. This allows properties to be added or removed from ToolSetting * component as tool processing progresses. * @public */ reloadToolSettingsProperties(): void; /** Used to "bump" the value of a tool setting. To "bump" a setting means to toggle a boolean value or cycle through enum values. * If no `settingIndex` param is specified, the first setting is bumped. * Return true if the setting was successfully bumped. * @public */ bumpToolSetting(_settingIndex?: number): Promise<boolean>; } /** The InputCollector class can be used to implement a command for gathering input * (ex. get a distance by snapping to 2 points) without affecting the state of the active primitive tool. * An InputCollector will suspend the active PrimitiveTool and can be suspended by a ViewTool. * @public * @extensions */ export declare abstract class InputCollector extends InteractiveTool { run(..._args: any[]): Promise<boolean>; exitTool(): Promise<void>; onResetButtonUp(_ev: BeButtonEvent): Promise<EventHandled>; } /** The result type of [[ToolRegistry.parseAndRun]]. * @public * @extensions */ export declare enum ParseAndRunResult { /** The tool's `parseAndRun` method was invoked and returned `true`. */ Success = 0, /** No tool matching the toolId in the keyin is registered. */ ToolNotFound = 1, /** The number of arguments supplied does not meet the constraints of the Tool. @see [[Tool.minArgs]] and [[Tool.maxArgs]]. */ BadArgumentCount = 2, /** The tool's `parseAndRun` method returned `false`. */ FailedToRun = 3, /** An opening double-quote character was not paired with a closing double-quote character. */ MismatchedQuotes = 4 } /** Possible errors resulting from [[ToolRegistry.parseKeyin]]. * @public * @extensions */ export declare enum KeyinParseError { /** No registered tool matching the keyin was found. */ ToolNotFound = 1, /** The opening double-quote of an argument was not terminated with a closing double-quote. */ MismatchedQuotes = 4 } /** Possible errors form [[ToolRegistry.parseKeyin]]. * @public * @extensions */ export interface ParseKeyinError { /** Union discriminator for [[ParseKeyinResult]]. */ ok: false; /** The specific error that occurred during parsing. */ error: KeyinParseError; } /** Successful result from [[ToolRegistry.parseKeyin]]. * @public * @extensions */ export interface ParsedKeyin { /** Union discriminator for [[ParseKeyinResult]]. */ ok: true; /** The constructor for the Tool that handles the keyin. */ tool: ToolType; /** The parsed arguments to be passed to [[Tool.parseAndRun]]. */ args: string[]; } /** The result type of [[ToolRegistry.parseKeyin]]. * @public * @extensions */ export type ParseKeyinResult = ParsedKeyin | ParseKeyinError; /** The ToolRegistry holds a mapping between toolIds and their corresponding [[Tool]] class. This provides the mechanism to * find Tools by their toolId, and also a way to iterate over the set of Tools available. * @public */ export declare class ToolRegistry { readonly tools: Map<string, typeof Tool>; private _keyinList?; shutdown(): void; /** * Un-register a previously registered Tool class. * @param toolId the toolId of a previously registered tool to unRegister. */ unRegister(toolId: string): void; /** * Register a Tool class. This establishes a connection between the toolId of the class and the class itself. * @param toolClass the subclass of Tool to register. * @param namespace the namespace for the localized strings for this tool. If undefined, use namespace from superclass. */ register(toolClass: ToolType, namespace?: string): void; /** * Register all the Tool classes found in a module. * @param modelObj the module to search for subclasses of Tool. */ registerModule(moduleObj: any, namespace?: string): void; /** Look up a tool by toolId */ find(toolId: string): ToolType | undefined; /** * Look up a tool by toolId and, if found, create an instance with the supplied arguments. * @param toolId the toolId of the tool * @param args arguments to pass to the constructor. * @returns an instance of the registered Tool class, or undefined if toolId is not registered. */ create(toolId: string, ...args: any[]): Tool | undefined; /** * Look up a tool by toolId and, if found, create an instance with the supplied arguments and run it. * @param toolId toolId of the immediate tool * @param args arguments to pass to the constructor, and to run. * @return true if the tool was found and successfully run. */ run(toolId: string, ...args: any[]): Promise<boolean>; /** * Split key-in into and array of string arguments. Handles embedded quoted strings. * @param keyin keyin string to process * #return an Array of string argument */ private tokenize; /** Given a string consisting of a toolId followed by any number of arguments, locate the corresponding Tool and parse the arguments. * Tokens are delimited by whitespace. * The Tool is determined by finding the longest string of unquoted tokens starting at the beginning of the key-in string that matches a registered Tool's * `keyin` or `englishKeyin`. * Tokens following the Tool's keyin are parsed as arguments. * Arguments may be quoted using "double quotes". The opening quote must be preceded by whitespace. Examples, assuming the tool Id is `my keyin`: * - `my keyin "abc" "def"` => two arguments: `abc` and `def` * - `my keyin abc"def"` => one argument: `abc"def"` * A literal double-quote character can be embedded in a quoted argument as follows: * - `my keyin "abc""def"` => one argument: `abc"def`. * @param keyin A string consisting of a toolId followed by any number of arguments. The arguments are separated by whitespace. * @returns The tool, if found, along with an array of parsed arguments. * @public */ parseKeyin(keyin: string): ParseKeyinResult; /** Get a list of Tools currently registered, excluding hidden tools */ getToolList(): ToolList; /** Given a string consisting of a toolId followed by any number of arguments, parse the keyin string and invoke the corresponding tool's `parseAndRun` method. * @param keyin A string consisting of a toolId followed by any number of arguments. * @returns A status indicating whether the keyin was successfully parsed and executed. * @see [[parseKeyin]] to parse the keyin string and for a detailed description of the syntax. * @throws any Error thrown by the tool's `parseAndRun` method. * @public */ parseAndRun(keyin: string): Promise<ParseAndRunResult>; /** * Find a tool by its localized keyin using a FuzzySearch * @param keyin the localized keyin string of the Tool. * @note Make sure the i18n resources are all loaded (e.g. `await IModelApp.i81n.waitForAllRead()`) before calling this method. * @public */ findPartialMatches(keyin: string): FuzzySearchResults<ToolType>; /** * Find a tool by its localized keyin. * @param keyin the localized keyin string of the Tool. * @returns the Tool class, if an exact match is found, otherwise returns undefined. * @note Make sure the i18n resources are all loaded (e.g. `await IModelApp.i81n.waitForAllRead()`) before calling this method. * @public */ findExactMatch(keyin: string): ToolType | undefined; } /** @internal */ export declare class CoreTools { static namespace: string; static tools: string; static translate(prompt: string): string; static outputPromptByKey(key: string): void; } //# sourceMappingURL=Tool.d.ts.map