Users Guide
Specifying a theme for the application UI

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 %AppeonInstallPath%\PowerBuilder [version]\IDE\theme and this is where the system themes and custom 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" 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\theme). 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 app's executable file is run): use the "theme" folder under the same location of the application's executable file.

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

   • Theme -- 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 Blue (SVG), Flat Design Dark, Flat Design Dark (SVG), Flat Design Grey, Flat Design Silver, Flat Design Lime, and Flat Design Orange. These 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 (for more, refer to Custom themes).

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

Instead of specifying the theme to use in the Additional Properties of the application object, you can set a theme dynamically in the script using the ApplyTheme method. The theme path and name set by the ApplyTheme function takes precedence over those selected in the painter.

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

  Best practice: 1) It is recommended to call the ApplyTheme function in the Application Open event and before any child window is opened. 2) You can add a dialog box to the application, where you provide end users the theme options to select by themselves.

  You can specify no path, a relative path, or an absolute path (not recommended) in the function.

  When specifying no path:

  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" folder under the same location of the application's executable file.

  When specifying a relative path:

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

  This script applies the "Flat Design Blue" theme (both the theme path and the theme name selected in the painter will be ignored) and reads the theme files from the path relative to the location of the PBT file (or the application's executable file).

  When specifying an absolute path (not recommended):

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

  This script applies the "Flat Design Blue" theme (both the theme path and the theme name selected in the painter will be ignored) and reads the theme files from "D:\App1SourceCode\themes\" at both the development environment and the production environment.

  Note: absolute path is not recommended, because when it goes to the production environment, it would be difficult to ensure the absolute path exists on every client machine.

  You can get the theme that is currently applied to the application using the GetTheme function.