-
Notifications
You must be signed in to change notification settings - Fork 241
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)
- Stock icons
- Vector images
- Custom drawn images
XWT can only load bitmaps from files, but vector images and icons can be created using the XWT API.
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.
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.
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.
An icon is an image that may need to be shown in different sizes, so it is composed by several images of different sizes. Like vector images, icons don't have a fixed size, the size has to be explicitly set before the image can be rendered. XWT doesn't support loading icons from files, icons can only be created using the static method CreateMultiSizeIcon from the Image class.
The Xwt.StockIcons class provides references to common icons. Those icons are platform-specific and are usually provided in different sizes.
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 icon has two 32x32 bitmaps, those are usually different bitmaps since they need to show different levels of detail.
XWT automatically loads high-resolution versions of an image when it is available. For example, when loading an image from a file named "foo.png", XWT will look for a file named "foo**@2x**.png" at the same location. If the file is found, that image will be loaded as a double resolution version of the image.
High-resolution images are automatically loaded by the Image.FromFile() and Image.FromResource() methods.
The Xwt.Drawing.ImageBuilder class can be used to create a vector or bitmap image using the XWT drawing API. Here is an example:
var builder = new ImageBuilder(50, 50);
var ctx = builder.Context;
ctx.Arc (25, 25, 25, 0, 360);
ctx.SetColor(Colors.Black);
ctx.Stroke(); // Draw a circle
...
var vectorImage = builder.ToVectorImage(); // Generates a vector image
var bitmap = builder.ToBitmap(); // Generates a bitmap
In this example the ToVectorImage() will return a vector image with a default size of 50x50, although it can be scaled without losing resolution. The bitmap returned by ToBitmap() will have a size of 50x50 at single resolution (there are other overloads which allow getting the bitmap in other resolutions).
A custom drawn image can be created by creating a subclass of Xwt.Drawing.DrawingImage and overriding the method OnDraw (). The OnDraw method will be called every time the image needs to be rendered.