Images

The Xwt.Drawing.Image class can be used to load, transform and render images. The Image class can represent different kinds of images:

• Bitmaps
• Icons (a set of images in different sizes)
• Vector images

XWT can only load bitmaps from files, but vector images and icons can be created using the XWT API.

Loading Images

Images can be loaded using several static methods available in the Image class:

• FromFile
• FromStream
• FromResource

In addition, the Xwt.Drawing.ImageBuilder class can be used to create a new bitmap or vector image using the drawing API.

Choosing the Size of an Image

Bitmap images have a fixed and unique size, but vector images and icons can have several sizes. Before rendering an image (and often when assigning an image to a widget, such as an ImageView) you have to make sure the image has a specific size. To select the size of an image, you can use the WithSize() method:

Image image = ... // Got an image
var smallImage = image.WithSize (16, 16);

The WithSize(16, 16) call returns a copy of the image that has a size fixed to 16x16. Notice that this method does not make a copy of the underlying physical image, it just creates a new Image wrapper with a fixed size, so it is a very lightweight operation.

This method can also be used to scale bitmaps, and it is still a lightweight operation since the bitmap is not really physically scaled. WithSize simply sets the size that has been chosen for rendering.

Image sizes are always specified and provided in logical pixels.

## Modifying the Transparency of an Image

The method WithAlpha() from the Image class can be used to select the transparency to be applied to an image. It works like WithSize(): the method returns a copy of the Image object with the specified transparency applied, but it doesn't make a copy of the physical image, so it is a lightweight operation. The alpha value is recorded and used only at rendering time.

Multi-resolution Images

XWT has support for multi-resolution images. It means that a single Image object can contain several versions of the same image in different resolutions. When rendering the image, XWT chooses the best image version, based on the resolution of the target surface.

For example, you may have an image of logical size 16x16 with 2 resolutions: single resolution (where 1 logical pixel = 1 physical pixel) and double/retina resolution (where 1 logical pixel = 2 physical pixels). In that case, the Image object would be represented by 2 bitmaps with a size of 16x16 and 32x32 physical pixels. The correct bitmap would be selected at rendering time.

Images with multiple resolutions are not to be confused with images with multiple sizes (icons). An image with multiple resolutions has a single logical size, and the fact that the image is internally represented by bitmaps with different physical sizes is completely transparent to the user of the Image.

On the other hand, icons (when composed by several images) don't have a single logical size. Before using them, the size has to be specified using the WithSize method, like you would do for vector images. However, notice that icons can be composed by multi-resolution images. For example you could have an icon composed by 2 images of 16x16 and 32x32 with single and double resolution, in which case the Image object would internally have 4 bitmaps with the following physical pixel sizes:

• 16x16 (logical size 16x16, single resolution)
• 32x32 (logical size 16x16, double resolution)
• 32x32 (logical size 32x32, single resolution)
• 64x64 (logical size 32x32, double resolution)

Although the icons has two 32x32 bitmaps, those are usually different bitmaps since they need to show different levels of detail.