UNPKG

6.23 kBTypeScriptView Raw
1import { Tree, TreeNode } from './tree';
2import { Event, Emitter, Disposable, DisposableCollection, MaybePromise } from '../../common';
3import { WidgetDecoration } from '../widget-decoration';
4/**
5 * The {@link TreeDecorator} allows adapting the look and the style of the tree items within a widget. Changes are reflected in
6 * the form of `decoration data`. This `decoration data` is a map storing {@link TreeDecoration.Data} for affected tree nodes (using the unique node id as key).
7 * It is important to notice that there is no common contribution point for `TreeDecorators`. Instead, each {@link TreeDecoratorService} is
8 * supposed to declare its own contribution provider for `TreeDecorators`.
9 *
10 * ### Example usage
11 * A simple tree decorator that changes the background color of each tree node to `red`.
12 *
13 * ```typescript
14 * @injectable()
15 * export class MyTreeDecorator implements TreeDecorator {
16 * id = 'myTreeDecorator';
17 *
18 * protected readonly emitter = new Emitter<(tree: Tree) => Map<string, TreeDecoration.Data>>();
19 *
20 * get onDidChangeDecorations(): Event<(tree: Tree) => Map<string, TreeDecoration.Data>> {
21 * return this.emitter.event;
22 * }
23 *
24 * decorations(tree: Tree): MaybePromise<Map<string, TreeDecoration.Data>> {
25 * const result = new Map();
26 *
27 * if (tree.root === undefined) {
28 * return result;
29 * }
30 * for (const treeNode of new DepthFirstTreeIterator(tree.root)) {
31 * result.set(treeNode.id,<TreeDecoration.Data>{backgroundColor:'red'})
32 * }
33 * return result;
34 * }
35 * }
36 * ```
37 */
38export interface TreeDecorator {
39 /**
40 * The unique identifier of the decorator. Ought to be unique in the application.
41 */
42 readonly id: string;
43 /**
44 * Fired when this decorator has calculated all the `decoration data` for the tree nodes.
45 */
46 readonly onDidChangeDecorations: Event<(tree: Tree) => Map<string, TreeDecoration.Data>>;
47 /**
48 * Computes the current `decoration data` for the given tree. Might return a promise if the computation is handled asynchronously.
49 *
50 * @param tree the tree to decorate.
51 *
52 * @returns (a promise of) a map containing the current {@linkTreeDecoration.Data} for each node. Keys are the unique identifier of the tree nodes.
53 */
54 decorations(tree: Tree): MaybePromise<Map<string, TreeDecoration.Data>>;
55}
56export declare const TreeDecoratorService: unique symbol;
57/**
58 * The {@link TreeDecoratorService} manages a set of known {link TreeDecorator}s and emits events when
59 * any of the known decorators has changes. Typically, a `TreeDecoratorService` provides a contribution point that can be used to
60 * register {@link TreeDecorator}s exclusively for this service.
61 *
62 * ### Example usage
63 * ```typescript
64 * export const MyTreeDecorator = Symbol('MyTreeDecorator');
65 *
66 * @injectable()
67 * export class MyDecorationService extends AbstractTreeDecoratorService {
68 * constructor(@inject(ContributionProvider) @named(MyTreeDecorator) protected readonly contributions: ContributionProvider<TreeDecorator>) {
69 * super(contributions.getContributions());
70 * }
71 * }
72 * ```
73 */
74export interface TreeDecoratorService extends Disposable {
75 /**
76 * Fired when any of the available tree decorators has changes.
77 */
78 readonly onDidChangeDecorations: Event<void>;
79 /**
80 * Computes the decorations for the tree based on the actual state of this decorator service.
81 *
82 * @param tree the tree to decorate
83 *
84 * @returns (a promise of) the computed `decoration data`
85 */
86 getDecorations(tree: Tree): MaybePromise<Map<string, TreeDecoration.Data[]>>;
87 /**
88 * Transforms the `decoration data` into an object, so that it can be safely serialized into JSON.
89 * @param decorations the `decoration data` that should be deflated
90 *
91 * @returns the `decoration data` as serializable JSON object
92 */
93 deflateDecorators(decorations: Map<string, TreeDecoration.Data[]>): object;
94 /**
95 * Counterpart of the [deflateDecorators](#deflateDecorators) method. Restores the argument into a Map
96 * of tree node IDs and the corresponding decorations data array (`decoration data`).
97 *
98 * @returns the deserialized `decoration data
99 */
100 inflateDecorators(state: any): Map<string, TreeDecoration.Data[]>;
101}
102/**
103 * The default tree decorator service. Does nothing at all. One has to rebind to a concrete implementation
104 * if decorators have to be supported in the tree widget.
105 */
106export declare class NoopTreeDecoratorService implements TreeDecoratorService {
107 protected readonly emitter: Emitter<void>;
108 readonly onDidChangeDecorations: Event<void>;
109 dispose(): void;
110 getDecorations(): Map<any, any>;
111 deflateDecorators(): object;
112 inflateDecorators(): Map<string, TreeDecoration.Data[]>;
113}
114/**
115 * Abstract decorator service implementation which emits events from all known tree decorators and caches the current state.
116 */
117export declare abstract class AbstractTreeDecoratorService implements TreeDecoratorService {
118 protected readonly decorators: ReadonlyArray<TreeDecorator>;
119 protected readonly onDidChangeDecorationsEmitter: Emitter<void>;
120 readonly onDidChangeDecorations: Event<void>;
121 protected readonly toDispose: DisposableCollection;
122 constructor(decorators: ReadonlyArray<TreeDecorator>);
123 dispose(): void;
124 getDecorations(tree: Tree): Promise<Map<string, TreeDecoration.Data[]>>;
125 deflateDecorators(decorations: Map<string, TreeDecoration.Data[]>): object;
126 inflateDecorators(state: any): Map<string, TreeDecoration.Data[]>;
127}
128/**
129 * @deprecated import from `@theia/core/lib/browser/widget-decoration` instead.
130 */
131export import TreeDecoration = WidgetDecoration;
132export interface DecoratedTreeNode extends TreeNode {
133 /**
134 * The additional tree decoration data attached to the tree node itself.
135 */
136 readonly decorationData: TreeDecoration.Data;
137}
138export declare namespace DecoratedTreeNode {
139 /**
140 * Type-guard for decorated tree nodes.
141 */
142 function is(node: TreeNode | undefined): node is DecoratedTreeNode;
143}
144//# sourceMappingURL=tree-decorator.d.ts.map
\No newline at end of file