UNPKG

7.65 kBTypeScriptView Raw
1import URI from '../common/uri';
2import { ContributionProvider } from '../common/contribution-provider';
3import { Event, Emitter, Disposable } from '../common';
4import { FrontendApplicationContribution } from './frontend-application';
5import { EnvVariablesServer } from '../common/env-variables/env-variables-protocol';
6import { ResourceLabelFormatter, ResourceLabelFormatting } from '../common/label-protocol';
7export declare const LabelProviderContribution: unique symbol;
8/**
9 * A {@link LabelProviderContribution} determines how specific elements/nodes are displayed in the workbench.
10 * Theia views use a common {@link LabelProvider} to determine the label and/or an icon for elements shown in the UI. This includes elements in lists
11 * and trees, but also view specific locations like headers. The common {@link LabelProvider} collects all {@links LabelProviderContribution} and delegates
12 * to the contribution with the highest priority. This is determined via calling the {@link LabelProviderContribution.canHandle} function, so contributions
13 * define which elements they are responsible for.
14 * As arbitrary views can consume LabelProviderContributions, they must be generic for the covered element type, not view specific. Label providers and
15 * contributions can be used for arbitrary element and node types, e.g. for markers or domain-specific elements.
16 */
17export interface LabelProviderContribution {
18 /**
19 * Determines whether this contribution can handle the given element and with what priority.
20 * All contributions are ordered by the returned number if greater than zero. The highest number wins.
21 * If two or more contributions return the same positive number one of those will be used. It is undefined which one.
22 */
23 canHandle(element: object): number;
24 /**
25 * returns an icon class for the given element.
26 */
27 getIcon?(element: object): string | undefined;
28 /**
29 * returns a short name for the given element.
30 */
31 getName?(element: object): string | undefined;
32 /**
33 * returns a long name for the given element.
34 */
35 getLongName?(element: object): string | undefined;
36 /**
37 * A compromise between {@link getName} and {@link getLongName}. Can be used to supplement getName in contexts that allow both a primary display field and extra detail.
38 */
39 getDetails?(element: object): string | undefined;
40 /**
41 * Emit when something has changed that may result in this label provider returning a different
42 * value for one or more properties (name, icon etc).
43 */
44 readonly onDidChange?: Event<DidChangeLabelEvent>;
45 /**
46 * Checks whether the given element is affected by the given change event.
47 * Contributions delegating to the label provider can use this hook
48 * to perform a recursive check.
49 */
50 affects?(element: object, event: DidChangeLabelEvent): boolean;
51}
52export interface DidChangeLabelEvent {
53 affects(element: object): boolean;
54}
55export interface URIIconReference {
56 kind: 'uriIconReference';
57 id: 'file' | 'folder';
58 uri?: URI;
59}
60export declare namespace URIIconReference {
61 function is(element: unknown): element is URIIconReference;
62 function create(id: URIIconReference['id'], uri?: URI): URIIconReference;
63}
64export declare class DefaultUriLabelProviderContribution implements LabelProviderContribution {
65 protected formatters: ResourceLabelFormatter[];
66 protected readonly onDidChangeEmitter: Emitter<DidChangeLabelEvent>;
67 protected homePath: string | undefined;
68 protected readonly envVariablesServer: EnvVariablesServer;
69 init(): void;
70 canHandle(element: object): number;
71 getIcon(element: URI | URIIconReference): string;
72 get defaultFolderIcon(): string;
73 get defaultFileIcon(): string;
74 protected getFileIcon(uri: URI): string | undefined;
75 getName(element: URI | URIIconReference): string | undefined;
76 getLongName(element: URI | URIIconReference): string | undefined;
77 getDetails(element: URI | URIIconReference): string | undefined;
78 protected getUri(element: URI | URIIconReference): URI | undefined;
79 registerFormatter(formatter: ResourceLabelFormatter): Disposable;
80 get onDidChange(): Event<DidChangeLabelEvent>;
81 private fireOnDidChange;
82 private readonly labelMatchingRegexp;
83 protected formatUri(resource: URI, formatting: ResourceLabelFormatting): string;
84 private hasDriveLetter;
85 protected findFormatting(resource: URI): ResourceLabelFormatting | undefined;
86}
87/**
88 * The {@link LabelProvider} determines how elements/nodes are displayed in the workbench. For any element, it can determine a short label, a long label
89 * and an icon. The {@link LabelProvider} is to be used in lists, trees and tables, but also view specific locations like headers.
90 * The common {@link LabelProvider} can be extended/adapted via {@link LabelProviderContribution}s. For every element, the {@links LabelProvider} will determine the
91 * {@link LabelProviderContribution} with the hightest priority and delegate to it. Theia registers default {@link LabelProviderContribution} for common types, e.g.
92 * the {@link DefaultUriLabelProviderContribution} for elements that have a URI.
93 * Using the {@link LabelProvider} across the workbench ensures a common look and feel for elements across multiple views. To adapt the way how specific
94 * elements/nodes are rendered, use a {@link LabelProviderContribution} rather than adapting or sub classing the {@link LabelProvider}. This way, your adaptation
95 * is applied to all views in Theia that use the {@link LabelProvider}
96 */
97export declare class LabelProvider implements FrontendApplicationContribution {
98 protected readonly onDidChangeEmitter: Emitter<DidChangeLabelEvent>;
99 protected readonly contributionProvider: ContributionProvider<LabelProviderContribution>;
100 /**
101 * Start listening to contributions.
102 *
103 * Don't call this method directly!
104 * It's called by the frontend application during initialization.
105 */
106 initialize(): void;
107 protected affects(element: object, event: DidChangeLabelEvent): boolean;
108 get onDidChange(): Event<DidChangeLabelEvent>;
109 /**
110 * Return a default file icon for the current icon theme.
111 */
112 get fileIcon(): string;
113 /**
114 * Return a default folder icon for the current icon theme.
115 */
116 get folderIcon(): string;
117 /**
118 * Get the icon class from the list of available {@link LabelProviderContribution} for the given element.
119 * @return the icon class
120 */
121 getIcon(element: object): string;
122 /**
123 * Get a short name from the list of available {@link LabelProviderContribution} for the given element.
124 * @return the short name
125 */
126 getName(element: object): string;
127 /**
128 * Get a long name from the list of available {@link LabelProviderContribution} for the given element.
129 * @return the long name
130 */
131 getLongName(element: object): string;
132 /**
133 * Get details from the list of available {@link LabelProviderContribution} for the given element.
134 * @return the details
135 * Can be used to supplement {@link getName} in contexts that allow both a primary display field and extra detail.
136 */
137 getDetails(element: object): string;
138 protected handleRequest(element: object, method: keyof Omit<LabelProviderContribution, 'canHandle' | 'onDidChange' | 'affects'>): string | undefined;
139 protected findContribution(element: object, method?: keyof Omit<LabelProviderContribution, 'canHandle' | 'onDidChange' | 'affects'>): LabelProviderContribution[];
140}
141//# sourceMappingURL=label-provider.d.ts.map
\No newline at end of file