sprotty/lib/features/routing/routing.d.ts

A next-gen framework for graphical views

/********************************************************************************
 * Copyright (c) 2018-2021 TypeFox and others.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the Eclipse
 * Public License v. 2.0 are satisfied: GNU General Public License, version 2
 * with the GNU Classpath Exception which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 ********************************************************************************/
import { Point } from "sprotty-protocol/lib/utils/geometry";
import { SParentElementImpl } from "../../base/model/smodel";
import { IViewArgs } from "../../base/views/view";
import { InstanceRegistry } from "../../utils/registry";
import { ResolvedHandleMove } from "../move/move";
import { SRoutingHandleImpl } from "../routing/model";
import { SConnectableElementImpl, SRoutableElementImpl } from "./model";
/**
 * A point describing the shape of an edge.
 *
 * The <code>RoutedPoints</code> of an edge are derived from the <code>routingPoints</code>
 * which plain <code>Points</code> stored in the SModel by the <code>IEdgeRouter</code>.
 * As opposed to the originals, they also contain the source and target anchor points.
 * The router may also add or remove points in order to satisfy the constraints
 * the constraints of the routing algorithm or in order to to filter out points which are
 * obsolete, e.g. to close to each other.
 */
export interface RoutedPoint extends Point {
    kind: 'source' | 'target' | 'linear' | 'bezier-control-before' | 'bezier-junction' | 'bezier-control-after';
    pointIndex?: number;
    isJunction?: boolean;
}
/**
 * Stores the state of an edge at a specific time.
 */
export interface EdgeSnapshot {
    routingHandles: SRoutingHandleImpl[];
    routingPoints: Point[];
    routedPoints: RoutedPoint[];
    router: IEdgeRouter;
    source?: SConnectableElementImpl;
    target?: SConnectableElementImpl;
}
export interface EdgeMemento {
    edge: SRoutableElementImpl;
    before: EdgeSnapshot;
    after: EdgeSnapshot;
}
/**
 * Encapsulates the logic of how the actual shape of an edge is derived from its routing points,
 * and how the user can modify it.
 */
export interface IEdgeRouter {
    readonly kind: string;
    /**
     * Calculates the route of the given edge.
     */
    route(edge: SRoutableElementImpl): RoutedPoint[];
    /**
     * Finds the orthogonal intersection point between an edge and a given point in 2D space.
     *
     * @param edge - The edge to find the intersection point on.
     * @param point - The point to find the intersection with.
     * @returns The intersection point and its derivative on the respective edge segment.
     */
    findOrthogonalIntersection(edge: SRoutableElementImpl, point: Point): {
        point: Point;
        derivative: Point;
    } | undefined;
    /**
     * Calculates a point on the edge
     *
     * @param t a value between 0 (sourceAnchor) and 1 (targetAnchor)
     * @returns the point or undefined if t is out of bounds or it cannot be computed
     */
    pointAt(edge: SRoutableElementImpl, t: number): Point | undefined;
    /**
     * Calculates the derivative at a point on the edge.
     *
     * @param t a value between 0 (sourceAnchor) and 1 (targetAnchor)
     * @returns the point or undefined if t is out of bounds or it cannot be computed
     */
    derivativeAt(edge: SRoutableElementImpl, t: number): Point | undefined;
    /**
     * Retuns the position of the given handle based on the routing points of the edge.
     */
    getHandlePosition(edge: SRoutableElementImpl, route: RoutedPoint[], handle: SRoutingHandleImpl): Point | undefined;
    /**
     * Creates the routing handles for the given target.
     */
    createRoutingHandles(edge: SRoutableElementImpl): void;
    /**
     * Updates the routing points and handles of the given edge with regard to the given moves.
     */
    applyHandleMoves(edge: SRoutableElementImpl, moves: ResolvedHandleMove[]): void;
    /**
     * Updates the routing points and handles of the given edge with regard to the given moves.
     */
    applyReconnect(edge: SRoutableElementImpl, newSourceId?: string, newTargetId?: string): void;
    /**
     * Remove/add points in order to keep routing constraints consistent, or reset RPs on reconnect.
     */
    cleanupRoutingPoints(edge: SRoutableElementImpl, routingPoints: Point[], updateHandles: boolean, addRoutingPoints: boolean): void;
    /**
     * Creates a snapshot of the given edge, storing all the data needed to restore it to
     * its current state.
     */
    takeSnapshot(edge: SRoutableElementImpl): EdgeSnapshot;
    /**
     * Applies a snapshot to the current edge.
     */
    applySnapshot(edge: SRoutableElementImpl, edgeSnapshot: EdgeSnapshot): void;
}
export interface IMultipleEdgesRouter extends IEdgeRouter {
    routeAll(edges: SRoutableElementImpl[], parent: Readonly<SParentElementImpl>): EdgeRouting;
}
/** A postprocessor that is applied to all routes, once they are computed. */
export interface IEdgeRoutePostprocessor {
    apply(routing: EdgeRouting, parent: SParentElementImpl): void;
}
export declare class EdgeRouterRegistry extends InstanceRegistry<IEdgeRouter> {
    protected postProcessors: IEdgeRoutePostprocessor[];
    constructor(edgeRouters: IEdgeRouter[]);
    protected get defaultKind(): string;
    get(kind: string | undefined): IEdgeRouter;
    /**
     * Computes the routes of all edges contained by the specified `parent`.
     * After all routes are available, it'll apply the registered `EdgeRoutePostProcessors`.
     * @param parent the parent to traverse for edges
     * @returns the routes of all edges that are children of `parent`
     */
    routeAllChildren(parent: Readonly<SParentElementImpl>): EdgeRouting;
    /**
     * Recursively traverses the children of `parent`, collects children grouped by router kind,
     * and then routes them either.
     * @param parent the parent to traverse for edges
     * @returns the routes of all edges that are children of `parent`
     */
    protected doRouteAllChildren(parent: Readonly<SParentElementImpl>): EdgeRouting;
    /**
     * Computes or obtains the route of a single edge.
     * @param edge the edge to be routed
     * @param args arguments that may contain an `EdgeRouting` already
     * @returns the route of the specified `edge`
     */
    route(edge: Readonly<SRoutableElementImpl>, args?: IViewArgs): RoutedPoint[];
}
/** Any object that contains a routing, such as an argument object passed to views for rendering. */
export interface EdgeRoutingContainer {
    edgeRouting: EdgeRouting;
}
/**
 * Map of edges and their computed routes.
 */
export declare class EdgeRouting {
    protected routesMap: Map<string, RoutedPoint[]>;
    set(routableId: string, route: RoutedPoint[]): void;
    setAll(otherRoutes: EdgeRouting): void;
    get(routableId: string): RoutedPoint[] | undefined;
    get routes(): Map<string, RoutedPoint[]>;
}
//# sourceMappingURL=routing.d.ts.map