Notes on document

Please note, this document is in an early draft form. It’s primary purpose is to discover how we will define APIs, rather than discover the detail of a specific API method. In other words, now is not the time to ask “Why doesn’t it support xyz?”, however, it is a good time to ask “If we were to add xyz, where would it live?”

API Design Principles

Our general principles are as follows:

Prior Art Example

Minuet ScreenSnippet API used in Symphony

SSF ScreenSnippet API

The ScreenSnippet API is used to capture a snippet of their desktop (unconstrained by the host application window) and highlight portions of this snippet so it can then be consumed by the host application.  This functionality is similar to the Windows Screen Snippet tool when used in rectangle capture mode.  This lets a user captures portions of the Windows Desktop, highlight aspects of the image and then save this image for sharing.

This functionality differs from the Electron BrowserWindow.capturePage API in that Electron is restricted in that it can only capture content from the host application and does not provide any annotation functionality.

The exact visual style and full functionality of a markup tool is container dependent and hence out-of-scope of this specification.

Constructor

ScreenSnippet()

Creates a new instance of the ScreenSnippet object.

Syntax

let mySnippet = new ScreenSnippet();

Note: the API should be exposed as a global namespace - working name "ssf" so:

let mySnippet = new ssf.ScreenSnippet();

Parameters

None.

Methods

capture()

Creates a new instance of the ScreenSnippet object.

Syntax

mySnippet.capture().then(function(bitmap) { ... });

Parameters

none

Returns

A Promise that resolves to an ImageBitmap object with contains the captured image and type.

Implementation Ideas:

A possible idea that has been floated is to make the ScreenSnippet tool a reusable Node Module that calls to an external executable using "child_process" that could be invoked from the container.  This external executable could then use StdOut to communicate with the container to provide the result of the snippet.

class ScreenSnippet {
	capture() {
		return new Promise((resolve, reject) => {
			const childProcess = require('child_process');
			const snippetToolInterop = childProcess.fork('...', [], {
				silent: true
			});

			let response = false;

			snippetToolInterop.on('exit', (code, signal) => {
				if (!response) {
					reject(...);
				}
			});

			snippetToolInterop.on('message', message => {
				if (!response) {
					response = true;
					snippetToolInterop.kill();
					if (message.error) {
						reject(...);
					} else {
						resolve(message.bitmap);
					}
				}
			});
		});
	}
}


module.exports = ScreenSnippet;

Discussion points:

• (From Gareth) I've assumed we have a preference for promises vs callbacks.  This seems inline with modern HTML5 standards which are deprecating callbacks. 

• (From Gareth) We should discuss the return object for the capture method.  I've currently followed the Minuet approach.