Classic: Let’s Focus on Highlighting!

This post was written by EunKyung Choi

Image Source:

In my last blog article, I’ve shown you how to customize highlighting styles when a custom control receives a focus. Here, I would like to expand on the topic of visual effects that you can apply to those controls with images and icons as well as text. This is new to BlackBerry 10.3.1.

Let’s dive into the CustomListItem class. The CustomListItem class is commonly used in a list view to represent text data with images or icons. The HighlightAppearance property has been supported since BlackBerry 10.2.0. When the HighlightAppearance value is not specified, the default highlight mode for a CustomListItem is set to “Full”. In 10.3.1, this setting will highlight the entire item when the CustomListItem receives focus while navigating the list using the trackpad. The following image shows the default highlight behaviour for a CustomListItem.


Next to the HighlightAppearance settings, it is also possible to customize the text of the focused item by:

– Highlighting the background colour;

– Highlighting the primary text colour;

– Highlighting the secondary text colour (if there is any).

It is also noteworthy to mention that if your application is using the customized primary and primary base colour settings in the bar-discriptor.xml file, the colour values are conveniently accessible though the UIPalette APIs.


For the CustomListItem containing ImageView, if the image is a picture, the highlight colour needs to be mixed in with the image, and if the image is an icon, the focused icon should turn to white. That can be achieved easily by applying the BrightnessEffect to the image.

You can also apply FocusHighlightEffect and SaturateEffect to pictures and icons. However, only one visual effect can be applied at a time. If multiple effects exist for an ImageView, only the first one will be shown and the subsequent effect(s) will be ignored. For more details, please check out the AbstractEffect class.

The following code demonstrates the customized focus highlighting using the UIPalette and the BrightnessEffect APIs.



And here is the code in action! When the list item receives focus, the colour of the text changes to the application’s textOnPrimary colour and the icon turns to white.


Applying UIPalette colours when highlighting focused items follows the application’s theme, i.e any changes to the theme or primary colour will automatically be applied to all components including backgrounds, text, controls, etc.

That’s all for now, till next time!

EK Choi

About EK Choi

EK is a member of the Enterprise Solutions Team, helping developers to create secure applications using BlackBerry solutions and services.