Template Custom Buttons

You can easily create and update custom buttons (called Soft Buttons in SDL) using the ScreenManager. To update the UI, simply give the manager your new data and (optionally) sandwich the update between the manager's beginTransaction() and commit() methods.

Soft Button Fields

ScreenManager Parameter Name	Description
softButtonObjects	An array of buttons. Each template supports a different number of soft buttons

Creating Soft Buttons

To create a soft button using the ScreenManager, you only need to create a custom name for the button and provide the text for the button's label and/or an image for the button's icon. If your button cycles between different states (e.g. a button used to set the repeat state of a song playlist can have three states: repeat-off, repeat-one, and repeat-all), you can create all the states on initialization.

There are three different ways to create a soft button: with only text, with only an image, or with both text and an image. If creating a button with an image, we recommend that you template the image so its color works well with both the day and night modes of the head unit. For more information on templating images please see the Template Images guide.

Text Only Soft Buttons

Generic - Text Only Soft Buttons

SoftButtonState textState1 = new SoftButtonState("<#State Name1#>", "<#Button Label Text1#>", null);
SoftButtonState textState2 = new SoftButtonState("<#State Name2#>", "<#Button Label Text2#>", null);
List<SoftButtonState> stateList1 = Arrays.asList(textState1, textState2);
SoftButtonObject softButtonObject1 = new SoftButtonObject("softButtonObject1", stateList1, textState1.getName(), new SoftButtonObject.OnEventListener() {
    @Override
    public void onPress(SoftButtonObject softButtonObject, OnButtonPress onButtonPress) {
        softButtonObject.transitionToNextState();
    }

    @Override
    public void onEvent(SoftButtonObject softButtonObject, OnButtonEvent onButtonEvent) {
    }
});

SoftButtonState textState3 = new SoftButtonState("<#State Name3#>", "<#Button Label Text3#>", null);
SoftButtonObject softButtonObject2 = new SoftButtonObject("softButtonObject2", Collections.singletonList(textState3), textState1.getName(), new SoftButtonObject.OnEventListener() {
    @Override
    public void onPress(SoftButtonObject softButtonObject, OnButtonPress onButtonPress) {
    }

    @Override
    public void onEvent(SoftButtonObject softButtonObject, OnButtonEvent onButtonEvent) {
    }
});

sdlManager.getScreenManager().beginTransaction();
sdlManager.getScreenManager().setSoftButtonObjects(Arrays.asList(softButtonObject1, softButtonObject2));
sdlManager.getScreenManager().commit(new CompletionListener() {
    @Override
    public void onComplete(boolean success) {
        DebugTool.logInfo(TAG, "ScreenManager update complete: " + success);
    }
});

Image Only Soft Buttons

You can use the SystemCapabilityManager to check if the HMI supports soft buttons with images. If you send image-only buttons to a HMI that does not support images, then the library will not send the buttons as they will be rejected by the head unit. If all your soft buttons have text in addition to images, the library will send the text-only buttons if the head unit does not support images.

Generic - Image Only Soft Buttons

List<SoftButtonCapabilities> softButtonCapabilitiesList = sdlManager.getSystemCapabilityManager().getDefaultMainWindowCapability().getSoftButtonCapabilities();
boolean imageSupported = (!softButtonCapabilitiesList.isEmpty()) ? softButtonCapabilitiesList.get(0).getImageSupported() : false;

Once you know that the HMI supports images in soft buttons you can create and send the image-only soft buttons.

SoftButtonState imageState1 = new SoftButtonState("<#State Name1#>", null, sdlArtwork1);
SoftButtonState imageState2 = new SoftButtonState("<#State Name2#>", null, sdlArtwork2);
SoftButtonObject softButtonObject1 = new SoftButtonObject("softButtonObject1", Arrays.asList(imageState1, imageState2), imageState1.getName(), new SoftButtonObject.OnEventListener() {
    @Override
    public void onPress(SoftButtonObject softButtonObject, OnButtonPress onButtonPress) {
        softButtonObject.transitionToNextState();
    }

    @Override
    public void onEvent(SoftButtonObject softButtonObject, OnButtonEvent onButtonEvent) {
    }
});

SoftButtonState imageState3 = new SoftButtonState("<#State Name3#>", null, sdlArtwork3);
SoftButtonObject softButtonObject2 = new SoftButtonObject("softButtonObject2", Collections.singletonList(imageState3), imageState3.getName(), new SoftButtonObject.OnEventListener() {
    @Override
    public void onPress(SoftButtonObject softButtonObject, OnButtonPress onButtonPress) {
    }

    @Override
    public void onEvent(SoftButtonObject softButtonObject, OnButtonEvent onButtonEvent) {
    }
});

sdlManager.getScreenManager().beginTransaction();
sdlManager.getScreenManager().setSoftButtonObjects(Arrays.asList(softButtonObject1, softButtonObject2));
sdlManager.getScreenManager().commit(new CompletionListener() {
    @Override
    public void onComplete(boolean success) {
        DebugTool.logInfo(TAG, "ScreenManager update complete: " + success);
    }
});

