UserGuide

Web HiDPI Support

From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

Xojo supports high dots per inch displays for web apps. Apple calls these displays "Retina Displays", but the generic term is HiDPI. For most of your web apps, you will likely only need to turn on the Supports Hi-DPI switch in the Inspector for the Shared Build Settings to enable your app to support HiDPI displays. When you do this, all UI elements will take advantage of HiDPI displays.

Overview

Enable HiDPI support for your web apps by turning on the "Supports HiDPI" property in the Shared Build Settings Inspector of the web project.

Use Image Sets to add multi-resolution images to your projects. Multi-resolution Images are now available in Web Projects. Just like iOS and Desktop projects, you can now use Image Sets to contain multiple representations of the same image and the Web Framework will automatically deliver the correct version to the browser.

Image Sets

Image Sets contain multiple size representations of the same image. The Web Framework automatically delivers the correct size to the browser.

An Image Set project item can contain pictures at three different scales: 1x, 2x and 3x. All images must have the same aspect ratio. For example if your 1x image is 64x64 @ 72DPI, then the 2x image must be the same ratio (1:1) and would typically be 128x128 @ 72DPI or 64x64 @ 144DPI. Make sure that that the tool you use to create or edit your images properly sets the image DPI (dots per inch). Some tools (such as Photoshop) do not properly set the DPI which can cause Xojo to interpret the image as the wrong size.

You can add Images to your projects by adding an Image Set from the Insert menu: Insert ↠ Image.

When the Supports HiDPI property is turned ON, dragging a picture file to the project creates an Image Set. When it is OFF, dragging a picture to the project adds it as a Picture. If you want to add a picture to an Image Set when Supports HiDPI is OFF, first add the Image Set to the project and then drag the picture file to the appropriate 1x, 2x or 3x slot. The 3x image is not typically needed at this time.

Picture files added to the project in Image Sets are treated as Images.

Picture files in your existing projects are treated as 1x and will be scaled as necessary. Should you want to update your projects with multiple sizes for your pictures, you would create an Image Set with the same name as the original picture and add images to the 1x, 2x and 3x slots as necessary. Your code that refers to these images will continue to work without changes since the name used for the picture now refers to the Image Set.

Framework API Changes

WebPicture

Constructor(width As Integer, height As Integer, files() As FolderItem)

Creates a multi-resolution image from picture files on the drive. It creates a file-based WebPicture which saves on memory and is only loaded/delivered to a browser when it is requested.

WebImageViewer, WebCanvas and WebToolbar have all been updated to use the new WebPicture format and deliver high resolution images to browsers that support them.

WebSession

Property ScaleFactor As Double

Returns the ScaleFactor of the current session.

Event ScaleFactorChanged

Called if/when the user moves their browser between screens if the ScaleFactor has changed. Note: The built-in controls automatically request new images when ScaleFactor changes.

WebControlWrapper

Event ScaleFactorChanged

Called in conjunction with the WebSession.ScaleFactorChanged event of the WebSession to which the control belongs.

Other Changes

  • Pictures dragged into your projects (whether directly or as part of an Image) are now exported to disk, placed in the Resources directory and loaded dynamically at runtime.
  • High-resolution versions of all of the graphics that make up the built-in web controls are now automatically included with your built apps.

See Also