Requires: GfaWinx.lg32
Sets the DPI awareness for the current thread.
oldContext% = DpiAwareness( [Context%] )
| oldContext% | : ivar |
| Context% | : iexp |
The function sets the dpi-awareness for the current thread and the windows opened after issuing DpiAwareness. The function returns the 'old context' or zero in case of an error. In fact, the return value holds some pointer to a private memory structure containing the old context. The 'old context' return value can be used as an input parameter with DpiAwareness to reset the dpi awareness when the program ends.
When the DpiAwareness returns zero the dpi awareness is not set and the program will run in whatever dpi-awareness context the IDE is running. DpiAwareness is a wrapper for the SetThreadDpiAwarenessContext() API and there can be two reasons for failure of this function:
In both cases the dpi-awareness isn't set or changed.
The Context% argument is optional and may be omitted and the dpi-aware mode will be set to the mode 'per monitor aware V2'. The Context% argument can have the following values (the constants are declared in winuser.inc.lg32):
DPI_AWARENESS_CONTEXT_UNAWARE (-1)
DPI_AWARENESS_CONTEXT_SYSTEM_AWARE (-2)
DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE (-3)
DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 (-4)
DPI_AWARENESS_CONTEXT_UNAWARE_GDISCALED(-5)
The default value for Context% is DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2. For more information on these values see: DPI_AWARENESS_CONTEXT handle (windef.h) - Win32 apps | Microsoft Docs.
After setting the dpi-awareness the program starts receiving WM_DPICHANGED messages when the dpi of the window's display changes. For instance, when a form is moved from one screen to another where the screens have different DPIs. See WM_DPICHANGED in this help for more information.
Note 1: After initializing the form, but before showing, either call FormScaleForDpi or send the WM_DPICHANGED message to the form (SendMessage Me.hWnd, WM_DPICHANGED,0,0).
Note 2: The preferred way to start a dpi-aware application is by using the Dpi Aware App template from the File | New menu item.
See WM_DPICHANGED.
The GB program is executed in the context of IDE's thread. After using DpiAwareness the IDE is set to the new DPI as well, but it is not affected and will not receive WM_DPICHANGED messages because DpiAwareness affects only the windows opened after invoking the command. The IDE's dpi-awareness is restored by the IDE (actually gfawin32.gll) after the GB32 program ends (normally or abnormally with an error); this requires GB32 version 2.581 or later and Windows 10, version 1803. If you are using Windows 10, version 1607, the Dpi is saved but not restored leaving the IDE in the dpi-awareness state set with DpiAwareness(). In this case, be sure to reset the dpi-awareness after leaving the main loop by passing DpiAwareness() the old context returned by the initial call.
For more information about SetThreadDpiAwarenessContext() API see SetThreadDpiAwarenessContext function (winuser.h) - Win32 apps | Microsoft Docs.
For more information on developing dpi-aware applications see the Microsoft blog: High DPI Scaling Improvements for Desktop Applications and "Mixed Mode" DPI Scaling in the Windows 10 Anniversary Update (1607) - Windows Developer Blog.
WM_DPICHANGED, ScaleToDpi, ScaleXYWHToDpi.
{Created by Sjouke Hamstra; Last updated: 03/03/2022 by James Gaite}