In PowerBuilder 2019, 3 new UI themes are provided to control how PowerBuilder’s commonly-used controls render in runtime applications. These new UI themes adopt a “Windows 10” style to enhance the appearances of applications. For detailed description of the themes, see Understanding system themes and Details on the theme settings and their effects.

You can directly control whether an application applies a new UI theme, or provide users with the ability to select a preferred theme by themselves. For details, see Applying a theme.

It is possible for you to modify a system theme through changing the theme template files, or to copy a system theme to create a custom theme. This way, you can further tune the color settings in the theme to your personal preference. For details, see Creating a custom theme.  

You may want to use the UI theme settings together with the PowerBuilder IDE settings and scripting techniques to achieve optimum UI effects. For samples on how to start the work, see Several useful techniques to further adjust your user interface.

Understanding system themes

There are three system themes available, featuring flat design style in contrasting to the old fashioned 3D design. System themes affect the display of windows, DataWindows, and all visual controls in runtime applications.

• Flat Design Blue -- this theme is similar to the common UI style used in the Windows 10. Windows would display in white background; a control would display in blue background if it’s set to default (default state), and display in grey if it is non-default (normal state).

• Flat Design Grey -- this theme is based on the original PowerBuilder style. Windows would display in gray background; controls would mostly display in darker blue.

• Flat Design Silver -- this theme features borderless controls, and a non-black (lighter black) font color. Windows would display in white background, and controls in silver color.

Table below shows you the major UI features of each theme, and the differences between the themes and the default “Do not use theme” option (the UI rendering option in previous PowerBuilder versions).

Creating a custom theme

You can create a custom theme through modifying one of the existing system themes. In the custom theme, you have options to define color settings according to your personal preference.

To create a new theme:

1. Locate the "theme190" folder in the "Appeon\Shared\PowerBuilder" directory. There are by default three sub-folders; each represents one type of UI theme: Flat Design Blue, Flat Design Grey, and Flat Design Silver. You can add your own themes here.
2. Find the sub-folder for the UI theme you want to customize. Each sub-folder contains a "theme.json" file which is configurable for the theme settings (such as color, state, border, text etc). Except for the “theme.json” file, there are a bunch of image files which represent the state (checked, unchecked, indeterminate, enabled, disabled, hover, pressed etc.) of the controls, DataWindow and window.
3. Creating a new sub-folder in the “theme190” folder by copying and pasting an existing sub-folder. The new sub-folder will be automatically recognized as a custom theme and listed for selection in the Themes tab. Alternatively, you may directly edit the sub-folder for a system theme, thus having the system theme updated.
4. In the "theme.json" file, adjust the UI theme settings for the controls, DataWindow and window, and then save the file. 

To restore a system theme:

If you directly make changes to the system theme and unpredictable problem occurs, you can click the Restore button in the Additional Properties | Themes tab to restore the system theme.

Applying a theme

You can select a theme in the painter or via script. The selected theme only takes effect at runtime.

To select a theme in the painter:

1. In the Application painter, select the General tab page.
2. On the General tab page, click the Additional Properties button to display the Application properties dialog box.
3. In the Application properties dialog box, select the Themes tab, and then select a theme from the list.
4. Click OK.

To select a theme in the script:

You can also set a theme in the script by calling the ApplyTheme function. For example, the following script applies the "Flat Design Blue" theme to the current application:

The ApplyTheme method should be called in the Application Open event when all of the child windows are not yet opened.

The recommended practice is to add an open dialog box for an application, in which you provide the theme options that you allow users to select by themselves.

To update the icons used in your application:

1. Click the Run or Select and Run button on the PowerBar to run the application and see the UI effect of the selected theme. The UI theme only takes effect at runtime, not at the development stage or under preview.
2. Build the application. Note: You should not check the "Windows classic style" option. If "Windows classic style" is selected, the application UI will be rendered in the Windows classic style instead of the selected theme. The "Windows classic style" option takes precedence over the selected theme.

3. Create the application installation package that contains the theme files. The theme files locate in the "theme190" folder in the "Appeon\Shared\PowerBuilder" directory. When creating the application installation package, you must copy the "theme190" folder (just like the other resource files) to the root of the application installation directory.

Details on the theme settings and their effects

Theme setting in the "theme.json" file

The “theme.json” file for each theme contains all the theme settings that can be set through a theme. The file is well structured and shall be easy to follow. Here are a few points worth mentioning:

• “drawing”=true in each section means that the settings in the section will take effect. You can set the node to false if you want to use the “no-theme” style for all the settings in the section. Note that the value for "drawing" can only be true or false (all letters in lower case).
• “border” may be set to 0, 1, or 2. Unless otherwise explained in this tutorial, 0 means whether to draw borders relies on the Border setting in the PB IDE; 1 means that borders will always be drawn; 2 means no border.
• The other node values will be either hex color value or specific image file to be assigned to the node.

You will find that you can configure much more visual elements in your application than before. The following table lists the additional UI properties that you can set in the theme.json file.

How theme settings work

It is complicated to update the look and feel of an application to a new style, especially considering that you may have set the display properties in the Properties, using expressions, or by scripts. Therefore, it is important to understand how the settings in each theme will affect your application.

Windows

General rule

Once a theme is applied, the UI setting (mainly background color) of window is determined by the theme.json file only.

What can be set by the theme

• The background color of window is determined by the theme.json file (and the background color of user object is determined by the background color of window).

What cannot be set by the theme

• The theme is not effective to the user object and window, including the menu, toolbar and scrollbar on the window and user object.
• The theme is not effective to the Windows system dialog (such as Save As dialog, Open dialog) and the PowerBuilder built-in dialog (such as Filter dialog, Sort dialog).

Controls

General rule

Once a theme is applied, the UI setting (mainly font color and background color) of controls is determined by the theme.json file. Whether to display borders varies with different controls.

What can be set by the theme

As explained above, the background color and font color of controls are always determined by the theme.json file. See the table below for how the control border will be determined.

What cannot be set by the theme

See the table below for what cannot be set by the theme on controls.

DataWindows

General rule

With DataWindows, after you apply a UI theme, the UI settings (except border and resizable) of DataWindow are determined by the “theme.json” file but can be changed by the expression or the Modify method.

The DataWindow section in the “theme.json” file contains “grid-style” and “cross-style” subsections respectively for the settings for the display properties in Grid and CrossTab style DataWindows, and the other settings outside the subsections for the other display properties that are not covered in the subsections.

What can be set by the theme

 See the table below for how the DataWindow properties will be determined by the "theme.json" settings, and the settings in the PowerBuilder IDE, and in scripts.

What cannot be set by the theme

• The theme is not effective to:
  • Label, Composite, OLE 2.0, and RichText presentation styles;
  • DataWindow title bar;
  • DataWindow Button control if the button displays a picture (system picture or custom picture).
• If a DataWindow control is dynamically created, it will be first rendered by the theme.json file (rather than defined in the Create statement), or changed later by the property expression in the PowerBuilder IDE or the Modify method in the script.
• When printing or saving the DataWindow as PDF file, the theme will not take effect, except for the Graph DataWindow.

Several useful techniques to further adjust your user interface

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.

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

Before applying a theme, 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, 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 expression in the properties dialog.

How to set the background color of DataWindow

Before applying a theme, 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 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:

After applying a theme:  

Solution: You can use a text control as the background and set its background color using an expression.