Description
Applies a theme to the current application UI. This method should be called when all windows are closed, in order for windows and controls to take effect.
Syntax
ApplyTheme ( String theme )
|
Argument |
Description |
|---|---|
|
theme |
A string whose value is the theme name (or theme path and name) you want to apply to the current application. The theme path is optional. If not specified, the default value is "%AppeonInstallPath%\PowerBuilder [version]\IDE\theme" when the app is run from the IDE (at the development environment), and the default value is the "theme" under the root of the application installation directory when the application's executable file is run (at the production environment). If specified, it can be an absolute path or a relative path; and cannot be a UNC path (for example, "\\172.16.0.1\theme\Flat Design Blue" is unsupported). The relative path is relative to the PBT file at the development environment; and relative to the root of the installation directory of the app's executable file at the production environment. The theme name should be the sub-folder name under the specified theme path or the default path that contain the files for the theme, therefore the sub-folder name represents the theme name. 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. |
Return value
Integer. Returns 1 if it succeeds and -1 if it fails. If any argument's value is null, the method returns null.
Usage
The ApplyTheme method should be called when all windows are closed, for example, it can be called in the Application Open event when all of the child windows are not yet opened.
The theme path and name set by the ApplyTheme function takes precedence over those selected in the PowerBuilder painter. See the following code examples for illustration.
The ApplyTheme method is effective to the window, DataWindow, and all visual controls in your current application, except Line, Oval, Rectangle, RoundRectangle, Picture, PictureHyperLink, and Animation.
Once you apply a theme to the application, you should not select the Windows classic style option in the System Options and/or project painter, otherwise, the application UI will be rendered in the Windows classic style instead of the selected theme.
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 Server 2012 will be automatically selected, if the scaling percentage is set to 125% or lower. This will prevent the selected theme working correctly. In such case, you should manually uncheck the "Use Windows XP style DPI scaling" option.
If the current operating system is Windows Server 2003, 2008, or 2008 R2 (or if the "Windows classic style" option is selected when building the application), the ApplyTheme function will not take effect and will return -1.
The ApplyTheme method can apply a theme, but it cannot turn off a theme. To turn off a theme, you should remove the ApplyTheme method (as well as the theme settings in the PowerBuilder painter), and then restart the application for the change to take effect. Or create a custom theme that has {“drawing”:false} for every control type, and use this theme in the ApplyTheme method.
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.
Example 1
This example applies the "Flat Design Blue" theme (the theme name selected in the painter will be ignored).
When the app is run from the IDE, the script reads the theme files from the Theme Path set in the painter; when the app's executable file is run, the script reads the theme files from the "theme" folder under the root of the application installation directory.
ApplyTheme ("Flat Design Blue")Example 2
This example 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\" no matter when the app is run from the IDE or when the app's executable file is run.
ApplyTheme("D:\App1SourceCode\themes\Flat Design Blue")Example 3
This example applies the "Flat Design Blue" theme and both the theme path and the theme name selected in the painter will be ignored.
When the app is run from the IDE, the script reads the theme files from the path relative to the PBT file; when the app's executable file is run, the script reads the theme files from the path relative to the root of the application installation directory.
ApplyTheme(".\themes\Flat Design Blue")ApplyTheme(".\..\themes\Flat Design Blue")ApplyTheme("themes\Flat Design Blue")See also
Specifying the UI theme for the application in Users Guide
