Tech Articles

Applying a New UI Theme to Your Application

Print
Details
Category: PowerBuilder
Hits: 5103

User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active
 

This tutorial is an update to the 2019 tutorial. If you have zero experience with the UI Theme feature, please first follow our Quick Start tutorial. If you are ready to gain a comprehensive understanding of this feature and dive deeper into UI Theme settings, then please proceed with this updated tutorial.

Starting from PowerBuilder 2019, Appeon added the UI theme feature to PowerBuilder so that developers can codelessly control how commonly-used controls and objects render during application runtime.

UI Theme configuration

You can configure the UI Theme to apply to an application in the Additional Properties > Themes settings of the application object.

The default theme path contains four system themes: Flat Design Blue, Flat Design Dark, Flat Design Grey, and Flat Design Silver. Table below shows you the major UI features of each system theme, and the differences between the themes and the “Do not use theme” options (the UI rendering option in previous PowerBuilder versions).

 

Do not use theme

Flat Design Blue

Flat Design Dark

Flat Design Grey

Flat Design Silver

Window background color

Set in the painter or script

White

Dark

Grey

White

Font color

Set in the painter or script

Black

White

Black

Silver Black

Control background color

Set in the painter or script

White

Black

White

White or Shallow Color Block

Button

System

2D

2D

2D

2D

Border

3D

2D

2D

2D

No Border

Border thickness

1 pixel

1 pixel

1 pixel

1 pixel

No Border

Furthermore, please pay attention to the following configuration if you select to apply a UI Theme:

UI Theme functions

There are two UI Theme functions: ApplyTheme and GetTheme.

ApplyTheme

Instead of specifying the theme to use in the Additional Properties of the application object, you can set a theme dynamically in your source code using the ApplyTheme method.

For example, the following script applies the "Flat Design Blue" theme in the default theme path of the current application:

ApplyTheme ("Flat Design Blue")

The following script applies the "Flat Design Blue" theme in D:\App1SourceCode\themes\.  

ApplyTheme("D:\App1SourceCode\themes\Flat Design Blue")

The following script applies the "Flat Design Blue" theme in themes\ folder in the directory that contains the PBT.  

ApplyTheme("themes\Flat Design Blue")

Recommended practices:

GetTheme

You can get the theme that is currently applied to the application UI using this method.

For example, the following example gets the theme name that is currently applied to the application:

String ls_themename
ls_themename = GetTheme()

UI Theme definition

System themes

If you open the default theme path %Appeon%\Shared\PowerBuilder\theme190, you will see four folders in it: Flat Design Blue, Flat Design Dark, Flat Design Grey, and Flat Design Silver. Each folder contains the UI Theme definition files of the corresponding theme. There are only two types of files for the purpose:

Note: Compared with version 2019, the theme.json file in version 2019 R2 add more theme settings (JSON nodes):

"graph-control"->"hover-state"

"graph-control"->"focused-state"

"groupbox"->"background-transparent"

"groupbox"->"normal-state"->"background-color"

"singlelineedit"->"placeholder"

Therefore, if you have customized the theme.json file in version 2019, be careful not to directly copy it over to version 2019 R2. It would result in rendering failure of the UI theme. 

Custom themes

You can add a new folder in the theme path to create a custom theme. In case it is too complicated to create a custom theme folder from scratch, you can duplicate an existing system theme folder and use that as the starting point for your custom theme. Yes, make sure to include the master "theme.json" file in the custom theme!

Custom theme definition files for selected objects or controls

The "theme.json" file applies globally to all the objects and controls in the application. For either a custom theme or system theme, you can define special visual override for selected objects or controls, such as:

The way to do it is to add one or more custom theme definition files in the theme folder, following these rules:

  1. The new theme files shall follow this format: theme-[xxxx].json. The file prefix must be "theme-", [xxxx] can be any text, and the extension must be .json. For example:

    theme-123.json

    theme-abc.json

  2. The settings in the file can be a subset or all of the "theme.json" file. While the nodes that host theme settings are the system object or control name in "theme.json" (such as "checkbox", "commandbutton"), the nodes that host theme settings in the custom theme files shall be the name that points to the specific object(s) or control(s) that will apply the settings. For example: 
    {
 "meta-info":
 {
  "version":"190"
 },
  "w_main.uo_1.cb_1":
 {
   ...
   // Copy the settings from the "commandbutton" node of
   //the "theme.json" file and then modify
 }
  "w_main$commandbutton":
 {
   ...
   //Copy the settings from the "commandbutton" node of
   //the "theme.json" file and then modify
 }
  "w_main":
 {
   ...
   //Copy the settings from the "window" node of
   //the "theme.json" file and then modify
 }
}
  3. Pay attention to the precedence on which settings would apply if multiple settings are defined for the same object/control:
    • If there are multiple theme-[xxxx].json files, the settings in the last file in alphabetical order will be applied.
    • From the highest to the lowest priority: settings configured for the specific control (in theme-[xxxx].json) > settings for controls of the same type (in theme-[xxxx].json) > generic settings for controls of the same type (in theme.json).

For more details about defining custom theme files and examples, you may further refer to:

https://docs.appeon.com/appeon_online_help/pb2019r2/pbug/ch04s04.html#Configuring_theme_settings_for_individual_controls.

