set-dpi-awareness

set-dpi-awareness Function

Summary

Sets the DPI awareness of the process when it starts a CAPI application.

Package

win32

Signature

set-dpi-awareness what

Arguments

what⇩

:none, :system or :monitor. The default is :system.

Description

The function set-dpi-awareness arranges for the DPI awareness of the process to be set just before it starts a CAPI application (or the LispWorks IDE) for the first time in the current invocation. This affects what happens when the process runs on a monitor with scaling different from 100%.

The meaning of what is as follows:

`:none`	The process is not aware of the DPI. Windows itself effectively causes all the drawing in the process to go to an internal bitmap, and then Windows scales the bitmap as needed ("bitmap scaling"). The result tends to be blurry and looks worse than proper scaling. This corresponds to the Windows constant `PROCESS_DPI_UNAWARE`.
`:system`	That means the process does proper scaling according to the system scaling at the time it starts the CAPI. If the scaling changes later, either because the system scaling changes or a window of the process is moved to another monitor with a difefrent scaling, then Windows performs a bitmap scaling to the new scaling. The result is that, as long as the scaling is fixed, the process's windows are scaled properly. Windows Controls (for example, list panels, text input panes) are scaled properly. Fonts are also scaled properly, which means that CAPI layouts that use constraints based on the number of characters (for example `:visible-min-width '(character 10)`), are scaled properly too. Images do not scale properly, and are drawn at their native size, which means that they will come out too small for scaling that is larger than 100%. You can check programmatically for scaling by using capi:screen-logical-resolution. The result of this on Windows is 96 multiplied by the scaling. For example, with scaling of 150% it returns 144. This corresponds to the Windows constant `PROCESS_SYSTEM_DPI_AWARE`.
`:monitor`	On startup, this is the same as `:system`, but when the scaling changes, Windows does not perform any bitmap scaling. This means that, if there is a change in the scaling after the process starts the CAPI, then the size of its windows will change. In principle. the process itself is responsible to change the size of its windows, but currently LispWorks does nothing. This corresponds to the Windows constant `PROCESS_PER_MONITOR_DPI_AWARE`.

The call to set-dpi-awareness just sets an internal state. The first time the CAPI starts, before dislpaying anything, LispWorks calls the Windows function SetProcessDpiAwareness with the appropriate constant. The internal state is preserved over saving and restarting a Lisp image.

Notes

If you need to call set-dpi-awareness, then it has to be done before starting the CAPI. For the LispWorks IDE, the normal way of doing that is to put a call to set-dpi-awareness in your initialization file (typically called .lispworks in your home directory). If you build a standalone application, you can just call set-dpi-awareness in the delivery script.

Repeated calls to set-dpi-awareness just change the internal state. Thus the behaviour of the process is determined by the last call before the CAPI starts.

The Windows function SetProcessDpiAwareness has no effect if the DPI awareness is already set in the current process. Therefore it is called only the first time the CAPI or the LispWorks IDE starts in a process, and it will not have any effect if something already set the awareness.

If you call set-dpi-awareness after starting the LispWorks IDE, it will have no effect in the running image. If you then save a session, it will still have no effect in the saving session, even though it stops and restarts the CAPI, but it will have an effect on the saved session itself when that is started.