Optional descriptionThe human-readable description which is rendered less prominent.
Optional detailThe human-readable detail which is rendered less prominent.
The execute handler is invoked when the run gestures in the UI are selected, e.g Run Cell, Run All, Run Selection etc. The execute handler is responsible for creating and managing execution-objects.
Readonly idThe identifier of this notebook controller.
Note that controllers are remembered by their identifier and that extensions should use stable identifiers across sessions.
Optional interruptOptional interrupt handler.
By default cell execution is canceled via tokens. Cancellation
tokens require that a controller can keep track of its execution so that it can cancel a specific execution at a later
point. Not all scenarios allow for that, eg. REPL-style controllers often work by interrupting whatever is currently
running. For those cases the interrupt handler exists - it can be thought of as the equivalent of SIGINT
or Control+C in terminals.
Note that supporting cancellation tokens is preferred and that interrupt handlers should only be used when tokens cannot be supported.
The human-readable label of this notebook controller.
Readonly notebookThe notebook type this controller is for.
Readonly onAn event that fires whenever a controller has been selected or un-selected for a notebook document.
There can be multiple controllers for a notebook and in that case a controllers needs to be selected. This is a user gesture and happens either explicitly or implicitly when interacting with a notebook for which a controller was suggested. When possible, the editor suggests a controller that is most likely to be selected.
Note that controller selection is persisted (by the controllers id) and restored as soon as a controller is re-created or as a notebook is workspace.onDidOpenNotebookDocument opened.
Readonly notebook: NotebookDocumentReadonly selected: booleanReadonly onAn event that fires when a renderer script has send a message to the controller.
Readonly editor: NotebookEditorReadonly message: unknownReadonly rendererOptional supportedAn array of language identifiers that are supported by this controller. Any language identifier from languages.getLanguages getLanguages is possible. When falsy all languages are supported.
Samples:
// support JavaScript and TypeScript
myController.supportedLanguages = ['javascript', 'typescript']
// support all languages
myController.supportedLanguages = undefined; // falsy
myController.supportedLanguages = []; // falsy
Optional supportsWhether this controller supports execution order so that the editor can render placeholders for them.
Create a cell execution task.
Note that there can only be one execution per cell at a time and that an error is thrown if a cell execution is created while another is still active.
This should be used in response to the execution handler being called or when cell execution has been started else, e.g when a cell was already executing or when cell execution was triggered from another source.
The notebook cell for which to create the execution.
A notebook cell execution.
Send a message to the renderer of notebook editors.
Note that only editors showing documents that are bound to this controller are receiving the message.
The message to send.
Optional editor: NotebookEditorA specific editor to send the message to. When undefined all applicable editors are receiving the message.
A promise that resolves to a boolean indicating if the message has been send or not.
A controller can set affinities for specific notebook documents. This allows a controller to be presented more prominent for some notebooks.
The notebook for which a priority is set.
A controller affinity
A notebook controller represents an entity that can execute notebook cells. This is often referred to as a kernel.
There can be multiple controllers and the editor will let users choose which controller to use for a certain notebook. The
notebookType-property defines for what kind of notebooks a controller is for and theupdateNotebookAffinity-function allows controllers to set a preference for specific notebook documents. When a controller has been selected its onDidChangeSelectedNotebooks-event fires.When a cell is being run the editor will invoke the
executeHandlerand a controller is expected to create and finalize a notebook cell execution. However, controllers are also free to create executions by themselves.