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
import { IModelConnection } from "@itwin/core-frontend";
import { createIModelKey } from "@itwin/presentation-core-interop";
import { createStorage, Selectables } from "@itwin/unified-selection";
// 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.
const unifiedSelection = createStorage();
// The store should to be cleaned up when iModels are closed to free up memory, e.g.:
IModelConnection.onClose.addListener((iModelConnection) => {
unifiedSelection.clearStorage({ imodelKey: createIModelKey(iModelConnection) });
});
// A demo selection listener logs selection changes to the console:
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. For example:
const elementKey = { className: "BisCore.PhysicalElement", id: "0x1" };
unifiedSelection.addToSelection({ imodelKey: createIModelKey(imodel), source: "MyComponent", selectables: [elementKey] });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!