Specifying application properties

You specify application properties in the Application painter's Properties view.

To specify application properties:

  1. In the Application painter, if the Properties view is not open, select View>Properties from the menu bar.

    With the exception of the AppName property, the properties on the General and Toolbar tab pages can be modified in the Properties view and in scripts.

    If you need help specifying properties in the Properties view, right-click on the background of the Properties view and select Help from the pop-up menu.

  2. Select the General or Toolbar tab page, or, on the General tab page, click the Additional Properties button to display the Application properties dialog box.

    The additional properties on the Application properties dialog box can be modified only in this dialog box. They cannot be modified in scripts.

  3. Specify the properties:

    To specify this

    Use this tab page

    Display name

    General tab page

    Application has toolbar text and toolbar tips

    Toolbar tab page

    Default font for static text as it appears in windows, user objects, and DataWindow objects

    Additional Properties (Text Font)

    Default font for data retrieved in a DataWindow object

    Additional Properties (Column Font)

    Default font for column headers in tabular and grid DataWindow objects

    Additional Properties (Header Font)

    Default font for column labels in freeform DataWindow objects

    Additional Properties (Label Font)

    Application icon

    Additional Properties (Icon)

    Global objects for the application

    Additional Properties (Variable Types)

    RichTextEdit control for the application

    Additional Properties (RichTextEdit)

    UI theme for the application

    Additional Properties (Themes)


These sections have information about how you specify the following application properties in the Application painter:

Specifying default text properties

You probably want to establish a standard look for the text in your application. There are four kinds of text whose properties you can specify in the Application painter: text, header, column, and label.

PowerBuilder provides default settings for the font, size, and style for each of these and a default color for text and the background. You can change these settings for an application in the Application painter and override the settings for a window, user object, or DataWindow object.

Properties set in the Database painter override application properties

If extended attributes have been set for a database column in the Database painter or Table painter, those font specifications override the fonts specified in the Application painter.

To change the text defaults for an application:

  1. In the Properties view, click Additional Properties and select one of the following:

    • Text Font tab

    • Header Font tab

    • Column Font tab

    • Label Font tab

    The tab you choose displays the current settings for the font, size, style, and color. The text in the Sample box illustrates text with the current settings.

  2. Review the settings and make any necessary changes:

    • To change the font, select a font from the Font list.

    • To change the size, select a size from the Size list or type a valid size in the list.

    • To change the style, select a style (Regular, Italic, Bold, or Bold Italic) from the Font styles list.

    • To change font effects, select one or more from the Effects group box (Strikeout and Underline).

    • To change the text color, select a color from the Text Color list. (You do not specify colors for data, headings, and labels here; instead, you do that in the DataWindow painter.)

    • To change the background color, select a color from the Background list.

    Using custom colors

    When specifying a text color, you can choose a custom color. You can define custom colors in several painters, including the Window painter or DataWindow painter.

  3. When you have made all the changes, click OK.

Specifying an icon

Users can minimize your application at runtime. If you specify an icon in the application painter, the icon will display when the application is minimized.

To associate an icon with an application

  1. In the Properties view, click Additional Properties and select the Icon tab.

  2. Specify a file containing an icon (an ICO file).

    The button displays below the Browse button.

  3. Click OK to associate the icon with the application.

Specifying default global objects

PowerBuilder provides five built-in global objects that are predefined in all applications.

Global object

Description

SQLCA

Transaction object, used to communicate with your database

SQLDA

DynamicDescriptionArea, used in dynamic SQL

SQLSA

DynamicStagingArea, used in dynamic SQL

Error

Used to report errors during execution

Message

Used to process messages that are not PowerBuilder-defined events and to pass parameters between windows


You can create your own versions of these objects by creating a standard class user object inherited from one of the built-in global objects. You can add instance variables and functions to enhance the behavior of the global objects.

For more information, see Working with User Objects.

After you do this, you can specify that you want to use your version of the object in your application as the default, instead of the built-in version.

To specify the default global objects

  1. In the Properties view, click Additional Properties and select the Variable Types tab.

    The Variable Types property page displays.

  2. Specify the standard class user object you defined in the corresponding field.

    For example, if you defined a user object named mytrans that is inherited from the built-in Transaction object, type mytrans in the box corresponding to SQLCA.


  3. Click OK.

    When you run your application, it will use the specified standard class user objects as the default objects instead of the built-in global objects.

Specifying a rich text editor

