ACtl.getClipboard

Gets the clipboard content in various formats or tells the type of content the clipboard contains.

If no argument is passed, the clipboard content is retrieved. ACtl.getClipboard() Returns Type: Promise Returns immediately. The Promise will resolve with the clipboard content. The resolved type depends on the type of content in the clipboard.

If clipboard contains...	The resolved value will be...
Plain text or Rich Text Format	A string of plain text.
Hypertext (HTML)	A DocumentFragment object.
Files	An Array of file system paths.
Image	An HTMLCanvasElement.
Anything else	An empty string.

If the string 'format' is passed as the only argument, the function tells what type of content there is in the clipboard. ACtl.getClipboard('format') Returns Type: Promise Resolves to: string Returns immediately. The Promise will resolve with a string representing the type of content in the clipboard.

If clipboard contains...	The resolved string will be...
Plain text or Rich Text Format	'text'
Hypertext (HTML)	'html'
Files	'files'
Image	'image'
Anything else	'unknown'

If the string 'text' is passed as the only argument, the clipboard content is retrieved as plain text. ACtl.getClipboard('text') Returns Type: Promise Resolves to: string Returns immediately. The Promise will resolve with the clipboard content converted to plain text. Any rich formatting or hypertext formatting is removed.
If the content cannot be converted to text, an empty string is returned. If anything else is passed as argument, the function will interpret that as an image format, in which case the clipboard is expected to contain image data. ACtl.getClipboard(imageFormat[,returnType]) imageFormat Type: string How to encode the image data in the clipboard. It can be any of 'png', 'jpg' or 'webp'.

Don't confuse "encode" with "decode". Clipboard images are not encoded in any format, they are raw pixels. This argument is for getting the image data in the desired file format (i.e. for "encoding"). returnType Type: string Default: 'binary' How to return the encoded image data:

'binary'	Return as a binary string
'dataUri'	Return as a data URI string
'objectUrl'	Return as a object URL string
'base64'	Return as a Base64 string
'blob'	Return as a Blob object
'image'	Return as a HTMLImageElement object

Returns Type: Promise Resolves to: string | Object Returns immediately. The Promise will resolve with the image data encoded as imageFormat. The binary data will be given as specified by returnType.
If the clipboard doesn't contain image data, an empty string is returned. Throws Type: string Error description if imageFormat is not a valid format or if returnType is not a valid return type.

Examples

Take the image in the clipboard and save it to a PNG file.


	//Get the clipboard image as a PNG-encoded binary string
	let pngData = await ACtl.getClipboard('png') ;
	//Save the binary string to a PNG file as is
	ACtl.saveFile('<desktop>/new-image.png', pngData) ;

Read the file that was copied to the clipboard.


	//Get the current clipboard format
	let clipFormat = await ACtl.getClipboard('format') ;
	//If there are no files in the clipboard
	if( clipFormat != 'files' )
		//Finish the script
		return alert("There are no files in the clipboard.") ;
	//Else, get the first file in the clipboard
	let [filePath] = await ACtl.getClipboard() ;
	//Read the file's content as text
	let fileContent = await ACtl.getFile(filePath) ;
	//Show off what we've got
	alert('The first 50 characters in the file are:\n' + fileContent.slice(0,50) );

Take the image in the clipboard and insert it into a webpage.


	//Get the clipboard image as an <img> element
	let imageElem = await ACtl.getClipboard('jpg', 'image') ;
	//Add some CSS styles to the image
	imageElem.style.cssText = 'position: fixed; top: 10px; left: 10px' ;
	//Insert the image into the page the script is running in
	document.body.appendChild( imageElem ) ;

Get the hypertext in the clipboard, count the number of links in it and find out which page it was copied from.


	//Get the clipboard content
	let htmlFragment = await ACtl.getClipboard() ;
	//If the content is a DocumentFragment
	if( htmlFragment instanceof DocumentFragment ){
		//Count the number of links
		let linkCount = htmlFragment.querySelectorAll('a[href]').length ;
		//Show the link count, the URL it was copied from, etc.
		alert(`
			The hypertext contains ${linkCount} links.
			It was copied from:\n ${htmlFragment.sourceURL} \n
			The unformatted text is:\n ${htmlFragment.textContent} \n
			And the full HTML code is:\n ${htmlFragment.innerHTML}
		`) ;
	}else
		alert("There's no hypertext in the clipboard.") ;

Notice the use of the properties .sourceURL and .innerHTML above. These are special properties of the DocumentFragment object returned only by ACtl.getClipboard. Scripting API Script Isolation Asynchronicity Backgrnd Scripts GUI vs API ACtl.include ACtl.import ACtl.getFile ACtl.saveFile ACtl.saveURL ACtl.openURL ACtl.closeTab ACtl.runInTab ACtl.runInFrames ACtl.runInPageCtx ACtl.getTabInfo ACtl.getTabIds ACtl.TAB_ID ACtl.setTabState ACtl.captureTab ACtl.execAction ACtl.runCommand ACtl.getClipboard ACtl.setClipboard ACtl.expand ACtl.switchState ACtl.var ACtl.pubVar ACtl.on ACtl.off ACtl.sleep ACtl.STOP_CHAIN ACtl.STOP_FULL_SEQ