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).
|
|
Do not use theme |
Flat Design Blue |
Flat Design Grey |
Flat Design Silver |
|
Window background color |
Set in the painter or script |
White |
Grey |
White |
|
Font color |
Set in the painter or script |
Black |
Black |
Silver Black |
|
Control background color |
Set in the painter or script |
White |
White |
White or Shallow Color Block |
|
Button |
System |
2D |
2D |
2D |
|
Border |
3D |
2D |
2D |
No Border |
|
Border thickness |
1 pixel |
1 pixel |
1 pixel |
No Border |
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:
- 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.
- 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.
- 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.
- 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:
- In the Application painter, select the General tab page.
- On the General tab page, click the Additional Properties button to display the Application properties dialog box.
- In the Application properties dialog box, select the Themes tab, and then select a theme from the list.
- 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:
|
ApplyTheme ("Flat Design Blue") |
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:
You will find that the old 3D-fashioned icons used in the applications do not fit well with the new themes. Therefore, it is necessary to update the icons to new styles as well.
There are two options for updating the icons:
Option A: You can replace each old-fashioned 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 engineers have prepared an icon-replacement tool for you to complete the task. For more information about the tool, see
https://community.appeon.com/index.php/codeexchange/powerbuilder/177-icon-replace-tool.
- 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.
- 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.
- 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.
|
UI Feature |
Corresponding Nodes in “theme.json” |
|
The box images for the CheckBox control and the CheckBox edit-style column |
“checkbox” and “datawindow”->“dwo-column”->“checkbox-type” ->“box-images” |
|
The radio images for the RadioButton control and the RadioButton edit-style column in DataWindow |
“radiobutton” and “datawindow”->“dwo-column”->“radiobuttons-type” ->”radio-images” |
|
The text color and background color for the selected row in the DropDown edit-style column in DataWindow |
“datawindow”->“dwo-column”->“dropdown-type”->"selected-row-text-color" “datawindow”->“dwo-column”->“dropdown-type”->"selected-row-background-color” |
|
The arrow for the DropDown edit-style column in DataWindow |
“datawindow”->“dwo-column”->“dropdown-type”->”arrow-image” |
|
The text color and background color for the detail band of CrossTab and Grid DataWindow |
“datawindow”->“cross-style” and “datawindow”->“grid-style”->”detail-band”->”selected-row-text-color” “datawindow”->“cross-style” and “datawindow”->“grid-style”->”detail-band”->”selected-row-background-color” |
|
The line and color for the grid line of CrossTab and Grid DataWindow |
“datawindow”->“cross-style” or “datawindow”->“grid-style”->”grid-line” |
|
The arrow for the DatePicker, DropDownListBox, and DropDownPictureListBox controls |
“datepicker”, “dropdownlistbox”, and “dropdownpicturelistbox”->”arrow-image” |
|
The arrow (up, down, and dropdown) for the EditMask control and the EditMask edit-style column in DataWindow |
“editmask” or “datawindow” -> “dwo-column” -> “editmask-type”->”images” |
|
The left and right buttons for the HScrollBar control |
“hscrollbar”->”images” |
|
The top and bottom buttons for the VScrollBar control |
“vscrollbar”->”images” |
|
The left, right, top, and bottom buttons for the Tab control |
“tab”->”images” |
|
The foreground and background color for the slider and the image for thumb in the HTrackBar and VTrackBar control |
“htrackbar” and “vtrackbar”->”slider” |
|
The image for the check box and the expanded and collapsed buttons in TreeView |
“treeview”->”images” |
|
The color for a graph |
"graph-colors" |
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.
|
Control |
Border Setting |
|
InkEdit, InkPicture, SingleLineEdit, EditMask, MultiLineEdit, RichTextEdit, ListBox, PictureListBox, ListView, TreeView, Graph, and MonthCalendar |
· Controlled by the Border property setting in the PB IDE. · Dynamically setting the border property by script will not take effect. · The border style is always StyleBox! |
|
StaticText |
Controlled by setting in “theme.json” · (Default) “border”=0: no border; · “border”=1: Controlled by the Border property setting in the PB IDE. The border style is always StyleBox! |
|
StaticHyperLink |
Controlled by setting in “theme.json” · (Default) “border”=0: no border except when 1) its border is set to StyleShadowBox in the IDE; or 2) its background is not transparent and its border is set to StyleBox in the IDE.; · “border”=1: Controlled by the Border property setting in the PB IDE. The border style is always StyleBox! |
|
DatePicker , DropDownListBox, and DropDownPictureListBox |
Same as before (their border is always rendered, regardless of the border property in the IDE), although the border style is always StyleBox!. |
|
TrackBar, CommandButton, PictureButton, CheckBox, RadioButton, ProgressBar, and GroupBox |
Same as before (These controls do not have Border property), although the border style is always StyleBox!. |
What cannot be set by the theme
See the table below for what cannot be set by the theme on controls.
|
Control |
How the settings work |
|
Line, Oval, Rectangle, RoundRectangle, Picture, PictureHyperLink, and Animation |
Not supported |
|
OLE control, ActiveX control |
Not supported |
|
RichTextEdit |
Because it is a third-party ActiveX control nly the border of this control is configurable in the theme.json file. |
|
All the controls configurable in “theme.json” |
The background color and font color cannot be changed in the PowerBuilder IDE. They can only be set in the theme.json file, except that: The background color for the following control is transparent: CheckBox, RadioButton, GroupBox, StaticText, and StaticHyperLink; it cannot be changed in the PowerBuilder IDE or the theme.json file. But when they are placed on top of an unsupported control (such as Picture), their background color will not be transparent and can be set in the PowerBuilder IDE. |
|
RadioButton and CheckBox |
The RightToLeft and LeftText property settings will be always ignored. |
|
DropDownListBox and DropDownPictureListBox |
The RightToLeft property setting will be always ignored. |
|
TreeView |
The lines that connect the tree items in the TreeView control will not display, even if the HasLines property is enabled. |
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.
|
DataWindow Property |
How the theme settings work |
|
|
Border |
· Dynamically setting the border property at runtime in the script will not take effect. · If “border”=0 in theme.json, only when the Border setting in the PB IDE is true, a DataWindow will have border; the border style is always StyleBox!; the border color will be rendered using the border color setting in theme.json; · When “border”=1 in theme.json, DataWindow will have StyleBox! border, regardless of the border property in the PowerBuilder IDE. · When “border”=2 in theme.json, DataWindow will not have border, regardless of the border property in the PowerBuilder IDE. · The CheckBox and RadioButton control on a DataWindow Column will have no border. · When the TitleBar property is disabled and the border property is enabled in the PowerBuilder IDE, border is rendered using the theme; when both the TitleBar property and the border property are disabled in the PowerBuilder IDE, no border is rendered. (The theme is not effective to the DataWindow title bar as well as to its border.) |
|
|
Background color |
Column, Text, Computed Field, and GroupBox controls |
Determined by “theme.json” setting section; and can be modified by the expression or the Modify method.
|
|
Header band of Grid and CrossTab DataWindows |
Determined by “theme.json” setting |
|
|
Other bands (except for the Header of Grid and Crosstab DataWindows) |
Only determined by setting in the PowerBuilder IDE. |
|
|
Text in the header of Grid and CrossTab DataWindows |
Always transparent |
|
|
Font color |
Column, Text, Computed Field, and GroupBox controls |
Determined by “theme.json” setting; and can be modified by the expression or the Modify method. |
|
Highlight color of selected rows |
· For CrossTab DataWindows, the color is configured in the “cross-style” section in the “theme.json” file; · For non-CrossTab DataWindowsd, the color is configured in the “grid-style” section in the “theme-json” file. |
|
|
Resizable |
· The resizable property in the PowerBuilder IDE takes effect: when enabled in the IDE, DataWindow is not flattened; when disabled in the IDE, DataWindow is flattened. Dynamically setting the resizable property at runtime in the script will not take effect. |
|
|
RightToLeft |
· The property is unsupported for RadioButton, CheckBox, and TreeView DataWindow. · The LeftText property is unsupported for RadioButton and CheckBox. · |
|
|
LeftText |
· The property is unsupported for RadioButton and CheckBox. |
|
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.
|
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, 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.