You can select from the three rich text editors supported by Appeon PowerBuilder. The selected rich text editor will be applicable to the RichTextEdit control, the RichText DataWindow object, and the RichText edit style.

To select a rich text editor:

  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.

    You can choose from three editors: Built-in TX Text Control, Built-in Rich Edit Control (TE Edit Control), and TX Text Control ActiveX X14 Professional/Enterprise.

    For more information about the rich text editors, see the section called “Rich text editors” in Application Techniques; and for feature difference of the rich text editor, see the section called “Feature difference” in Application Techniques.

  3. In the Application properties dialog box, select the RichTextEdit Control tab, and then select a rich text editor.

  4. Input a valid serial number if you selected to use the TX Text Control ActiveX X14 Professional/Enterprise editor.

  5. Click OK.

Specifying a theme for the application UI

Applying a theme

You can apply one of the following themes to the window, DataWindow, and all visual controls (except Line, Oval, Rectangle, RoundRectangle, Picture, PictureHyperLink, and Animation) in your application.

  • Flat Design Blue -- this theme is evolved from the Windows 10 style, featuring a flat design style in contrasting to a prominent UI content. The window style is similar to that of Windows 10. The controls are flattened, and the color is gray in the normal state, and blue in the default state, making a more visually appealing and recognizable UI.

  • Flat Design Dark -- this theme displays light white text on dark backgrounds, making the information on the page more prominent and easy to read; and displays a blue auxiliary color, making the page looks technical. The dark theme can lessen eye strain during the night.

  • Flat Design Grey -- this theme is based on the original PowerBuilder style. It retains most of the color matching of the controls, and removes their 3D effect so they are flattened; the window is displayed in a gray background, making the UI convenient for users to read and improves user experience.

  • Flat Design Silver -- this theme is a combination of the modern designs. The theme removes the control border, and divides controls by shallow color blocks, making the UI more concise and focused.

If no theme is applied or if the theme is unsupported for a control, the style of windows, DataWindow, and controls will be determined by the settings in the PowerBuilder IDE or script.

  Do not use theme Flat Design Blue Flat Design Dark Flat Design Grey Flat Design Silver
