SDK API - Display

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

The ProGlove SDK API enables an easy integration of display devices with other Apps.

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

Introduction

The ProGlove Display SDK is a fast and easy way to integrate display devices into your application. The SDK works by connecting to the ProGlove Connect App, which in turn connects (via BLE) to the display device.

This setup allows handling, establishing and holding of the BLE connection to the device in a central, easy to update place (the ProGlove Connect App) - while your application can focus on the actual (business) process.

Display Device State

You will want to be informed about connection state changes of the display device. To get this, call the pgManager.subscribeToDisplayEvents() function and implement the IDisplayOutput interface. For example, in the same onCreate of our sample app we subscribe to the display info. And we unsubscribe in the onDestroy function.
(Code in Kotlin)

override fun onCreate(savedInstanceState: Bundle?) {

     //...

     pgManager.subscribeToDisplayEvents(this)

     //...
}

override fun onDestroy() {
     super.onDestroy()
     pgManager.unsubscribeFromDisplayEvents(this)
     //...
}

To do this, our Activity needs to implement the IDisplayOutput interface:

//
// -- IDisplayOutput --
//
override fun onDisplayConnected() {
        // let the user know that the display device is connected
}

override fun onDisplayDisconnected() {
     // Inform the user that the display has been disconnected
}

As you can see above, the IDisplayOutput Interface will be called whenever a display device connects or disconnects.

You can also query the PgManager methods.

Disconnecting a Display Device

To disconnect from a display device, call the PgManager.disconnectDisplay() method.

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

Setting Screens

To display screens on the device use the pgManager.setScreen() function. It takes a PgScreenData object, which has parameters on its own, wrapped in a PgCommand and an IPgSetScreenCallback Object as parameters.

Templated: 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.

TemplateFields: Array

  • This is the central entry point for your information to enter our services.
  • Here you will provide an array of PgTemplateField objects, which describe the contents of the given template.
  • Each PgTemplateField has a field for an Id, a Header and a Content:
    • The Id is a positive integer, which identifies the TemplateField.
    • 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.
  • More information about Templates can be found in the documentation provided when receiving the Early Access License Key.

refreshType: RefreshType - defaults to RefreshType.DEFAULT

  • This parameter controls the display device's strategy of screen refresh. There are two modes of refreshing. Full refreshes and partial refreshes.
  • Possible Values:
    • RefreshType.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)
    • RefreshType.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.
    • RefreshType.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.

(optional) durationMs: Int > 0

  • This parameter is only used if setting a notification screen.
  • It represents the amount of time in milliseconds this notification should be displayed.

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 more detailed context into the error. This will be done through the logger provided through the constructor of PgManager, or the default one.

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 the commands currently in the queue and adds itself as the first element. More information can be found here

Example code:

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
)

Updating/Versioning

This is currently a test version. We do not expect this version to work longer than 30 days. It will not work in production and will not be supported for longer than that. Future iterations of this SDK may include breaking changes.

Picking a display orientation

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

To show this dialog use the following sample code:

val error = pgManager.showPickDisplayOrientationDialog(context)
if (error != null) {
    Toast.makeText(context, error.toString(), Toast.LENGTH_SHORT).show()
}

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.