Intent API - Display

PLEASE NOTE: THE USAGE OF THIS FEATURE IS RESTRICTED AND ONLY AVAILABLE AS CLOSED BETA THROUGH OUR EARLY ACCESS PROGRAM. PLEASE FILL OUT THE REGISTRATION FORM TO APPLY.

The ProGlove Display Intent API is a fast and easy way to integrate ProGlove Display devices into your application. Broadcast Intents are sent to the ProGlove Connect App, which in turn connects (via BLE) to the display device. This setup allows easy handling, establishing and holding of the BLE connection through the ProGlove Connect App while your application can focus on the actual (business) process.

Sent out from the ProGlove Connect App

Receiving Display Connection State

Once the pairing process is started, the ProGlove Connect App will send out the current connection State of the display device

  • Action: com.proglove.api.DISPLAY_STATE
  • Extra: String in com.proglove.api.extra.DISPLAY_STATE

Example code to get scanner state events (in Kotlin):

  1. Implement a broadcast receiver (in this case the class is called MessageHandler):
    class MessageHandler : BroadcastReceiver() {
        override fun onReceive(context: Context?, intent: Intent?) {
            if (intent != null && intent.action == "com.proglove.api.DISPLAY_STATE") {
                intent.getStringExtra("com.proglove.api.extra.DISPLAY_STATE")
            }
        }
    }
  1. Define an IntentFilter for the desired actions:
    val messageHandler: MessageHandler = MessageHandler()
    val filter = IntentFilter()
    filter.addAction("com.proglove.api.DISPLAY_STATE")
    filter.addCategory(Intent.CATEGORY_DEFAULT)
  1. Finally register the broadcast receiver instance with a context. The usual place for this call would be in the onCreate method of a Service or an Activity class:
    context.registerReceiver(messageHandler, filter)

Do not forget to unregister the receiver again, for example in onDestroy:

    context.unregisterReceiver(messageHandler)

The passed Status String can be one of the following:

  • "CONNECTED": The display is connected and the user can start to set screens and receive button press events.
  • "DISCONNECTED": No display is connected.
  • "CONNECTING": In the process of establishing a display BLE Connection.
  • "ERROR": Something went wrong trying to establish the display connection or the BLE search in general. Consult the ProGlove Connect App.
  • "RECONNECTING": Lost connection to a previously connected display trying to re-establish the connection.
  • "SEARCHING": Searching for a display.

The examples above can be unified to one class handling all events by adding the other Action to the IntentFilter object. Then onReceive gets called for both kinds of events.

Input to the ProGlove Connect App

Disconnecting a display device

To disconnect a connected display, send a Broadcast Intent to:

  • Action: com.proglove.api.DISPLAY_DISCONNECT
  • No Extras

Example code:

val intent = Intent()
intent.setAction("com.proglove.api.DISPLAY_DISCONNECT")
sendBroadcast(intent)

NOTICE: This will disconnect the device. So you might receive a display and a scanner disconnected event.

Setting a screen

We distinguish two types of screens (templates): Notification screens and permanent screens. Notifications, in contrast to permanent screens are only visible for a set amount of time. After the time passed, an automatic transition to the previous screen will take place. The display of a notification can only be interrupted and finished early by a new screen setting command, both notification and permanent.

setScreen commands, like all commands that trigger an action on MARK, will by default be queued in ProGlove Connect. By providing a special extra in com.proglove.api.extra.REPLACE_QUEUE, this behaviour can be changed to replace the queue with this new command. For more Information about the queueing behaviour click here

To do this via Intents you will need to send a Broadcast Intent of the following structure:

  • Action: com.proglove.api.SET_DISPLAY_SCREEN
  • Extras:
    • String in com.proglove.api.extra.TEMPLATE_ID
    • String in com.proglove.api.extra.DATA
    • optional: String in com.proglove.api.extra.SEPARATOR
    • optional: String in com.proglove.api.extra.REFRESH_TYPE
    • optional: Int >= 0 in com.proglove.api.extra.DURATION

Example code:

    val intent = Intent()
    intent.setAction("com.proglove.api.SET_DISPLAY_SCREEN")
    intent.putExtra("com.proglove.api.extra.TEMPLATE_ID", "PG3")
    intent.putExtra("com.proglove.api.extra.DATA", "1|Bezeichnung|Kopfairbag|2|Fahrzeug-Typ|Hatchback|3|Teilenummer|K867 86 027 H3")
    intent.putExtra("com.proglove.api.extra.SEPARATOR", "|")
    intent.putExtra("com.proglove.api.extra.REFRESH_TYPE", "FULL_REFRESH")
    intent.putExtra("com.proglove.api.extra.DURATION", 5000)
    sendBroadcast(intent)

Explanation of Extras:

1. TEMPLATE_ID: String

  • This string describes which template to use, in order to show information on the display device.
  • Each template has a number of fields into which you can insert your data. Fields usually have a header and a content.
  • More information about Templates can be found in the documentation provided when receiving the Early Access License Key