Window background color By IDE or script White Dark Grey White
Font color By IDE or script Black White Black Silver Black
Control background color By IDE or script White Black White White or Shallow Color Block
Button By IDE or script 2D 2D 2D 2D
Border By IDE or script 2D 2D 2D No Border
Border thickness 1 pixel 1 pixel 1 pixel 1 pixel No Border

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 specify the path for the theme files and select a theme from the list.

    • Theme Path -- The default value for Theme Path is %Appeon%\Shared\PowerBuilder\theme[version] and this is where the system themes are stored.

      Theme Path can be either set to an absolute path or a relative path. For example, it can be an absolute path: D:\App1SourceCode\Themes, or a relative path that starts with “.\”, “.\..\”, or a folder name: “.\Themes”, “.\..\Themes” or “themes”. The relative path is relative to the location of the PBT file.

      Note

      In Windows system, the maximum length for a path is defined as 260 characters. Therefore, it is recommended the theme path (including theme name) should be less than 260 characters and the path alone (excluding theme name) should be less than 200 characters.

      When the application is run from the IDE, it reads the theme files from the path specified by Theme Path in the painter; but when the application's executable file is run, the Theme Path setting in the painter will be ignored; instead it reads the theme files from the “theme[version]” folder under the root of the application installation directory (for example, if the application is installed to C:\App1Executable\, then the theme path is C:\App1Executable\theme190). To summarize:

      • At the development environment (when the app is run from the IDE): use the path set in the Theme Path field.

      • At the production environment (when the pap's executable file is run): use the "theme[version]" folder under the root of the installation directory of the application's executable file.

      However, this will no longer be the case if the ApplyTheme function is used to specify a theme, as the theme path and name set by the ApplyTheme function takes precedence over those selected in the painter.

    • Theme -- Four system themes are provided under the default path; each one is stored in a sub-folder named after the theme: Flat Design Blue, Flat Design Dark, Flat Design Grey, and Flat Design Silver. These four sub-folders will be overwritten when you re-install or upgrade PowerBuilder IDE. Therefore, if you want to customize the system theme, make sure to make a copy of the theme and then make changes there, the custom theme will not be overwritten when PowerBuilder is re-installed or upgraded.

    • Restore button -- The Restore button is effective only when Theme Path is the default path and the theme name is the system theme.

      If restoring theme failed, make sure to close any theme files that are currently opened and then click the Restore button to try again.

  4. In the Preview section, take a quick look at how UI will look like after a theme is applied.

  5. Click OK.

To select a theme in the script:

  • Call the ApplyTheme function in the application script to select a theme.

    Best practice: It is recommended to call the ApplyTheme function in the Application Open event and before any child window is opened.

    The theme path and name set by the ApplyTheme function takes precedence over those selected in the painter. See the following examples for illustration.

    Example 1:

    ApplyTheme ("Flat Design Blue")

    This script applies the "Flat Design Blue" theme (the theme name selected in the painter will be ignored) and reads the theme files from the following path:

    • At the development environment: the script reads the theme files from the Theme Path set in the painter.

    • At the production environment: the script reads the theme files from the "theme[version]" folder under the root of the installation directory of the application's executable file.

    Example 2:

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

    This script applies the "Flat Design Blue" theme and both the theme path and the theme name selected in the painter will be ignored:

    The script reads the theme files from "D:\App1SourceCode\themes\" at both the development environment and the production environment.

    Therefore, absolute path is not recommended at the production environment, considering the convenience of distribution.

    Example 3:

    ApplyTheme (".\themes\Flat Design Blue")
    ApplyTheme (".\..\themes\Flat Design Blue")
    ApplyTheme ("themes\Flat Design Blue")

    This script applies the "Flat Design Blue" theme and both the theme path and the theme name selected in the painter will be ignored:

    • At the development environment: the script reads the theme files from the path relative to the PBT file.

    • At the production environment: the script reads the theme files from the path relative to the root of the installation directory of the application's executable file.

    For more, see the section called “GetTheme” in PowerScript Reference and the section called “ApplyTheme” in PowerScript Reference.

To customize or create a theme:

  1. Locate the "theme[version]" folder in the "%Appeon%\Shared\PowerBuilder" directory.

    There are by default four sub-folders; each represents one type of UI theme: Flat Design Blue, Flat Design Dark, Flat Design Grey, and Flat Design Silver. You can add your own theme folder here.

  2. Make a copy of the theme sub-folder you want to customize.

    To permanently keep your settings, it is recommended that you make a copy of the theme folder and then make changes to the copy, instead of directly changing the system theme. The folder name will be automatically recognized as the theme name and listed for selection in the Themes tab.

    Note

    If you directly make changes to the system theme, the changes may lose after you re-install or upgrade PowerBuilder IDE.

    Each theme folder contains a bunch of image files which represent the state (checked, unchecked, indeterminate, enabled, disabled, hover, pressed etc.) of the controls, DataWindow and window and a "theme.json" file which is configurable for the theme settings (such as color, state, border, text etc).

  3. In theme sub-folder, edit the "theme.json" file to adjust the UI theme settings for the controls, DataWindow and window and save changes.

To make the theme effective:

  • Click the Run or Select and Run button on the PowerBar to run the application and review the UI effect of the selected theme.

    The UI theme takes effect only when the application is run, not at the design time or under preview.

    The following options in PowerBuilder IDE or the Windows operating system may prevent the selected theme working correctly:

    • The "Windows classic style" option in the PowerBuilder Project painter

      When you build the application in the Project painter, 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" theme in the Windows operating system

      When the application is run in the Windows system and if the Windows system theme is set to "Windows Classic", then the application UI will be rendered in the Windows Classic theme instead of the selected theme.

    • The "Use Windows XP style DPI scaling" option in Windows 7, Windows Server 2012, or earlier

      If the scaling percentage is set to 125% or lower, the "Use Windows XP style DPI scaling" option will be automatically selected, which will prevent the selected theme working correctly. In such case (125% or lower), you should manually uncheck the "Use Windows XP style DPI scaling" option.

To package the theme folder:

  • Manually copy the theme folder (just like the other resource files) to the specified path when creating the application installation package, so that the theme files will be installed along with the application and will be accessible to the application.

    • If you have not specified the path in the ApplyTheme function (and no matter if you have or have not specified any path in the painter), manually copy the "theme[version]" folder to the root of the application installation directory;

    • If you have specified the relative path in the ApplyTheme function, then manually copy the theme folder to the path relative to the root of the application installation directory;

    • If you have specified the absolute path in the ApplyTheme function, you should change to use no path or the relative path, and then copy the theme files according to the above instructions.

Understanding 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 after you apply the theme. You can set the node to false if you want to use the "no-theme" style for 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. See Understanding what additional features provided by the theme for the additional UI properties that you can set in the theme.json file.

Understanding what can be set by the theme

Since the application UI mechanism is very complicated, it is very important to understand what the new UI theme can achieve and cannot achieve before you decide to apply the new theme.

Windows and User Objects

General rule: Once a theme is applied, only the background color of window can be set by the theme.json file.

What can be set by the theme

  • Only the background color of window can be set 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, title bar, and scroll bar, on the window and user object.

  • The theme is not effective to the dockable window.

  • 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).

