Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added docu for Label Provider #2

Closed
wants to merge 1 commit into from
Closed

Added docu for Label Provider #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions packages/core/src/browser/label-provider.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
* Contributors:
* TypeFox and others - Initial API and implementation
* Jonas Helming <jhelming@eclipsesource.com> Contributed on behalf of STMicroelectronics - Documentation
********************************************************************************/

import { inject, injectable, named, postConstruct } from 'inversify';
Expand Down Expand Up @@ -47,10 +50,21 @@ export const FOLDER_ICON = DEFAULT_FOLDER_ICON;
export const FILE_ICON = DEFAULT_FILE_ICON;

export const LabelProviderContribution = Symbol('LabelProviderContribution');
/**
* A {@link LabelProviderContribution} determines how specific elemens/nodes are displayed in the workbench.
* 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
* and trees, but also view specific locations like headers. The common {@link LabelProvider} collects all {@links LabelProviderContribution} and delegates
* to the contribution with the highest priority. This is determined via calling the {@link LabelProviderContribution.canHandle} function, so contributions
* define which elements they are responsible for.
* As an example, a {@links LabelProviderContribution} can contribute an icon for a specific file type. This would be used in multiple locations displaying files,
* e.g. the file explorer, the header of editors or in file dialogues. Therefore, as arbitrary views can consume LabelProviderContributions, they must be generic
* for the covered element type, not view specific. Label providers and contributions can be used for arbitrary element and node types, e.g. for markers or domain-specific
* elements.
*/
export interface LabelProviderContribution {

/**
* whether this contribution can handle the given element and with what priority.
* Determines whether this contribution can handle the given element and with what priority.
* All contributions are ordered by the returned number if greater than zero. The highest number wins.
* If two or more contributions return the same positive number one of those will be used. It is undefined which one.
*/
Expand Down Expand Up @@ -78,7 +92,7 @@ export interface LabelProviderContribution {
readonly onDidChange?: Event<DidChangeLabelEvent>;

/**
* Check whether the given element is affected by the given change event.
* Checks whether the given element is affected by the given change event.
* Contributions delegating to the label provider can use this hook
* to perform a recursive check.
*/
Expand Down Expand Up @@ -256,6 +270,16 @@ export class DefaultUriLabelProviderContribution implements LabelProviderContrib
}
}

/**
* The {@link LabelProvider} determines how elemens/nodes are displayed in the workbench. For any element, it can determine a short label, a long label
* and an icon. The {@link LabelProvider} is to be used in lists, trees and tables, but also view specific locations like headers.
* The common {@link LabelProvider} can be extended/adapted via {@link LabelProviderContribution}s. For every element, the {@links LabelProvider} will determine the
* {@link LabelProviderContribution} with the hightest priority and delegate to it. Theia registers default {@link LabelProviderContribution} for common types, e.g.
* the {@link DefaultUriLabelProviderContribution} for elements that have a URI.
* Using the {@link LabelProvider} across the workbench ensures a common look and feel for elements across multiple views. To adapt the way how specific
* elements/nodes are rendered, use a {@link LabelProviderContribution} rather than adapting or sub classing the {@link LabelProvider}. This way, your adaptation
* is applied to all view in Theia that use the {@link LabelProvider}
*/
@injectable()
export class LabelProvider implements FrontendApplicationContribution {

Expand Down Expand Up @@ -314,6 +338,9 @@ export class LabelProvider implements FrontendApplicationContribution {
return this.getIcon(URIIconReference.create('folder'));
}

/**
* returns an icon class for the given element.
*/
getIcon(element: object): string {
const contributions = this.findContribution(element);
for (const contribution of contributions) {
Expand All @@ -326,6 +353,9 @@ export class LabelProvider implements FrontendApplicationContribution {
return '';
}

/**
* returns a short name for the given element.
*/
getName(element: object): string {
const contributions = this.findContribution(element);
for (const contribution of contributions) {
Expand All @@ -338,6 +368,9 @@ export class LabelProvider implements FrontendApplicationContribution {
return '<unknown>';
}

/**
* returns a long name for the given element.
*/
getLongName(element: object): string {
const contributions = this.findContribution(element);
for (const contribution of contributions) {
Expand Down