Test for #77131

• Mac @deepak1556
• Linux @Tyriar
• Windows @alexr00

Complexity: 5

Overview

Custom editors let extension contribute a webview that is tied to a resource. For example, we now use a custom editor to preview images in VS Code. The custom editor replace's VS Codes default text/binary editor (although users can switch back to the default editor if they wish)

The current discussion around custom editors (#77131) is long and confusing so I've tried to distill down the important points here. For this iteration, we only want to test readonly custom editors and the UX for them. The save functionality that has been proposed will likely be significantly changed and is not actually functional at the moment

Contributing a custom editor

Use the new built-in imagePreview extension as a starting point for testing custom editors. Here are the important parts of the API highlight the important points of it below:

The contribution point

  "activationEvents": [
    "onWebviewEditor:imagePreview.previewEditor"
  ],
"contributes": {
    "webviewEditors": [
      {
        "viewType": "imagePreview.previewEditor",
        "displayName": "Image Preview",
        "discretion": "default",
        "selector": [
          {
            "filenamePattern": "*.{jpg,jpe,jpeg,png,bmp,gif,ico,tga,tif,tiff,webp}",
            "mime": "image/*"
          }
        ]
      }
    ]
  },

This tells VS Code that a custom editor exists:

• displayName — Unique Identifier for the editor. This is also used in the extension code later. Note this identifier is also used for in the activation event.
• displayName — Human readable name of the custom editor
• discretion — Determines if the custom editor should be enabled by default
• selector— Specifies when the editor should be enabled.
  • filenamePattern — A glob for which file names the editor should be enabled for
  • mime — A glob for which mime types the editor is enabled (this is used if you open a data uri resource, such as from git history)

The code

In our extension, we then use the new registerWebviewEditorProvider proposed api to bind id to a webview editor resolver. These resolvers take a resource and a webview editor. The resolver is invoked whenever a resource that matches the selector for the custom editor is opened

import * as vscode from 'vscode';
import { Preview } from './preview';

export function activate(context: vscode.ExtensionContext) {
	context.subscriptions.push(vscode.window.registerWebviewEditorProvider(
		'imagePreview.previewEditor',
		{
			async resolveWebviewEditor(resource: vscode.Uri, editor: vscode.WebviewEditor): Promise<void> {
                          // Take ownership of webview and create its content
                         editor.webview.html = `...`;
			}
		}));
}

That's pretty much it. Once you have a webviewEditor, you can use it just like an existing webview panel. See the cat coding sample for an example of that

Other noteworthy custom editor related UX

Reopen with command

Use this new command to switch between available editors. This should close the existing editor and reopen it with the newly selected editor.

The workbench.experimental.editorAssociations setting

This setting lets users control which custom editor is used for a given resource. It consists of a list of file selectors and which editor should be opened when a resource matches the selector

    "workbench.experimental.editorAssociations": [
        {
            "filenamePattern": "*.png",
            "viewType": "imagePreview.previewEditor",
        }
    ]

Note that default is also a valid viewType and can be used to force VS Code to open its normal text/binary editor instead of any default custom editor

    "workbench.experimental.editorAssociations": [
        {
            "filenamePattern": "*.png",
            "viewType": "imagePreview.previewEditor",
        }
    ]

Testing

For this plan item, take an exploratory approach to exploring the current custom editor functionality as laid out above. Here are some areas to focus on:

• API

  • Can you write a simple custom editor
  • Does the contribution point make sense (does your editor get activated when you would expect)

• Basic UX

  • Is your custom editor enabled used by default when you expect it to be
  • Does the Reopen with command work as you expect
  • Try the workbench.experimental.editorAssociations setting
  • Try contributing a custom editor for a binary file format
  • Try contributing a custom editor for a text file format

• Multiple extensions

  • What happens when there are multiple custom editors for a resource?
  • Does the discretion setting do what you would expect?

• Restoration.

  • Are custom editors properly restored on window reload?

• Test custom editors in diff views

  • Specifically in the git diff view