Workarounds

The following workaround takes User Object as an example. If a theme is applied, the background color of User Object is determined by the background color of window which is set in the theme.json file. If you want to set different background colors for User Object (or for window), you will have to disable the UI theme for User Object (or for window) first.

To disable the UI theme for User Object (or for window), change the value of "drawing" to false under "window" in the theme.json file.

"window":
 {
  "drawing":false,
  "background-color":"#FFFFFF"
 }
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 only; and the border (whether displays or not) depends on different controls.

What can be set by the theme

Background color and font Color:

  • The background color and the font color of controls is determined by the theme.json file.

Border:

  • The border of the following control is determined by their border property settings in the PowerBuilder IDE: InkEdit, InkPicture, SingleLineEdit, EditMask, MultiLineEdit, RichTextEdit, ListBox, PictureListBox, ListView, TreeView, Graph, and MonthCalendar. Dynamically setting the border property at runtime in the script will not take effect.

  • By default, StaticText has no border ("border"=0 in theme.json). If "border" is modified to 1 in theme.json, the border property setting in the PowerBuilder IDE takes effect.

  • By default, StaticHyperLink has no border ("border"=0 in theme.json), 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. If "border" is modified to 1 in theme.json, its border property in the PowerBuilder IDE takes effect.

  • The border of DatePicker, DropDownListBox, and DropDownPictureListBox is processed in the same way as before (in the original UI as well as the new UI theme, their border is always rendered, regardless of the border property setting in the IDE.)

  • TrackBar, CommandButton, PictureButton, CheckBox, RadioButton, ProgressBar, and GroupBox have no border property at all, so they will not be discussed here.

What cannot be set by the theme

  • The theme is not effective to Line, Oval, Rectangle, RowndRectangle, Picture, PictureHyperLink, and Animation.

  • The theme is not effective to the OLE control or ActiveX control.

  • RichTextEdit control is a third-party ActiveX control, so only the border of this control is configurable in the theme.json file.

  • 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.

  • The border style is always StyleBox!. The following border styles are unsupported: StyleLowered!, StyleRaised!, and StyleShadowBox.

  • The RightToLeft property is unsupported for RadioButton, CheckBox, DropDownListBox, and DropDownPictureListBox.

  • The LeftText property is unsupported for RadioButton and CheckBox.

  • The lines that connect the tree items in the TreeView control will not display, even though the HasLines property is enabled.

Workarounds

Take 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.

DataWindows

General rule: Once a theme is applied, the UI setting of DataWindow are determined by the expression or the Modify method first, or by the theme.json file; except for border and resizable settings which are determined by the setting in the PowerBuilder IDE first, or by the theme.json file.

What can be set by the theme

Background color and font color:

  • The background color and font color of Column, Text, Computed Field, and GroupBox controls are determined by the expression or the Modify method first, or by the theme.json file. The property settings in the PowerBuilder IDE take no effect.

  • For the Header of Grid and CrossTab DataWindows, the background of the Text control is transparent and the background color of the Header band is determined by the theme.json file.

Border:

  • The DataWindow border property is determined by the settings in the PowerBuilder IDE. Dynamically setting the border property at runtime in the script will not take effect.

  • 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 its border.)

  • When "border"=0 in theme.json, the border color will be rendered using the border color setting in theme.json and the border (whether to display or not) will be determined by the border property setting in the PowerBuilder IDE; and if the DataWindow border property is enabled in the PowerBuilder IDE, the border is rendered as StyleBox!.

  • When "border"=1 in theme.json, DataWindow will have StyleBox border, regardless of the border property setting in the PowerBuilder IDE.

  • When "border"=2 in theme.json, DataWindow will not have border, regardless of the border property setting in the PowerBuilder IDE.

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.

Presentation styles:

  • The controls in the DataWindow are configured respectively in the theme.json file, except for the Column, Text and Computed Field controls in the Grid and Crosstab DataWindow which are configured under the "grid-style" and "cross-style" in the theme.json file.

  • The DataWindow selected row is determined by the theme.json file, which are configured under the "cross-style" for the Crosstab DataWindow, or configured under the "grid-style" for DataWindows of other presentation styles.

