ACtl.on

The purpose of this function is twofold:

1. It adds an event listener function for one or more event types

2. It waits until the first time an event happens

Use ACtl.off to remove event listeners.

ACtl.on(eventTypes[,tabSpec][,listener]) eventTypes Type: string One or more event types to listen for, separated by a space character. Valid event types are:

tabOpen	A tab is opened
tabClose	A tab is closed
tabActivate	A tab becomes the active one in its window
tabDeactivate	A tab becomes inactive in its window
tabFocus	A tab gains the system focus
tabUnfocus	A tab loses the system focus
tabLoadBegin	A tab begins loading a page
tabLoadEnd	A tab ends loading a page
tabUnload	A tab's content is unloaded
tabUrlChange	A tab's URL changes
tabAudioBegin	A tab starts playing audio
tabAudioEnd	A tab stops playing audio
winOpen	A window is opened
winClose	A window is closed
winFocus	A window is focused
winUnfocus	A window loses focus
winMinimize	A window is minimized
winUnminimize	A window is unminimized
clipboardChange	The clipboard's content changes

tabSpec Type: TabSpec Default: undefined One or more tabs on which to listen for the specified eventTypes. It can be either a tab ID, a filter object, a tab-selection name or an array combining all that. Full details at Tab Specifier.

If omitted, the event types will be listened for on all tabs. This argument can be omitted even if listener is specified.

This argument is ignored on the following event types:
clipboardChange, tabOpen, winOpen, winClose. listener Type: Function Default: undefined Function to call when any of the eventTypes occur on any of the tabs given by tabSpec.

The function is passed an Event object as only argument.

If you only need to listen for an event once, you can omit this argument and wait for the returned Promise instead (example below). Returns Type: Promise Resolves to: Object Returns immediately. The Promise will resolve the first time any of the eventTypes occur on any of the tabs given by tabSpec. The resolved value will be an Event object.

You need to await for the promise to resolve only if you omit the listener argument. Throws Type: string Error description if:

eventTypes contains an invalid event type.
tabSpec is not a valid Tab Specifier.
listener is not a function.

Event object

The Event object contains information about an individual event.

Property	Type	Description
type	string	The type of event.
tabId	number	ID of the tab on which the event occurred. For all window events, this is the ID of the active tab in the window. For the events winClose and clipboardChange, this property is not present.
clipFormat	string	The type of content in the clipboard. This property is only present if the event type is clipboardChange. This is the same value returned by`ACtl.getClipboard('format')`.

Examples

Open a new page and wait for it to finish loading.


	//Open a url in a new tab
	let [tabId] = await ACtl.openURL('http://example.com') ;
	//Wait for the tab to finish loading. No need to pass a listener function
	await ACtl.on('tabLoadEnd', tabId) ;
	//Activate the tab
	await ACtl.setTabState(tabId, 'active') ;
	alert('DONE') ;

Whenever a Youtube URL is copied to the clipboard, open it in a new tab automatically.


	//Add a listener function for clipboard changes
	ACtl.on('clipboardChange', async event =>{
		//If the clipboard contains text
		if( event.clipFormat == 'text' ){
			//Get the text from the clipboard
			let clipContent = await ACtl.getClipboard() ;
			//If the text is a Youtube URL
			if( clipContent.startsWith('https://www.youtube.com') )
				//Open the URL
				ACtl.openURL(clipContent) ;
		}
	}) ;

Switch back to one specific tab whenever that tab emits sound.


	//Get the ID of the current tab
	let tabId = await ACtl.gettabIds('#currentTab') ;
	//Listen for audio-begin events on that tab only
	ACtl.on('tabAudioBegin', tabId, ()=>{
		//Activate the tab and focus its window
		ACtl.setTabState(tabId, 'active focused') ;
	}) ;

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