Image and Text Soft Buttons

Generic - Text and Image Soft Buttons

SoftButtonState textAndImageState1 = new SoftButtonState("<#State Name1#>", "<#Button Label Text1#>", sdlArtwork1);
SoftButtonState textAndImageState2 = new SoftButtonState("<#State Name2#>", "<#Button Label Text2#>", sdlArtwork2);
SoftButtonObject softButtonObject1 = new SoftButtonObject("softButtonObject1", Arrays.asList(textAndImageState1, textAndImageState2), textAndImageState1.getName(), new SoftButtonObject.OnEventListener() {
    @Override
    public void onPress(SoftButtonObject softButtonObject, OnButtonPress onButtonPress) {
        softButtonObject.transitionToNextState();
    }

    @Override
    public void onEvent(SoftButtonObject softButtonObject, OnButtonEvent onButtonEvent) {
    }
});

SoftButtonState textAndImageState3 = new SoftButtonState("<#State Name3#>", "<#Button Label Text3#>", sdlArtwork3);
SoftButtonObject softButtonObject2 = new SoftButtonObject("softButtonObject2", Collections.singletonList(textAndImageState3), textAndImageState3.getName(), new SoftButtonObject.OnEventListener() {
    @Override
    public void onPress(SoftButtonObject softButtonObject, OnButtonPress onButtonPress) {
    }

    @Override
    public void onEvent(SoftButtonObject softButtonObject, OnButtonEvent onButtonEvent) {
    }
});

sdlManager.getScreenManager().beginTransaction();
sdlManager.getScreenManager().setSoftButtonObjects(Arrays.asList(softButtonObject1, softButtonObject2));
sdlManager.getScreenManager().commit(new CompletionListener() {
    @Override
    public void onComplete(boolean success) {
        DebugTool.logInfo(TAG, "ScreenManager update complete: " + success);
    }
});

Highlighting a Soft Button

When a button is highlighted its background color will change to indicate that it has been selected.

Highlight On

Generic HMI

Highlight Off

Generic HMI

SoftButtonState softButtonState1 = new SoftButtonState("Soft Button State Name", "On", sdlArtwork);
softButtonState1.setHighlighted(true);
SoftButtonState softButtonState2 = new SoftButtonState("Soft Button State Name 2", "Off", sdlArtwork);
softButtonState2.setHighlighted(false);
SoftButtonObject softButtonObject = new SoftButtonObject("softButtonObject", Arrays.asList(softButtonState1, softButtonState2), softButtonState1.getName(), new SoftButtonObject.OnEventListener() {
     @Override
     public void onPress(SoftButtonObject softButtonObject, OnButtonPress onButtonPress) {
         softButtonObject.transitionToNextState();
     }

     @Override
     public void onEvent(SoftButtonObject softButtonObject, OnButtonEvent onButtonEvent) {
     }
});

Updating Soft Button States

When the soft button state needs to be updated, simply tell the SoftButtonObject to transition to the next state. If your button states do not cycle in a predictable order, you can also tell the soft button which state to transition to by passing the stateName of the new soft button state.

SoftButtonState state1 = new SoftButtonState("<#State1 Name#>", "<#Button1 Label Text#>", sdlArtwork);
SoftButtonState state2 = new SoftButtonState("<#State2 Name#>", "<#Button2 Label Text#>", sdlArtwork);

SoftButtonObject softButtonObject = new SoftButtonObject("softButtonObject", Arrays.asList(state1, state2), state1.getName(), new SoftButtonObject.OnEventListener() {
    @Override
    public void onPress(SoftButtonObject softButtonObject, OnButtonPress onButtonPress) { 
    }

    @Override
    public void onEvent(SoftButtonObject softButtonObject, OnButtonEvent onButtonEvent) {
    }
});

sdlManager.getScreenManager().beginTransaction();
sdlManager.getScreenManager().setSoftButtonObjects(Collections.singletonList(softButtonObject));
sdlManager.getScreenManager().commit(new CompletionListener() {
    @Override
    public void onComplete(boolean success) {
        DebugTool.logInfo(TAG, "ScreenManager update complete: " + success);
    }
});

// Transition to a new state
SoftButtonObject retrievedSoftButtonObject = sdlManager.getScreenManager().getSoftButtonObjectByName("softButtonObject");
retrievedSoftButtonObject.transitionToNextState();

Deleting Soft Buttons

To delete soft buttons, simply pass the screen manager a new array of soft buttons. To delete all soft buttons, simply pass the screen manager an empty array.

sdlManager.getScreenManager().setSoftButtonObjects(Collections.EMPTY_LIST);

Using RPCs

You can also send soft buttons manually using the Show RPC. Note that if you do so, you must not mix the ScreenManager soft buttons and manually sending the Show RPC. Additionally, the ScreenManager takes soft button ids 0 - 10000. Ensure that if you use custom RPCs, that the soft button ids you use are outside of this range.

View on GitHub.com

Previous Section Next Section