Package Exports
- @itwin/unified-selection
- @itwin/unified-selection/package.json
Readme
@itwin/unified-selection
Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.
The purpose of the @itwin/unified-selection package and unified selection in general is to act as a single source of truth of what is selected in an iTwin.js application.
Concepts
The API consists of a few very basic concepts:
A
Selectableis something that can be selected and is associated with an EC instance. There are 2 types of selectables:SelectableInstanceKeyuniquely identifies a single EC instance through a full class name and ECInstanceId.CustomSelectableis identified by an arbitraryidentifierstring and knows how to get any number ofSelectableInstanceKeyassociated with it.
Selectablesis a container for multipleSelectableinstances. The container is structured in a way that allows to quickly find specific selectables by their identifier.SelectionStorageis an interface that managesSelectablesfor different iModels. It allows:- Changing the selection (add, remove, replace, clear).
- Get active selection.
- Listen to selection changes.
The package delivers the
createStorage()function to create an instance ofSelectionStorage. Consumers are also expected to callSelectionStorage.clearStoragewhenever an iModel is closed to free up memory.
Usage example
// Create a global selection store (generally, somewhere in main.ts or similar). This store
// must be shared across all the application's components to ensure unified selection experience.
import { createStorage } from "@itwin/unified-selection";
const unifiedSelection = createStorage();
// The store should to be cleaned up when iModels are closed to free up memory, e.g.:
import { IModelConnection } from "@itwin/core-frontend";
import { createIModelKey } from "@itwin/presentation-core-interop";
IModelConnection.onClose.addListener((imodel) => {
unifiedSelection.clearStorage({ imodelKey: createIModelKey(imodel) });
});
// A demo selection listener logs selection changes to the console:
import { Selectables } from "@itwin/unified-selection";
unifiedSelection.selectionChangeEvent.addListener(({ imodelKey, source, changeType, selectables }) => {
const suffix = `in ${imodelKey} iModel from ${source} component`;
const numSelectables = Selectables.size(selectables);
switch (changeType) {
case "add":
console.log(`Added ${numSelectables} items to selection ${suffix}.`);
break;
case "remove":
console.log(`Removed ${numSelectables} items from selection ${suffix}.`);
break;
case "replace":
console.log(`Replaced selection with ${numSelectables} items ${suffix}.`);
break;
case "clear":
console.log(`Cleared selection ${suffix}.`);
break;
}
});
// An interactive component that allows selecting elements, representing something in an iModel, may want to
// add that something to unified selection:
MyComponent.onECInstanceSelected((imodel: IModelConnection, key: { className: string; id: Id64String }) => {
unifiedSelection.addToSelection({ imodelKey: createIModelKey(imodel), source: "MyComponent", selectables: [key] });
});Learning
Are you migrating from SelectionManager in @itwin/presentation-frontend? Check out our Migrating from SelectionManager learning page!
Below is a list of learning material related integrating unified selection into your components:
- General topics:
- Integrating with iTwin.js components:
Do you think something is missing in the above list? Let us know by creating an issue!