Support for High-DPI Displays
Q: What do I need to do in order to support high-DPI displays? Do you have tips to convert old projects?
A: For more than two decades, traditional computer displays had a display density of less than 100 pixels per inch (DPI, or PPI). Reasoning in terms of 96-DPI displays was widespread and worked well until higher-density displays became pervasive. "Retina"-class notebooks and tablets and "4K" and "5K" desktop monitors pushed the density into the 200-DPI range, while at the same time mobile devices already exceeded 500 DPI.
Pervasive high-DPI support was added to the MenuBox 6 series, while preserving backward-compatibility with existing projects. 96-DPI units continue to be used to indicate the intended size of objects.
Built-in features which are provided transparently by MenuBox include:
- Per-system and per-monitor DPI awareness and scaling
- Refresh on display rotate, dock, undock, resume, etc.
Older versions of MenuBox (i.e. before version 6.0) are not DPI-aware. Their windows are rescaled automatically by Windows on high-DPI displays. The entire result (including text) may appear a bit "blurry".
Existing text-mode projects running on MenuBox 6 do not require changes in order to render with high-DPI title and content texts. Background images, however, are scaled by MenuBox (using a high-quality algorithm) and may lack detail on high-DPI modes unless they are provided in a larger format.
The following changes are recommended for legacy text window mode projects:
- Keep a note of the width and height of the original background image (BackgroundImage key). This size will continue to be referenced where 96-DPI units are used (e.g. in the Height or Width key).
- Create a new high-resolution background image that is exactly two or four times the dimensions of the original image. Save it as BMP (like in previous MenuBox versions) or PNG or JPEG (these two new formats require Windows 2000 or higher when running on the client side).
- Reference the updated background bitmap in the BackgroundImage key, appending the new "Fill" argument after the file name (separated by a comma). This new argument is required because unlike in previous versions the size of the image bitmap does not provide information about the intented rendering size.
- Set the original (96 DPI) value for either the Height or Width, but not both. The missing dimension will be auto-calculated at runtime by MenuBox, based on the image dimensions and the display density. This runtime procedure is pixel-exact and avoids possible rounding differences.
For HTML window mode projects:
- Set the new DPIAware key to True if your HTML content is DPI-aware. This new key, which is under the [HTMLWindow] section, is specific to HTML window mode projects (it does not exist in text window mode projects).
- DPI-aware content can query the screen.deviceXDPI and screen.deviceYDPI DOM properties to obtain information about the current display.
- If the DPIAware key is not set, or if it is set to False, then MenuBox will scale the content (similar to a browser magnify), assuming it was designed for the canonical 96-DPI size. On high-DPI displays texts will be crisp, but images may be a bit blurry.
- The window Width and Height arguments remain expressed at the canonical 96-DPI units, and do not need to be changed.
For all projects (both text and HTML window), if the original window icon (ICO file) only included a 16x16 bitmap, add at least the 24x24, 32x32 and 48x48 variants. On higher-density displays even a 256x256 image, if included, may be used for task switching (e.g. ALT+TAB) purposes.
It is safe to link to this page.