UI Theme deployment

When you deploy the application, make sure to deploy the following two runtime files together with the application for the UI Theme support:

Also, you must copy the theme definition folder (with the folder name being the same as the theme name) into the root directory of the application .exe file. The following explains the right way to do it:

Supported and unsupported theme settings

If you have customized visual properties in the Properties, using expressions, or by PowerScript, you may find the UI Theme may clash with your customizations. Therefore, it is important to know the list of supported and unsupported theme settings and adjust accordingly.

General Settings

Windows and user objects

What can be set by the theme

What cannot be set by the theme

Controls

What can be set by the theme

What cannot be set by the theme

DataWindows

What can be set by the theme

What cannot be set by the theme

Additional theme settings

By upgrading to PowerBuilder 2019 R2, the new UI theme allows you to configure much more visual elements of the controls than before.

Grid line:

Toolbar

Graph

User object

DataWindow

StaticText, StaticHyperLink and GroupBox

Select row:

Images:

Several useful techniques to further adjust your user interface

How to turn off  UI Theme at runtime

Use this workaround if you want to dynamically turn off the theme at runtime: create a custom theme that has {“drawing”:false} for every control type, and use this theme in the ApplyTheme method.

Note: Before switching between themes or turning off the theme thru the ApplyTheme method, it is the best practice to prompt end users to reopen the current window, in order to refresh the UI correctly.

How to make it easier to resize windows in new theme

Windows in new UI theme have modern-looking 2D borders. The lines of the borders are quite thin, sometimes causing difficulty to change the cursor to the resizing cursor. If you want to make it easier for your app users to resize windows, you can consider to slightly enlarge the width of the border lines, for globally window (in theme.json) or for a specific window (in theme_123.json, for example).  

The JSON node "Window"->"border"->"margin" determines the width of the border lines. By default, the value is [1,30,1,1], respectively for the left border, upper border, right border and lower border. You can change the settings for the left border, right border, and lower border to 2 or 3.  For example, [3,30,3,3]. The border will be bolder, and when you hover mouse over, the cursor will change to the resizing cursor more easily.

How to update the icons used in your application

You may find that the old-fashioned icons used in the application clashes with the modern appearance of UI Themes. Therefore, it may be necessary to update the icons to a modern style.

There are two options for updating the icons:

Option A: You can replace each icon manually. A set of Windows 10 style icons are provided for selection under the "icons" list and the "small pictures" list in the Property tab for controls. The icons can be easily distinguished by their names: "_icon_2" is appended to the name of each new icon, and "_2" is appended to the name of each new small picture. 

Option B: Appeon has developed a free icon-replacement tool to help you with completing the task. For more information about the tool, see https://community.appeon.com/index.php/codeexchange/powerbuilder/177-icon-replace-tool.

How to disable the new UI theme for a control

Taking StaticText as an example. If a theme is applied, the font color, background color, and border of StaticText can only be set in the theme.json file, and cannot be dynamically changed by the expression or the Modify method. If you want to set different font color or background color for multiple StaticText controls, you will have to disable the UI theme for this control first.

To disable the UI theme for the StaticText control, change the value of “drawing” to false under “statictext” in the theme.json file.

statictext":
	{
		"drawing":false,
		"border":0,
		"background-transparent":true,
		"normal-state":
		{
			"text-font":{"color":"#000000"}
		},
		"disabled-state":
		{
			"text-font":{"color":"#999999"}
		}
	},

How to set the font color of text control in the DataWindow

Before applying a theme (take New Customer window as an example): the asterisk for a few columns (such as Customer ID, Last Name, First Name) is set to blue.

After applying a theme:

All text controls in DataWindow have the same font color (black) in the theme.json file.

Solution:

If you want to set it to a different color, you can set it by specifying an expression in the properties dialog.

Add an expression for Text Color in the Font Properties dialog to set the asterisk to blue.

Specify the color in the expression box.

 

How to set the background color of text control in the DataWindow

Before applying a theme (take New Order window as an example):

The background of the text field for Order ID and Amount is set to grey in the properties dialog.

After applying a theme:

The background color set in the properties dialog does not take effect; instead, all text fields have the same background color which is set in theme.json.

Solution:

To set the background of the text field for Order ID and Amount to a different color, you can set it by using an expression in the properties dialog.

How to set the background color of DataWindow

Before applying a theme (take Customer Report window as an example):

The background color of DataWindow is set by the following script:

dw_1.modify("datawindow.color="+string(il_BackColor))

After applying a theme:

The script that modifies the DataWindow background.color does not take effect.

Solution:

You can set the background color by the following method:

Method 1: Use the following script to modify the background color of the DataWindow Detail band:

dw_1.modify("datawindow.detail.color = "+string(il_BackColor))

Method 2: Use the expression in the properties dialog to modify the background color of the DataWindow Detail band.

How to set the background color of a DataWindow column

Before applying a theme (take Customer Maintenance window as an example):

After applying a theme:

  

Solution:

You can use a text control as the background and set its background color using an expression.
We use cookies which are necessary for the proper functioning of our websites. We also use cookies to analyze our traffic, improve your experience and provide social media features. If you continue to use this site, you consent to our use of cookies.