API: Connect & Configure External Screen

Connect to and configure display options for an external screen or projector.

Requirements

Kiosk Pro Enterprise

Integration of our JavaScript API into your webpage

Sample code to run within the app and download for integration into your own project is available here.
Best practices for working with the JavaScript API are available here.

App Settings

Content > JavaScript API > Access JavaScript API = By Import
Screensaver > External Monitor Mode = Interactive or Standard Mirroring

Physical Hardware

External screen or projector connected via HDMI to the iPad through a Digital AV Adapter or hub or to a connected Apple TV for wireless Airplay.

Connect To Screen

This function is used to exit native screen mirroring and begin sending full-screen content to the external display through the External Screen API. If the external display is not linked to the device (either by AirPlay or AV Adapter) or if the external screen is already connected through the External Screen API, then this function does nothing. If the external display is linked to the device and is using native mirroring, then this function initiates a connection with the external display, displaying a plain, black background on the external display until the first request to display content is sent.

Format	kp_ExternalScreen_connectToScreen();
Triggers	Kiosk Pro will immediately trigger kp_ExternalScreen_connectionStateDidChange and pass the current connection state of the external display.

Disconnect From Screen

This function is used to end sending full-screen content to the external display through the External Screen API and revert to native screen mirroring. If the external display is not linked to the device (either by AirPlay or AV Adapter) or if the external screen is already mirroring the iPad, then this function does nothing. If the external display is linked to the device and is connected through the External Screen API, then this function returns the external display to native screen mirroring.

Format	kp_ExternalScreen_disconnectFromScreen();
Triggers	Kiosk Pro will immediately trigger kp_ExternalScreen_connectionStateDidChange and pass the current connection state of the external display.

Check Connection State

This function triggers a check of the current connection state of the external display.

Format	kp_ExternalScreen_requestStateOfConnection();
Triggers	Kiosk Pro will immediately trigger kp_ExternalScreen_connectionStateDidChange and pass the current connection state of the external display.

Check Screen Properties

This function triggers a callback returning the following properties associated with the external display:

Array of available screen modes with each mode shown as a set of screen pixel dimensions and pixel aspect ratio
Current screen mode index (in array of available screen modes).
Preferred screen mode index (in array of available screen modes).
Overscan compensation mode value.

Format	kp_ExternalScreen_requestProperties(callback);
Parameters	callback - [string] the name of the callback to be triggered after the function has been executed
Callback Format	callback(screenProperties);
Callback Return Values	screenProperties - returned as an associative array: {'modes':Array of associative arrays:{'width':value, 'height':value, 'pixelAspectRatio':value} , 'curMode':index, 'prefMode':index, 'overscanCompensation':value} modes - an associative array of available screen modes. Each screen mode has the following structure: width - [string] the screen width, measured in pixels height - [string] the screen height, measured in pixels pixelAspectRatio - [string] the aspect ratio is defined as x/y, where x is the width of the pixel and y is the height of the pixel. A pixel aspect ratio of '1.00' describes a standard square pixel; certain digital displays may use other pixel aspect ratios curMode - [integer] indicating the index of element in the 'modes' array of the current screen mode in use. As an array, this begins with '0' (rather than '1') representing the first returned screen mode and so on prefMode - [integer] indicating the index of element in the 'modes' array of the screen mode which is returned by the external display as its 'preferred' display mode overscanCompensation - [integer] indicating current overscan compensation mode. This value determines how the iPad frames the display on the external display, ensuring that your content is displayed in full-screen. Note that different displays may require different settings and some experimentation to determine the optimal setting for the type of display being used. Descriptions below are directly from Apple's Screen API documentation: 0 - "the final composited framebuffer for the screen is scaled so that all pixels lie in the area visible on the display." 1 - "the screen bounds are reduced in size so that all pixels in the framebuffer are visible on the display." 2 - "the application frame is reduced in size to compensate for overscan. Content drawn outside the application frame may be clipped." 3 - (default) a value which is undocumented in Apple's Screen API's, but which displayed content in full-screen on all monitors tested during development
Example	{'modes':new Array({'width':640.00, 'height':480.00, 'pixelAspectRatio':1.00}, {'width':800.00, 'height':600.00, 'pixelAspectRatio':1.00}, {'width':1024.00, 'height':768.00, 'pixelAspectRatio':1.00}), 'curMode':0, 'prefMode':2, 'overscanCompensation':3}

Set Screen Mode

This function sets a new screen mode for the external display. The new screen mode is specified as a pair, declaring the desired width and height. If the external display is not linked or does not support the declared resolution, this method will fail. As such, it is generally recommended to check the available resolution modes through kp_ExternalScreen_requestProperties(); prior to setting a new screen mode.

Format	kp_ExternalScreen_setScreenMode(width, height, сallback);
Parameters	width - [string] the desired screen width, measured in pixels height - [string] the desired screen height, measured in pixels callback - [string] the name of the callback to be triggered after the function has been executed
Callback Format	callback(newModeWasSet);
Callback Return Values	newModeWasSet - [boolean integer] indicating the success of setting a new screen mode. Possible values are: 1 - the new mode was set 0 - mode was not set

Set Overscan Compensation Mode

This function sets a new overscan compensation mode for the external display. If no external display is connected or the display does not support the declared resolution, then this method will fail.

Format	kp_ExternalScreen_setOverscanCompensationMode(mode, сallback);
Parameters	mode - [integer] indicating the new overscan compensation mode. This value determines how the iPad frames the display on the external display, ensuring that your content is displayed in full-screen. Note that different displays may require different settings and some experimentation may be required to determine the optimal setting for the type of display being used. Descriptions below are directly from Apple's Screen API documentation: 0 - "the final composited framebuffer for the screen is scaled so that all pixels lie in the area visible on the display." 1 - "the screen bounds are reduced in size so that all pixels in the framebuffer are visible on the display." 2 - "the application frame is reduced in size to compensate for overscan. Content drawn outside the application frame may be clipped." 3 - (default) a value which is undocumented in Apple's Screen APIs, but which displayed content in full-screen on all monitors tested during development callback - [string] the name of the callback to be triggered after the function has been executed
Callback Format	callback(newModeWasSet);
Callback Return Values	newModeWasSet - [boolean integer] indicating the success of setting a new overscan compensation mode. Possible values are: 1 - the new mode was set 0 - mode was not set

Notifications via API Callbacks

When Connection State Changes

When Connection State Changes

This callback is triggered each time the external display is connected or disconnected and also as result of calling kp_ExternalScreen_requestStateOfConnection.

Format	kp_ExternalScreen_connectionStateDidChange(stateOfConnection);
Return Values	stateOfConnection - [integer] indicating the state of the connection with possible values of: 0 - external screen not linked (via AirPlay or Apple Digital AV Adapter) 1 - external screen linked and in native mirroring mode 2 - external screen linked and connected via Screen API

Sample Code

This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.
To run sample code, set the app's homepage to kioskgroup.com/external-screen-api
To download a .zip of sample code, click here.

Change Log

Added in initial version of Enterprise. Major revision of underlying code base in version 7.3