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
- External Monitor Mode = Interactive or Standard Mirroring
- 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
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 |
|
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 |
|
Callback Format | callback(isNewModeWasSet); |
Callback Return Values |
|
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 |
|
Callback Format | callback(isNewModeWasSet); |
Callback Return Values |
|
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 |
|