Using Views: Image

The Mosaic class Views::Image implements a graphical object specialized to display a single image. This so-called Image view can be used to compose the appearance of a GUI component, in particular to add icons, symbols or any kind of image decoration to it. The following screenshot demonstrates few examples of how Image views appear in the canvas area of Composer (and accordingly on the screen in your target device):

The following sections are intended to provide you an introduction and useful tips of how to work with the Image view. For the complete reference please see the documentation of the Views::Image class.

Add new Image view

To add a new Image view just at the design time of a GUI component do following:

First ensure that the Templates window is visible.

In Templates window switch to the folder Views.

In the folder locate the template Image.

Drag & Drop the template into the canvas area of the Composer window:

Eventually name the new added Image view.

Inspect the Image view

As long as the Image view is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below:

This is in so far worth mentioning as all following sections describe diverse features of the Image view by explicitly referring to its corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

Arrange the Image view

Once added, you can freely move the Image view, or you simply grab one of its corners and resize it in this way. You can control the position and the size of the view also by directly modifying its property Bounds. If you want the Image view to appear behind other views you can reorder it explicitly.

Specify the bitmap for the Image view

The content to display within an Image view is determined by its property Bitmap. Usually, you initialize this property with the name of an existing bitmap resource member, which is typical for all immutable contents like button icons, screen backgrounds and any other decorations well known already at the design time. With the Inspector Assistant you can conveniently select the right resource when you edit the initialization expression for the property Bitmap.

From technical point of view, you can initialize the property Bitmap with any instance of a class descended from the Mosaic class Resources::Bitmap. In particular, you can use an instance of the Resources::ExternBitmap class if you want to display bitmap contents, you have e.g. received just at the runtime. Or you render the bitmap dynamically into a Graphics::Canvas object and assign it to the Image view.

Please note, every new added Image view uses the Resources::DefaultBitmap bitmap resource as place holder to display something on the screen. In addition to it, Embedded Wizard Studio provides a set of default bitmap resources with icons for typical application cases. They are intended to help you when you start to create a prototype of your new product.

Align, scale or stretch the bitmap within the Image view

Per default, the Image view displays the bitmap centered within the area determined by the property Bounds. If the bitmap is larger than the available area, the parts lying outside the area are simply clipped and are not visible.

If desired, with the property Alignment you can determine other behavior how the Image view should react when its size and the size of the displayed bitmap are different. In particular, you can align the bitmap at the edges of the Image view or you can instruct the view to proportionally scale or even stretch the bitmap so it fits within the available area. The following figure demonstrates few examples of how the initialization of the property Alignment affects the image layout (the gray borders indicate the view areas):

Please note, if your target device doesn't provide any dedicated graphics hardware for bitmap scale operation, the operations are performed by the CPU, which may impact the performance of your application significantly if you use this feature extensively.

Rotate the bitmap within the Image view

With the property Orientation you can determine the rotation of the displayed bitmap in steps of 90 degrees (0, 90, 180 and 270 degrees). The following figure demonstrates how the initialization of the property Orientation affects the image layout (the gray borders indicate the view areas):

Modifying the Orientation property has also an effect on how the bitmap is aligned within the view's area. For example, if you have configured the Image view to align the bitmap at its top-left corner and then you rotate the bitmap 90 degrees counterclockwise, the bitmap will in fact appear aligned to the bottom-left corner of the view. The following figure demonstrates it (the gray borders indicate the view areas):

In such case the simplest is you consider the specified alignment constraints as being relative to the edges of the bitmap itself instead of the edges of the Image view. Accordingly, regardless of how you initialize the property Orientation, a left aligned bitmap will stick at its original left edge.

Please note, if your target device doesn't provide any dedicated graphics hardware for bitmap rotate operation, the operations are performed by the CPU, which may impact the performance of your application significantly if you use this feature extensively.

Scroll the bitmap within the Image view

Besides the possibility to align the bitmap within an Image view you can also scroll it pixel-wise. For this purpose use the property ScrollOffset. You can determine the vertical and the horizontal displacement individually. With positive values the bitmap is scrolled right/down. With negative values left/up. For example (the gray borders visualize the view areas):

Configure the Image view to adjust its size automatically

With the property AutoSize you can instruct the Image view to automatically adjust its size and eventually its position when new bitmap is assigned or the already associated bitmap changes its size. In other words, the Image view will assume the size of the displayed content.

You can combine AutoSize with the alignment options. For example, if you have configured the Image view to align the bitmap at its bottom-right corner, assigning new bitmap will move the left and top edges of the view by maintaining the bottom-right corner fixed. This is demonstrated in the following screenshot (the gray borders visualize the view area):

Since with AutoSize mode enabled the Image view assumes automatically the size of the assigned bitmap, scaling or stretching of the bitmap is not useful in such case.

Control the bilinear filtering

