HomePowerBuilderAppeon Documentation Center

SetHighDPIMode

Description

Sets the DPI (Dots Per Inch) awareness mode for the application.

Applies to

Application object

Syntax

applicationname.SetHighDpiMode (<HighDpiMode>)

Argument

Description

applicationname

The name of the application object in which you want to set the DPI mode.

HighDpiMode

An integer determines the DPI awareness mode to be used in the application.

  • 0 - None. No DPI awareness. This is the default value for applications upgraded from an earlier version.

  • 1 - DpiUnaware. This is the default behavior in Windows. It has the same effect as 0.

  • 2 - SystemAwareness. Uses system DPI at launch.

  • 3 - PerMonitor. Uses DPI of the monitor where the window is displayed.

  • 4 - PerMonitorV2. Enhanced per-monitor DPI awareness. This is the default value for new applications.

  • 5 - DpiUnawareGdiScaled. Uses GDI scaling.

For details about the awareness mode, refer to 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.


Usage

The SetHighDPIMode function must be called before any window is opened (for example, in the Application's Open event).

When the DPI mode is 0, you can call the SetHighDPIMode function to set the awareness mode.

When the DPI mode is already set to 1 - 5 (inclusive) (no matter it is set in the painter or by the SetHighDPIMode function), you cannot call the SetHighDPIMode function to change the mode. The SetHighDPIMode function calls will fail and return -1.

The SetHighDPIMode function configures the DPI awareness mode at application startup by invoking the Windows API (such as SetProcessDpiAwarenessContext). Its effect depends on two main factors:

  1. DPI Mode Priority

    DPI awareness can be configured through multiple mechanisms. When the application starts, Windows applies the setting with the highest priority according to the following order (highest to lowest):

    • Application executable properties (for example, DPI compatibility settings in the .exe file properties)

    • Application manifest file (the configuration file loaded during startup)

    • Windows API calls (such as SetProcessDpiAwarenessContext)

    If DPI awareness is already specified via a higher-priority method (executable property or manifest file), the configuration requested by SetHighDPIMode will be ignored.

  2. Operating System Support

    The SetProcessDpiAwarenessContext API is supported only on Windows 11 and later and Windows Server 2016 and later. On earlier versions of Windows, no DPI awareness mode will be applied, and the application will run in None (0) mode (not DPI-aware), which may result in blurry or improperly scaled UI elements.

For more information, refer to the section called “Enabling DPI Awareness”.

Return value

Integer.

Returns 1 if the mode is set successfully and -1 if it is not. If any argument's value is null, the method returns null.

Examples

The following code example reads the DPI mode from an INI file and then sets the mode for the application (the scripts should be placed in the Application's Open event, so they can be executed before any window is opened): 

// Suppose the HighDPIMode selected in the painter is 0 – None.
Int li_dpimode
Int li_rtrn

// Read the HighDpiMode configuration from an ini file.
li_dpimode = Integer(ProfileString("myapp.ini", "DPI", "HighDpiMode", "4") )

// Change DPI Awareness 
li_rtrn = GetApplication().SetHighDpiMode(li_dpimode)
If li_rtrn <> 1 Then
            Messagebox("SetHighDpiMode Failed: " + String(li_dpimode), String(li_rtrn))
End If

See also

GetDpiForWindow

Prev  Up  Next
SetHeight  Home  SetHttpRequestHeader