bpmn-visualization/dist/component/registry/bpmn-elements-registry.d.ts

A TypeScript library for visualizing process execution data on BPMN diagrams

/**
 * Copyright 2020 Bonitasoft S.A.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import type { BpmnElement, Overlay } from './types';
import type { BpmnElementKind } from '../../model/bpmn/internal';
/**
 * `BpmnElementRegistry` is a public API that permits to find the BpmnElements present in the diagram.
 * How to access it:
 *
 * ```javascript
 * // 1. Initialize the BpmnVisualization.
 * const bpmnVisualization = new BpmnVisualization({ container: 'bpmn-container' });
 * // 2. Get diagram and load it.
 * const bpmn = 'BPMN diagram string - whether coming from bpmn.xml file or some API call';
 * bpmnVisualization.load(bpmn);
 * // 3. Access registry directly from bpmnVisualization.
 * bpmnVisualization.bpmnElementsRegistry
 * ```
 *
 * **WARN**: subject to change, feedback welcome.
 *
 *  @category Custom Behavior
 *  @experimental
 */
export declare class BpmnElementsRegistry {
    private bpmnModelRegistry;
    private htmlElementRegistry;
    private cssRegistry;
    private graphCellUpdater;
    /**
     * Get all elements by ids. The returned array contains elements in the order of the `bpmnElementIds` parameter.
     *
     * Not found elements are not returned as undefined in the array, so the returned array contains at most as much elements as the `bpmnElementIds` parameter.
     *
     * ```javascript
     * ...
     * // Find all elements by specified id or ids
     * const bpmnElements1 = bpmnVisualization.bpmnElementsRegistry.getElementsByIds('userTask_1');
     * const bpmnElements2 = bpmnVisualization.bpmnElementsRegistry.getElementsByIds(['startEvent_3', 'userTask_2']);
     * // now you can do whatever you want with the elements
     * ...
     * ```
     *
     * **WARNING**: this method is not designed to accept a large amount of ids. It does DOM lookup to retrieve the HTML elements relative to the BPMN elements.
     * Attempts to retrieve too many elements, especially on large BPMN diagram, may lead to performance issues.
     */
    getElementsByIds(bpmnElementIds: string | string[]): BpmnElement[];
    /**
     * Get all elements by kinds.
     *
     * ```javascript
     * ...
     * // Find all elements by desired type or types
     * const bpmnTaskElements = bpmnVisualization.bpmnElementsRegistry.getElementsByKinds(ShapeBpmnElementKind.TASK);
     * const bpmnEndEventAndPoolElements = bpmnVisualization.bpmnElementsRegistry.getElementsByKinds([ShapeBpmnElementKind.EVENT_END, ShapeBpmnElementKind.POOL]);
     * // now you can do whatever you want with the elements
     * ...
     * ```
     *
     * **WARNING**: this method is not designed to accept a large amount of types. It does DOM lookup to retrieve the HTML elements relative to the BPMN elements.
     * Attempts to retrieve too many elements, especially on large BPMN diagrams, may lead to performance issues.
     */
    getElementsByKinds(bpmnKinds: BpmnElementKind | BpmnElementKind[]): BpmnElement[];
    /**
     * Add one/several CSS class(es) to one/several BPMN element(s).
     *
     * Notice that if you pass ids that are not related to existing BPMN elements, their reference will be kept within the registry but nothing happens on the rendering side.
     *
     * @example
     * ```javascript
     * // Add 'success-path' to BPMN elements with id: flow_1 and flow_5
     * bpmnVisualization.bpmnElementsRegistry.addCssClasses(['flow_1', 'flow_5'], 'success-path');
     *
     * // Add 'suspicious-path' and 'additional-info' to BPMN element with id: task_3
     * bpmnVisualization.bpmnElementsRegistry.addCssClasses('task_3', ['suspicious-path', 'additional-info']);
     * ```
     *
     * **Notes**:
     *
     * - This method is intended to set CSS classes to specific elements, for instance to hide or highlight them. During BPMN diagram rendering, `bpmn-visualization` set specific CSS classes to all elements regarding their types.
     * So, if you want to style all elements of a given type, use these default classes instead of adding new ones. The classes allow identifying elements of the same 'family' and of the same specific type.
     * - For instance, a BPMN Service Task is an `Activity` and a `Task`, so it has the `bpmn-type-activity` and the `bpmn-type-task` classes. It shares these classes with all types of `Tasks`.
     * It also has the specific `bpmn-service-task` to differentiate it from a BPMN User Task that has a `bpmn-user-task`.
     * - In addition, labels also have the `bpmn-label` classes.
     *
     * Check the examples for more details.
     *
     * @param bpmnElementIds The BPMN id of the element(s) where to add the CSS classes
     * @param classNames The name of the class(es) to add to the BPMN element(s)
     */
    addCssClasses(bpmnElementIds: string | string[], classNames: string | string[]): void;
    /**
     * Remove one/several CSS class(es) previously added with the `addCssClasses` or the `toggleCssClasses` methods from one/several BPMN element(s).
     *
     * @example
     * ```javascript
     * // Remove 'highlight' from BPMN elements with id: activity_1 and activity_2
     * bpmnVisualization.bpmnElementsRegistry.removeCssClasses(['activity_1', 'activity_2'], 'highlight');
     *
     * // Remove 'running' and 'additional-info' from BPMN element with id: task_3
     * bpmnVisualization.bpmnElementsRegistry.removeCssClasses('task_3', ['running', 'additional-info']);
     * ```
     *
     * @param bpmnElementIds The BPMN id of the element(s) where to remove the CSS classes
     * @param classNames The name of the class(es) to remove from the BPMN element(s)
     */
    removeCssClasses(bpmnElementIds: string | string[], classNames: string | string[]): void;
    /**
     * Toggle one/several CSS class(es) for one/several BPMN element(s).
     * Notice that if you pass ids that are not related to existing BPMN elements, their reference will be kept within the registry but nothing happens on the rendering side.
     *
     * @example
     * ```javascript
     * // Toggle 'highlight' for BPMN elements with id: activity_1 and activity_2
     * bpmnVisualization.bpmnElementsRegistry.toggleCssClasses(['activity_1', 'activity_2'], 'highlight');
     *
     * // Toggle 'running' and 'additional-info' for BPMN element with id: task_3
     * bpmnVisualization.bpmnElementsRegistry.toggleCssClasses('task_3', ['running', 'additional-info']);
     * ```
     *
     * @param bpmnElementIds The BPMN id of the element(s) where to remove the CSS classes
     * @param classNames The name of the class(es) to remove from the BPMN element(s)
     */
    toggleCssClasses(bpmnElementIds: string | string[], classNames: string | string[]): void;
    private updateCssClasses;
    private updateCellIfChanged;
    /**
     * Add one/several overlays to a BPMN element.
     *
     * Notice that if you pass an id that is not related to an existing BPMN element, nothing happens on the rendering side.
     *
     * @example
     * ```javascript
     * // Add an overlay to BPMN elements with id 'task_1'
     * bpmnVisualization.bpmnElementsRegistry.addOverlays('task_1', {
     *    position: 'top-left',
     *    label: '40',
     *    style: {
     *      font: { color: 'Chartreuse', size: 8 },
     *      fill: { color: 'Pink', opacity: 50 },
     *      stroke: { color: 'DarkSeaGreen', width: 2 }
     *    }
     * });
     *
     * // Add several overlays to BPMN element with id 'task_3'
     * bpmnVisualization.bpmnElementsRegistry.addOverlays('task_3', [
     *    {
     *      position: 'bottom-right',
     *      label: '110',
     *      style: {
     *        font: { color: '#663399', size: 8 },
     *        fill: { color: '#FFDAB9', opacity: 50 },
     *        stroke: { color: 'DarkSeaGreen', width: 2 }
     *      }
     *    },
     *    {
     *      position: 'top-left',
     *      label: '40',
     *      style: {
     *        font: { color: 'MidnightBlue', size: 30 },
     *        fill: { color: 'Aquamarine', opacity: 70 },
     *        stroke: { color: '#4B0082', width: 1 }
     *      }
     *    }
     * ]);
     * ```
     *
     * @param bpmnElementId The BPMN id of the element where to add the overlays
     * @param overlays The overlays to add to the BPMN element
     */
    addOverlays(bpmnElementId: string, overlays: Overlay | Overlay[]): void;
    /**
     * Remove all overlays of a BPMN element.
     *
     * <b>WARNING</b>: could be renamed when adding support for removal of one or several specific overlays.
     *
     * @example
     * ```javascript
     * //  all overlays of the BPMN element with id: activity_1
     * bpmnVisualization.bpmnElementsRegistry.removeAllOverlays('activity_1');
     * ```
     *
     * @param bpmnElementId The BPMN id of the element where to remove the overlays
     */
    removeAllOverlays(bpmnElementId: string): void;
}