Display API: Connection State & General Functions

Kiosk Pro's External Screen API allows you to display local and/or remote content on an external display connected to your iOS device wirelessly via AirPlay or through Apple's Digital AV Adapter (which creates a wired connection betweeen an HDMI port on the external display and your device's 30-pin or Lightning port).

Unlike the native video mirroring available for iPad2 and above, which creates a mirrored image of the device on the external display and shows the same content on each, this API allows you to send content to the display in full-screen while using the iPad as a controller to display an interactive menu view.

The External Screen API supports a wide variety of content formats, including video, image files, .pdf, and .html pages. Direct mirroring of the iPad's screen is not currently supported in full-screen as 4:3 monitors are increasingly rare and not available in larger sizes, but it is still possible to switch back and forth between the Screen API and the iPad's native mirroring if this functionality is needed. Note that as there is no support for touch input from the external display, all navigation must be available from the iPad.

Functions

Callbacks

Requirements

  • Access JavaScript API
    • 'By Import' - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
    • 'By Injection' - only works offline, may not be available 'onload' event.
  • Screensaver
  • Connection to an External Display
    • iOS device must be connected to an external monitor, screen or projector via AirPlay or through Apple's Digital AV Adapter (which creates a wired connection betweeen an HDMI port on the external display and your device's 30-pin or Lightning port).

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 http://www.kioskproapp.com/external-screen

Download Sample Code

kp_ExternalScreen_connectToScreen

This function is used to exit standard iOS 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();

Status

Kiosk Pro will immediately call kp_ExternalScreen_connectionStateDidChange and pass the current connection state of the external display.

kp_ExternalScreen_disconnectFromScreen

This function is used to end sending full-screen content to the external display through the External Screen API and revert to standard iOS 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 standard iOS mirroring.

Format 
kp_ExternalScreen_disconnectFromScreen();

Status

Kiosk Pro will immediately call kp_ExternalScreen_connectionStateDidChange and pass the current connection state of the external display.

kp_ExternalScreen_requestStateOfConnection

This function requests current connection state of the external display.

Format 
kp_ExternalScreen_requestStateOfConnection();

Status

Kiosk Pro will immediately call kp_ExternalScreen_connectionStateDidChange and pass the current connection state of the external display.

kp_ExternalScreen_requestProperties

This function requests the following properties associated with the external display:

  • Array of available screen modes. Each mode is 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 = callback name as a string.
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 = the associative array of available screen modes. Each screen mode has the following structure:
    • width = the screen width, measured in pixels.
    • height = the screen height, measured in pixels.
    • pixelAspectRatio = 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 = index of element in the 'modes' array, indicating the current screen mode which is associated with the external display. As an array, this begins with '0' (rather than '1') representing the first returned screen mode and so on.
  • prefMode = index of element in the 'modes' array, indicating the screen mode which is returned by the external display as its 'preferred' display mode.
  • overscanCompensation = integer value which indicates 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}

kp_ExternalScreen_setScreenMode

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.

Format 
kp_ExternalScreen_setScreenMode(width, height, сallback);
Parameters
  • width = the desired screen width, measured in pixels.
  • height = the desired screen height, measured in pixels.
  • callback = callback name as a string.
Callback Format 
callback(isNewModeWasSet);
Callback Return Values
  • isNewModeWasSet = integer variable indicating the success of setting a new screen mode. Possible values are:
    • 1 = the new mode was set
    • otherwise = mode was not set.

kp_ExternalScreen_setOverscanCompensationMode

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 value which indicates 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.
  • callback = callback name as a string.
Callback Format 
callback(isNewModeWasSet);
Callback Return Values
  • isNewModeWasSet = integer variable indicating the success of setting a new overscan compensation mode. Possible values are:
    • 1 = the new mode was set
    • otherwise = mode was not set.

kp_ExternalScreen_connectionStateDidChange

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 = an integer value 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.

Still stuck? How can we help? How can we help?