For applications developed using raw Win32 programming or Windows Forms (such as PowerBuilder applications), Microsoft offers the following modes for automatic DPI scaling management. For more detailed information, please refer to Microsoft's documentation: https://learn.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows and https://learn.microsoft.com/en-us/windows/win32/hidpi/dpi-awareness-context.
-
DPI Unaware
-
System DPI Awareness
-
Per Monitor (V1) DPI Awareness
-
Per-Monitor (V2) DPI Awareness
-
DPI Unaware GDI Scaled
For applications developed in PowerBuilder 2022 R3 or earlier or upgraded to PowerBuilder 2025, the "DPI Unaware" mode will be automatically used, which means, Windows will bitmap stretch the UI of these applications when the DPI changes, which may result in a blurry or pixelated appearance.
For applications developed in PowerBuilder 2025 or upgraded to PowerBuilder 2025, the "Per-Monitor (V2) DPI Awareness" mode (4 - PerMonitorV2) is recommended, because PowerBuilder 2025 has specifically optimized its DPI-aware scaling algorithm to support this mode.
Note
PowerBuilder IDE does not support DPI scaling. When you run the application from the PowerBuilder IDE, the DPI mode has no effect to the application UI. To view the effects, you need to compile the application as an executable file. To do this:
1) Open the application object painter, go to the application's Properties view, select PerMonitorV2(4) --- Default from the HighDpiMode property listbox, and then compile the application as an exe file.
2) Run the application executable file, and then change the Windows scaling size.
3) Every time when you change the Windows scaling size, restart the application and then verify that the text and controls remain clear and appropriately sized.
Note
The DPI mode is not well supported in the multi-monitor environment. For more, refer to Unsupported features.
When the Per-Monitor (V2) DPI Awareness mode is used, the DPI scaling will be handled by both PowerBuilder and Windows OS, to ensure all Ul elements will automatically scale proportionally according to Windows' scaling settings.
PowerBuilder 2025 will handle DPI scaling for the following:
-
PowerBuilder windows
-
PowerBuilder native controls
-
Any other Ul elements that are not handled by Windows OS.
Windows OS will handle DPI scaling for the following:
-
Automatic non-client area (window caption, scroll bars, etc.)
-
Win32 dialogs (e.g. from PowerBuilder MessageBox)
-
Theme-drawn bitmap assets in common controls (checkboxes, button backgrounds, etc.)
Note
For other DPI scaling modes, PowerBuilder 2025 provides no optimization or intervention. If you select these modes, your PowerBuilder application will rely entirely on Windows for automatic scaling. Please run comprehensive testing to ensure that the scaling results meet your expectations.
The DPI scaling mode must be set before any window is opened. You can set the mode either in the IDE painter or in the scripts:
-
In the IDE painter
Open the application object painter, go to the application's Properties view, select a value from the HighDpiMode property listbox. The value can be one of the following: 0 - None, 1 - DpiUnaware, 2 - SystemAwareness, 3 - PerMonitor, 4 - PerMonitorV2 (Default), and 5 - DpiUnawareGdiScaled.
The HighDPIMode property can only be set in the IDE. It cannot be set in the script; but you can get its property value in the script.
-
In the scripts
The Application SetHighDPIMode function must be called before any window is opened (for example, it can be called in the Application's Open event). Once the mode is set successfully to any value between 1 and 5 (inclusive) (either in the IDE or in the scripts), it cannot be changed any more; the subsequent SetHighDPIMode function calls will fail and return -1.
Note
For all desktop applications (including PowerBuilder applications), the DPI scaling mode can be set in several ways and will take effect in the following order: application executable property (①) > manifest file (②) > Windows API (③).
The PowerBuilder HighDPIMode property and SetHighDPIMode function call the Windows API (③) to set the awareness mode, therefore please notice the following:
1) If the mode is set successfully in the application executable property (①) or manifest file (②), the PowerBuilder HighDPIMode property and SetHighDPIMode function will not take effect.
2) The Windows API (to be specific, SetProcessDpiAwarenessContext) (③) will work only in Windows 10 (version 1703) or later and Windows Server 2016 or later; in the other Windows OS, no mode will be set (the application will run in the None(0) mode).
While the Per-Monitor (V2) DPI Awareness mode can ensure the clarity of text and controls, there are still certain features that are not fully supported or optimized:
-
Dynamically changing the DPI scaling is NOT supported, and moving the application across screens with different DPI scaling is also NOT supported.
If the DPI scaling is dynamically changed while the application is running, you will have to restart the application otherwise the UI will not scale properly (the window size may change unexpectedly, and the size of UI elements such as buttons, DataWindows, fonts etc. may increase or decrease incorrectly).
Likewise, when moving the application between screens with different DPI settings, the same kind of issues exist.
-
Images
The application bitmap image is stretched to the expected physical size. High-definition system images are not yet provided, making original images blurry after increasing the scaling ratio. For example, the arrows in some controls, check marks in the checkboxes, RibbonBar, etc., will appear blurry after increasing the scaling ratio.
Vector images (e.g. SVG) are not yet supported (they are planned for future versions).
-
Some controls are rendered partially by PowerBuilder and partially by Windows.
For example, toolbar text in non-client areas may appear unclear. In some virtual machine environments, Windows OS may occasionally have issues rendering images in CheckBox\RadioButton.
Solution: Applying a theme can often work around these issues, as PowerBuilder will handle the rendering. If the customer applies a "theme" or uses a contemporary style toolbar, PowerBuilder will render the toolbar.
Tip: If using PerMonitorV2 on Windows 10, ensure the "Fix scaling for apps" option is checked (Right-click desktop -> Display Settings -> Scale and layout -> Advanced scaling settings -> Fix scaling for apps -> Let Windows try to fix apps so they’re not blurry. This option is checked by default on Windows 10). Some controls' sizes are handled by Windows, and if "Let Windows try to fix apps so they’re not blurry" is not checked, the control sizes will not scale automatically.
-
The measurement unit Pixel used in scripts may not calculate properly.
If you use pixel values in the application, note that pixel values will change significantly at high DPI because it will use the real monitor pixel in PerMonitorV2. Check and adjust the corresponding code, as well as some PowerBuilder control events that pass pixel value parameters. Currently, no auxiliary classes are provided to help users with these calculations.
-
UI rendered by Windows APIs or UI frameworks is not supported.
PowerBuilder cannot optimize the UI elements that are rendered by the Windows APIs or UI frameworks. You will need to implement support of high DPI for these UI elements by yourself.
-
Proportional scaling of non-TrueType fonts is not supported.
If controls use non-TrueType fonts, the fonts and controls may not scale in the same ratio, causing visual discrepancies (e.g., text may not fully display within controls).
Solution: Most fonts are TrueType, but some legacy projects may use non-TrueType fonts. Adjusting the font can bypass this issue.