What cannot be set by the theme

  • The theme is not effective to the DataWindow with the following presentation style: Label, Composite, OLE 2.0, and RichText.

  • The theme is not effective to the DataWindow title bar.

  • The theme is not effective to the 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 the definition in the Create statement), or changed later by the property expression in the PowerBuilder IDE or the Modify method in the script.

  • The color of the DataWindow band (except for the Header of Grid and Crosstab DataWindows) is not configurable in the theme.json file; it is determined by the settings in the PowerBuilder IDE.

  • When printing or saving the DataWindow as PDF file, the theme will not take effect, except for the Graph DataWindow.

  • The border style is always StyleBox!. The following border styles are unsupported: StyleLowered!, StyleRaised!, and StyleShadowBox.

  • The CheckBox and RadioButton control on a DataWindow Column will have no border.

  • The RightToLeft property is unsupported for RadioButton, CheckBox, and TreeView DataWindow.

  • The LeftText property is unsupported for RadioButton and CheckBox.

Workarounds

The following workaround takes the Text control for DataWindow as an example. If a theme is applied, the font color, background color, and border of Text is set in the theme.json file. If you want to set different background color for the Text controls in the header band and the detail band, you can set it in the expression or the Modify method.

In the expression:

string ls_create,ls_error
dw_1.dataobject = "d_test2"
ls_create = 'create text(band=detail alignment="2" text="create" border="2" color=" 65280~t 65280" x="100" y="200" height="116" width="485" html.valueishtml="0"  name=t_1 visible="1"  font.face="MS Sans Serif" font.height="-16" font.weight="700"  font.family="2" font.pitch="2" font.charset="0" background.mode="2" background.color=" 255~tif(1<>1,rgb(0,0,255),rgb(255,0,0))" )'
ls_error = dw_1.modify(ls_create)

In the Modify method:

ls_error =dw_1.modify("t_1.color=' 65280'")

Understanding what additional features provided by the theme

The new UI theme allows you to configure much more visual elements of the controls than before. For example, you can configure the grid line in the CrossTab and Grid DataWindows, or change the image for the box (of CheckBox), arrow (of DropDownListBox, EditMask etc.) etc. The following lists the additional UI properties which you can set in the theme.json file.

Grid line:

  • Configure the line and color for the grid line of CrossTab and Grid DataWindow (JSON node: "datawindow"->"cross-style" and "datawindow"->"grid-style").

Graph:

  • Configure the color for a graph (JSON node: "graph-colors").

Select row:

  • Configure the text color and background color for the selected row in the DropDown edit-style column in DataWindow (JSON node: "datawindow"->"dwo-column"->"dropdown-type").

  • Configure the text color and background color for the detail band of CrossTab and Grid DataWindow (JSON node: "datawindow"->"cross-style" and "datawindow"->"grid-style").

Images:

  • Configure the box for the CheckBox control and the CheckBox edit-style column in DataWindow (JSON node: "checkbox" and "datawindow"->"dwo-column"->"checkbox-type").

  • Configure the radio for the RadioButton control and the RadioButton edit-style column in DataWindow (JSON node: "radiobutton" and "datawindow"->"dwo-column"->"radiobuttons-type").

  • Configure the arrow for the DropDown edit-style column in DataWindow (JSON node: "datawindow"->"dwo-column"->"dropdown-type").

  • Configure the arrow for the DatePicker, DropDownListBox, and DropDownPictureListBox controls (JSON node: "datepicker", "dropdownlistbox", and "dropdownpicturelistbox").

  • Configure the arrow (up, down, and dropdown) for the EditMask control and the EditMask edit-style column in DataWindow (JSON node: "editmask" and "datawindow" -> "dwo-column" -> "editmask-type").

  • Configure the left and right buttons for the HScrollBar control (JSON node: "hscrollbar").

  • Configure the top and bottom buttons for the VScrollBar control (JSON node: "vscrollbar").

  • Configure the left, right, top, and bottom buttons for the Tab control (JSON node: "tab").

  • Configure the foreground and background color for the slider and the image for thumb in the HTrackBar and VTrackBar control (JSON node: "htrackbar" and "vtrackbar").

  • Configure the image for the check box and the expanded and collapsed buttons in TreeView (JSON node: "treeview").