Using Multi-Resolution Bitmaps

From RAD Studio
Jump to: navigation, search

Go Up to FireMonkey Application Design

FireMonkey is a multi-platform framework (Windows, iOS, macOS, and Android), and therefore FireMonkey applications work on devices having different screen densities and resolutions. Using FireMonkey multi-resolution bitmaps means that your images and icons in FireMonkey applications will appear correctly in different densities and resolutions (Windows, iOS, macOS, and Android). A multi-resolution bitmap is a collection of bitmap items providing the same image but having different scales.

Here we use the following terms:

  • Screen density: The quantity of pixels within a physical area of the screen; usually referred to as dpi (dots per inch). For example, a "low" density screen has fewer pixels within a given physical area, compared to a "normal" or "high" density screen.
  • Screen resolution: The total number of physical pixels on a screen. Screen density and screen resolution are measured in physical units - pixels.
  • Scale: FireMonkey always uses logical coordinates and logical sizes. Working with multi-resolution bitmaps, FireMonkey estimates relations between logical units and physical units using the Scale property.

Let us discuss the Scale property. For example, Apple uses the Retina display (2880×1800 pixels), which doubles the density and resolution of non-Retina displays. As a result, to submit your application to the Mac App Store, the icon set file must include an icon with a resolution of 512×512 pixels, for non-Retina displays. Let us say that we use the Scale = 1 for this icon. For Retina displays, you should add an icon with a resolution of 1024×1024 pixels. If both these icons have the same logical size in FireMonkey, then for the 1024×1024 icon FireMonkey should use the Scale = 2. So we use different Scales to provide different numbers of physical pixels to images having the same logical sizes in FireMonkey tools.

For the macOS and iOS platforms, it is reasonable to provide at least two scales: 1 and 2. Since a screen resolution is the hardware property of particular screens, platforms having a rich set of different type devices with different resolutions can require a more extended set of scales. For example, the Android platform can require scales 1, 1.33, 1.5, 2, and others.

The base class for multi-resolution bitmaps is TCustomMultiResBitmap. TCustomBitmapItem is the base class for bitmap items in TCustomMultiResBitmap collections.

Multi-resolution bitmaps are used in the following components:

  1. In TImage controls.TImage controls keep a TFixedMultiResBitmap multi-resolution bitmap in the MultiResBitmap property. TFixedMultiResBitmap is the descendant of TCustomMultiResBitmap. A TFixedMultiResBitmap multi-resolution bitmap can contain any number of bitmap items having different scales. On each device, TImage retrieves the most appropriate bitmap to display from the bitmap collection in the TFixedMultiResBitmap multi-resolution bitmap and refers to the obtained bitmap with the Bitmap property. The obtained bitmap depends on the device resolution and scales of bitmap items kept in the TFixedMultiResBitmap multi-resolution bitmap. If a multi-resolution bitmap does not contain a bitmap item having exactly the scale required by some particular screen, then FireMonkey automatically stretches or zooms out the bitmap item having the most appropriate scale. For information about how this bitmap is obtained, see Bitmap. Keep in mind that each bitmap item takes resources of the application's executable on all platforms (even if some bitmap item is never used on a particular platform).
  2. In TImageList image lists. Image lists provide full-featured tools for using centralized collections of small images by GUI elements (controls, menus, and others) in your FireMonkey applications. Image lists use multi-resolution bitmaps to represent source images from which image lists generate final images that can be shown. The generated final images are also represented as multi-resolution bitmaps. See Using TImageList Image Lists as Centralized Collections of Images
  3. In the IGlyph interface. IGlyph declares the basic methods and properties used to manage lists of images. Many components, like TCustomButton, TCustomListBox, TTabControl, TTreeViewItem, TMenuBar, and others, support the IGlyph interface and, therefore, can use multi-resolution bitmaps.
  4. In TGlyph controls. TGlyph controls support the IGlyph interface and, therefore, implement methods and properties used to manage lists of images. TGlyph declares as published the Images, ImageIndex, and AutoHide properties to be able to edit them in the Object Inspector. Images references a TCustomImageList image list and ImageIndex identifies the particular image in this list. The image is scaled to fully fit into the control area. The TGlyph element is included in most styled controls (TButton, TTabControl, TMenuItem, and others).

Use the MultiResBitmap Editor to create the TFixedMultiResBitmap multi-resolution bitmaps.

Bitmap items in TFixedMultiResBitmap multi-resolution bitmaps have the TFixedBitmapItem type. TFixedBitmapItem bitmap items have the Fixed property. Bitmap items with Fixed = True are mandatory items. By default, each multi-resolution bitmap contains at least one mandatory (default) bitmap item having the Scale = 1 and the name Normal. In the MultiResBitmap Editor you cannot delete mandatory bitmap items or change the Scale of mandatory bitmap items. You can extend the list of mandatory bitmap items (and scales) using the global RegisterScaleName method.

See Also