2. DATA: String

  • This is the central entry point for your information to enter our services.
  • Here you will provide a String that encodes the information you want to display
  • Each template field has an id, a header and a content:
    • The id is a positive integer, which identifies the template field. We number each field in normal reading direction, starting with 1 on the top-left
    • The content is the string, that will be displayed inside the field.
    • The header is the string, that will be displayed on the top of the field. It should give context to what is shown in this field.
  • The data string is constructed by appending template field descriptions with a ';' character between them. Each template field description looks like this: "id;header;content"
    • full example: "1;header1;content1;2;header2;content2"

3. SEPARATOR: String

  • As you might have noticed in section 2 we use ';' in between the Id, Header and Content, but in the above example we used the '|' character.
  • If for some reason the default separator character ';' is not an option for you, because you want to display that character on screen, then use a different separator, and send it as a string extra in the separator field.
  • The ProGlove Connect App will split the DATA string along the ';' character by default, but uses the SEPARATOR if one is provided.

4. REFRESH_TYPE: String - defaults to DEFAULT, if not provided or not parsable

  • This parameter controls the display device's strategy of screen refresh. The display uses an E-Ink display, which has two modes of refreshing. Full and partial refreshes.
  • Possible Values:
    • FULL_REFRESH: A full refresh takes longer, because it turns the screen blank before setting the new one. Use this, if your current process step is not time critical and you want to have control over the visibility of artifacts (for example you want to control the refresh type everytime)
    • PARTIAL_REFRESH: A partial refresh is quicker, but there may remain some artifacts from the previous screen. Use this, if your current process step is time critical and visibility of artifacts is not an issue.
    • DEFAULT: The default strategy defined by ProGlove. Here both full or partial refreshes may appear. Use this, if have no preference over one or the other.
    • Note: The refresh type parameter will be ignored, if you set a notification screen. These will always use PARTIAL_REFRESH.**

5. DURATION: Int >= 0 - defaults to 0, if not provided or not parsable

  • With this parameter you can specify weather you want to set the screen as a notification (>0) or as a permanent screen (=0 or not provided)
  • It represents the amount of time in milliseconds this notification should be displayed.
  • A value of 0 represents a permanent screen. A value <0 will result in a permanent screen as well.

Additionally to the above mentioned structure you can also provide a Boolean valued extra in com.proglove.api.extra.REPLACE_QUEUE, which if set to true will make this command cancel all the currently waiting commands and execute this command as soon as possible. More information can be found here

After sending a SET_DISPLAY_SCREEN intent, the ProGlove Connect App will send out a status report about how it went. If you listen for this broadcast intent, you will be able to find out when your call succeeded or whether it produced an error.

The broadcast will have the following structure:

  • Action: com.proglove.api.SET_DISPLAY_SCREEN_RESULT
  • Extra:
    • Boolean in com.proglove.api.extra.DISPLAY_SET_SCREEN_SUCCESS
    • optional (if success is false): String in com.proglove.api.extra.DISPLAY_SET_SCREEN_ERROR

Example code:

  1. Implement a broadcast receiver (in this case the class is called MessageHandler):
class MessageHandler : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        if (intent != null && intent.action == "com.proglove.api.SET_DISPLAY_SCREEN_RESULT") {
            val setScreenSucceeded = intent.getBooleanExtra("com.proglove.api.extra.DISPLAY_SET_SCREEN_SUCCESS")
            if(setScreenSucceeded) {
                Toast.makeText(context, "Did set screen successfully", Toast.LENGTH_LONG).show()
            } else {
                val errorMessage = intent.getStringExtra("com.proglove.api.extra.DISPLAY_SET_SCREEN_ERROR")
                Toast.makeText(context, "Did receive error during screen setting: $errorMessage", Toast.LENGTH_LONG).show()
            }
        }
    }
}
  1. Define an IntentFilter for the desired actions:
    val messageHandler: MessageHandler = MessageHandler()
    val filter = IntentFilter()
    filter.addAction("com.proglove.api.SET_DISPLAY_SCREEN_RESULT")
    filter.addCategory(Intent.CATEGORY_DEFAULT)
  1. Finally register the broadcast receiver instance with a context. The usual place for this call would be in the onCreate method of a Service or an Activity class:
    context.registerReceiver(messageHandler, filter)

Do not forget to unregister the receiver again, for example in onDestroy:

    context.unregisterReceiver(messageHandler)

Picking a display orientation

ProGlove Connect comes with a dialog to pick the orientation of a display device.

To show this dialog send the following intent:

val intent = Intent()

intent.component = ComponentName(
        "de.proglove.connect",
        "de.proglove.coreui.activities.DisplayOrientationActivity"
)
context.startActivity(intent)

Note: In case Android's pinned application mode is used, context must be the pinned activity. Requires ProGlove Connect version 1.2.0 or newer.