Customise color of Codicon - Extensions custom view tree items

[warrenbuckley]

Goal

As an extension author, I wish to be able to customise the colors of icons used in tree items within my own custom view in conjunction with the colors contributions to allow consumers of the extension to tweak/change these colors if they wish to.

For example I wish to add some new colors via the package.json contributions method mentioned here but the documentation is limited and does not show any uses of where the retrieved color could be used to theme part of the UI, apart from fetching its value only.
https://code.visualstudio.com/api/references/contribution-points#contributes.colors

{
  "contributes": {
    "colors": [
      {
        "id": "iisexpress.startIcon",
        "description": "Color for the start icon tree item in the custom view.",
        "defaults": {
          "dark": "errorForeground",
          "light": "errorForeground",
          "highContrast": "#010203"
        }
      }
    ]
  }
}

Information

I have tried investigating how problemsWarningIcon.foreground is done in the codebase to see if I can do something similar and come across this file

https://github.com/microsoft/vscode/blob/8b7ea333ccc46fc8a27eda86199dfec57a4e255b/src/vs/platform/severityIcon/common/severityIcon.ts

It seems like registerThemingParticipant would be useful in order for me to do this, is anyone able to offer me some guidance or input please?

[alexr00]

@jrieken a request to color codicons.

@warrenbuckley if you want to have different colored icons in you tree view, you can't use codicons right now. There isn't a supported way to set the color on them. For now, you would need supply your own icons and set the color of them yourself.

[warrenbuckley]

@alexr00 & @jrieken if I supply my own coloured icons, then they can not be themeable by using the colors contribution or is this possible?

[alexr00]

I haven't done this before, but it should be possible for you to handle color theming your icons yourself. I think you would use this API to watch for theme changes, then retrieve the color you want from the workspace.colorCustomization setting. Then, you can modify your SVG or whatever it is you're using for your icons to be that color.

[warrenbuckley]

OK I will experiment later today and see how it goes, but as far as I know the iconPath property on vscode.TreeItem takes a string location to my own SVG, an object for dark & light variants or a vscode.ThemeIcon but I am not sure how I could update the SVG fill color for this scenario at the moment or am I missing something obvious @alexr00 ?

Update

As the SVG is not put inline or I have no access to the DOM, I have no way to set the fill attribute to set the color for the icon, the only hacky way I can think of doing is opening the svg file on disk and modifying it manually & re-saving it's contents when the onDidChangeActiveColorTheme event is fired with the custom color or is there a nicer way to achieve this?

[alexr00]

opening the svg file on disk and modifying it manually

That's what I was thinking of. I agree that it isn't ideal

[warrenbuckley]

@alexr00 I have created a related issue as I am unable to get the stored hex/color value stored but only an object with an ID to be even able to update a SVG file on disk. There are no examples or usages in docs on how I can use/consume a color that my extension contributes.

#103241

[aeschli]

Don't modify extension resources, as we consider them static and cachable.
If you want to go down the suggested path of generating svg icons, create new resources for each color variant.

That said, you really want all colors to be themable, and the colors should come from a theme,
The right approach is that the TreeItem API also takes a iconColor.
It would be used if you use iconPath with a ThemeIcon. Currently ThemeIcon can only reference to one of our codicons (icon reference). In the future we also want to allow extensions to contribute ThemeIcon as well.

[aeschli]

Assigning to @sandy081 as this is a TreeItem API request.

[alexr00]

Re-assigning to me, since I took over tree api over a year ago.

[mmohdnowfal]

iconColor

how this is done? Any examples

[alexr00]

API proposal:

vscode/src/vs/vscode.proposed.d.ts

Lines 2272 to 2278 in 10c7db8

	export class ThemeIcon2 extends ThemeIcon {
	/**
	* Returns a new `ThemeIcon` that will use the specified `ThemeColor`
	* @param color The `ThemeColor` to use for the icon.
	*/
	with(color: ThemeColor): ThemeIcon2;
	}

[alexr00]

@warrenbuckley there is now proposed API for coloring ThemeIcon(only works in the tree view for now). If you can try it out and let us know what you think in this issue that would help us move forward with the API proposal.

[warrenbuckley]

I will try and get round to this shortly & let you know how it went @alexr00 😄

[warrenbuckley]

@alexr00 I can confirm this as working in the insiders build with the proposed API

Here's my example if anyone needs a reference/usage who may stumble across this issue in the future

import * as vscode from 'vscode';

export class ControlsTreeProvider implements vscode.TreeDataProvider<ControlsTreeItem> {


    onDidChangeTreeData?: vscode.Event<void | ControlsTreeItem | null | undefined> | undefined;

    getTreeItem(element: ControlsTreeItem): vscode.TreeItem | Thenable<vscode.TreeItem> {
        return element;
    }

    getChildren(element?: ControlsTreeItem | undefined): vscode.ProviderResult<ControlsTreeItem[]> {
        if(element === undefined){
            const items = new Array<ControlsTreeItem>();

            const startIconThemeColor = new vscode.ThemeColor("debugIcon.startForeground");
            
            items.push(
                {
                    label: 'Start Website',
                    iconPath: new vscode.ThemeIcon2("play").with(startIconThemeColor),
                    collapsibleState: vscode.TreeItemCollapsibleState.None,
                    command: {
                        title: 'Start Website',
                        command: "extension.iis-express.start"
                    }
                },
                {
                    label: 'Restart Website',
                    iconPath: new vscode.ThemeIcon("refresh"),
                    collapsibleState: vscode.TreeItemCollapsibleState.None,
                    command: {
                        title: 'Restart Website',
                        command: "extension.iis-express.restart"
                    }
                },
                {
                    label: 'Stop Website',
                    iconPath: new vscode.ThemeIcon("stop"),
                    collapsibleState: vscode.TreeItemCollapsibleState.None,
                    command: {
                        title: 'Stop Website',
                        command: "extension.iis-express.stop"
                    }
                },
                {
                    label: 'Become a supporter',
                    iconPath: new vscode.ThemeIcon("heart"),
                    collapsibleState: vscode.TreeItemCollapsibleState.None,
                    command: {
                        title: 'Become a supporter',
                        command: 'extension.iis-express.supporter'
                    }
                });

            return items;
        }

        return Promise.resolve([]);
    }
}

export class ControlsTreeItem extends vscode.TreeItem {}

[warrenbuckley]

@alexr00 do we know when this is due for release in stable please?
So I can plan when I can roll this minor release update from my extension.

[alexr00]

We try to take our time with API since once we have API we have to support it forever. I will try to finalize this API in October, but no promises.

[alexr00]

Latest proposal:

vscode/src/vs/vscode.proposed.d.ts

Lines 2170 to 2184 in b775976

	//#region https://github.com/microsoft/vscode/issues/103120 @alexr00
	export class ThemeIcon2 extends ThemeIcon {
	/**
	* The id of the icon. The available icons are listed in https://microsoft.github.io/vscode-codicons/dist/codicon.html.
	*/
	public readonly id: string;
	/**
	* Creates a reference to a theme icon.
	* @param id id of the icon. The available icons are listed in https://microsoft.github.io/vscode-codicons/dist/codicon.html.
	* @param color optional `ThemeColor` for the icon.
	*/
	constructor(id: string, color?: ThemeColor);
	}

[warrenbuckley]

@alexr00 is this proposal available immediately in VSCode Insiders or do I need to wait until tomorrow to try the updated API proposal of passing the color reference into the constructor

[alexr00]

@warrenbuckley It will be available in the next insiders (whatever version comes after f943318)