Set screens

There are two types of screens (templates): notification screens and permanent screens.

Notifications are only visible for a set period of time after which they revert to the previous screen. The notification display can only be interrupted and finished early by a new screen setting command, either a notification or a permanent message.

setScreen commands, like all commands that trigger an action on a MARK, are queued in Insight Mobile by default.

To set a screen using the SDK you need to provide the following data:

Parameter Name	Data Type	Description
templateId	String	The ID of the selected template
templateFields	Array<PgTemplateField>	The selected fields in the given template
refreshType	RefreshType	The refresh type used for the screen update
(optional) durationMs	Int > 0	If this is provided, a notification screen will be set for this time
callback	IPgSetScreenCallback	The object which will be called back with the results

For Intent, the data is almost identical in content, but structurally different:

Action: com.proglove.api.SET_DISPLAY_SCREEN

Extra Name	Data Type	Description
`com.proglove.api.extra.TEMPLATE_ID`	String	The ID of the selected template
`com.proglove.api.extra.DATA`	String	The selected header and content data in the given template
(optional) `com.proglove.api.extra.SEPARATOR`	String	Needed to parse the DATA correctly
(optional) `com.proglove.api.extra.REFRESH_TYPE`	String	The refresh type used for this screen update
(optional) `com.proglove.api.extra.DURATION`	Int > 0	If this is provided, a notification screen will be set for this time

Parameters

templateId/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.
To learn more about templates, go to Templates.

refreshType/REFRESH_TYPE: RefreshType/String

This parameter controls the display device’s screen refresh strategy. There are two modes of refreshing. Full refreshes and partial refreshes.
Possible Values:
- RefreshType.FULL_REFRESH/“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 artifacts visibility (for example, if you want to control the refresh type every time).
- RefreshType.PARTIAL_REFRESH/“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 artifacts visibility is not an issue.
- RefreshType.DEFAULT/“DEFAULT”: The default strategy defined by ProGlove. Here, both full or partial refreshes may appear. Use this if you 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.

(optional) durationMs/DURATION: Int > 0

With this parameter you can specify whether 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) within which the notification should be displayed.
A value of 0 represents a permanent screen. A value <0 will result in a permanent screen as well.

SDK-specific parameters

TemplateFields: Array<PgTemplateField>

This is the central entry point for your information to enter our services.
Here, you will provide an array of PgTemplateField objects, that describe the contents of the given template.
Each PgTemplateField has an ID field, a Header, and a Content:
- The ID is a positive integer, which identifies the TemplateField.
- The Content is a string displayed inside the field.
- The Header is a string displayed on the top of the field. It should give context to what is shown in this field.
To learn more, see Templates.

Callback: IPgSetScreenCallback

This is the object onto which the SDK will callback onSuccess and onError. Inside these functions you will be able to handle error or success cases.
Additionally, we will log an error message, which provides a more detailed context into the error. This will be done through the logger provided through the constructor of PgManager, or the default one.

SDK-specific remarks

The convenience function PgScreenData.toComamnd() used here to wrap the PgScreenData optionally takes a PgCommandParams object, which gives additional control over how the command should be executed. For now, we only support the replaceQueue flag here, which, if set to true, cancels all commands currently in the queue and adds itself as the first element.

Intent-specific parameters

DATA: String

This is the central entry point for your information into 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 displayed inside the field.
- The Header is the string 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”

SEPARATOR: String

As shown in section 2, we use ‘;’ in between the ID, Header, and Content, but in the above example we used the ‘|’ character.
If 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 Insight Mobile app will split the DATA string along the ‘;’ character by default, but uses the SEPARATOR if one is provided.

Intent-specific remarks

Additionally, you can provide a boolean valued extra in com.proglove.api.extra.REPLACE_QUEUE, which, if set to true, will make this command cancel the currently waiting commands and execute this command as soon as possible.

To learn more, see Command queueing in Insight Mobile.

After sending a SET_DISPLAY_SCREEN intent, the Insight Mobile app will send out a status report.

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

Implement a broadcast receiver:

val broadcastReceiver = object : 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", false)
            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()
            }
        }
    }
}

Define an IntentFilter for the desired actions:

val filter = IntentFilter()
filter.addAction("com.proglove.api.SET_DISPLAY_SCREEN_RESULT")
filter.addCategory(Intent.CATEGORY_DEFAULT)

Register the broadcast receiver instance. The usual place for this call would be in the onCreate method of a Service or an Activit y class:
```
registerReceiver(broadcastReceiver, filter)
```
Do not forget to unregister the receiver again, for example in onDestroy:
```
unregisterReceiver(broadcastReceiver)
```

Example code

Example 83. SDK

val duration = 3000
val setScreenData = PgScreenData(
        "PG3",
        listOf(
                PgTemplateField(1, "Header1", "Content1"),
                PgTemplateField(2, "Part-Number", "123456789"),
                PgTemplateField(3, "Storage-hub", "PG28-AHX2C")
        ),
        RefreshType.PARTIAL_REFRESH,
        duration
)

val callback = object : IPgSetScreenCallback {
    override fun onSuccess() {
        // screen was set successfully
    }

    override fun onError(error: PgError) {
        // react to the error
        // check your logs, there will be a message that further specifies the error
        if (error.errorCode == PgError.NOT_CONNECTED_TO_DEVICE) {
            // the callbacks might come on background threads, make sure to execute this on the UI Thread
            runOnUiThread {
                Toast.makeText(this@MainActivity, "please connect the display device first", Toast.LENGTH_SHORT).show()
            }
        }
    }
}
pgManager.setScreen(
        setScreenData.toCommand(),
        callback
)
//_or_
pgManager.setNotificationScreen(
        setScreenData.toCommand(),
        callback
)

Example 84. Intent

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)

In this section:

ProGlove Documentation