Bilinear filtering is a technique to smooth an image when it is scaled or stretched. The problem: through the distortion, the center of a pixel in the resulting image does not necessarily correspond to the center of a pixel in the original content. The simply copying of the pixel color value results then in an ugly image with rough pixel steps. The bilinear filter helps to improve the results by interpolating the color values of the pixels lying around the mapped position.

The usage of the bilinear filter is controlled by the property Quality. Per default the filter is enabled. By initializing Quality with the value false you can deactivate it again. The following figure demonstrates the results depending on the current setting of the property:

TIP

Despite the advantages, you should consider, that with the bilinear filter the bitmap operations are more computing intensive. Thus, if your target device is not powerful nor doesn't provide any dedicated graphics hardware and the Image view scales or stretches the image, deactivating the filter may improve the performance.

Colorize alpha-only bitmaps

Alpha-only bitmaps don't provide any colors. Instead they contain pure opacity information. Thus if you assign an alpha-only bitmap to the Image view, you have to specify which color you want the bitmap to be colorized with when it is shown on the screen otherwise the bitmap appears with white color.

To specify the color you use the property Color. Alternatively you can configure the bitmap to be colorized with a color gradient. For this purpose you specify the colors for the four corners of the Image view (top-left, top-right, bottom-right and bottom-left) individually by using the corresponding properties ColorTL, ColorTR, ColorBR and ColorBL. The gradient colors are interpolated linearly between the specified values. Using colors with alpha < 255 causes the bitmap to appear semi- or even transparent. For example:

Please note, before the version 11.00 the common property Color and the individual properties ColorTL.. ColorBR were intended to be used exclusively. You could specify either the common color for the entire image or individual colors for its four corners. Using both approaches simultaneously produced unexpected results depending on the order in which the properties were initialized. This confused the users.

Starting with the version 11.00 the Image view calculates the resulting colors by modulating the values from the individual properties ColorTL..ColorBR by the value from the common property Color. In this manner, you are able to specify colors in all properties simultaneously avoiding the unpredictable behavior found in the preceding version. From technical point of view, the modulation is performed by multiplying the color components (red, green, blue, alpha) from the individual property (e.g. ColorTL) with the corresponding components from the common property Color.

Modulate the opacity of the displayed bitmap

Using the property Opacity you can modulate the original opacity of the displayed bitmap, so that it appears semi-transparent even if the original content was opaque. The valid values for the property Opacity are 0 .. 255, whereby the smaller the value the more transparent the resulting image. For example:

Additionally you can specify for every corner (top-left, top-right, bottom-right and bottom-left) an individual opacity value resulting in the bitmap being modulated by an opacity gradient. For this purpose modify the alpha values of the corresponding properties ColorTL, ColorTR, ColorBR and ColorBL. For example:

Select the frame number of a multi-frame bitmap resource

If you assign a multi-frame bitmap resource to the Image view, the view displays always one (per default the first available) frame. To display another frame you have to specify its number by using the property FrameNumber. In the following example you see three Image views, each configured to display another frame from one and the same multi-frame bitmap resource:

Multi-frame bitmaps are ideal wherever several versions of one and the same image are necessary. For example, a button can display different versions of its icon depending on whether the user actually presses the button or not. Instead of creating individual bitmap resources for every possible button state you store the different versions of the icon as frames within one multi-frame bitmap resource.

Control the playback of an animated bitmap resource

A multi-frame bitmap resource can be configured as containing a short animation sequence. When such bitmap is assigned to the Image view, the animation sequence can be played automatically.

To control the playback you use the property Animated or you send signals to the slot methods StartAnimation and StopAnimation. Per default the Image view plays the sequence endless as long as the property Animated is true. You can disable this behavior by additionally setting the property Endless to false.

Once finished the animation, the Image view sends a signal to a slot method assigned to its property OnFinished. In this manner you can trigger other animation effects or simply perform operations you want to complete just after the playback is done.

Connect the Image view with a Slide Touch Handler

For your convenience the Views::Image class implements an interface for easy coupling Image views with Slide Touch Handlers. In this manner, the user can scroll the content displayed within the Image view by simply touching the associated Slide Touch Handler. Assuming that you have already an Image view in your GUI component, then:

Follow the instructions to add a new Slide Touch Handler.

Arrange the Slide Touch Handler so it covers the destined Image view.

Assign the Slide Touch Handler to the property SlideHandler of the Image view.

Control the visibility of the Image view

The visibility of the Image view is controlled primarily by the property Visible and the content of the assigned bitmap. Also the specified opacity and eventually the color values may affect the resulting appearance of the Image view.

Per default the views appear alpha-blended over the contents lying behind them unless you explicitly disable this mode by setting the property AlphaBlended to the value false. In such case, the image will overwrite the contents in the background. For example:

TIP

In the complete GUI application an individual view is visible on the screen only when all of its superior Owner components are visible too, the view itself does lie within the visible area of the superior components and the view is not covered by other sibling views nor components.