Using Views: Bitmap Frame

The Mosaic class Views::Frame implements a graphical object specialized to show a freely scalable image by composing it of bitmap slices. With this technique (also known as 9-slice scaling) the view may flexibly change its size without the displayed images being stretched or distorted. This so-called Frame view can be used to compose the appearance of a GUI component, in particular to display any kinds of resizable decorations and frames. The following screenshot demonstrates few examples of how Frame 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 Frame view. For the complete reference please see the documentation of the Views::Frame class.

Frame views and 9-slice image scaling

The Frame view is displayed by filling its area with slices copied from an original bitmap. Depending on the ratio between the size of the Frame view and the of the bitmap, the slices are copied multiple times resulting in areas of the Frame view being literally tiled with them. Thus, the original bitmap seems to be scaled without being it really.

This technique is called 9-slice image scaling because the original image (the bitmap) is considered as being composed of 9 equally sized slices organized in three rows and three columns. Accordingly, the Frame view is divided in 9 areas which are then tiled with the corresponding slices. The following figure demonstrates it:

Add new Frame view

To add a new Frame 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 Bitmap Frame.

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

Eventually name the new added Frame view.

Inspect the Frame view

As long as the Frame 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 Frame 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 Frame view

Once added, you can freely move the Frame 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 Frame view to appear behind other views you can reorder it explicitly.

Specify the bitmap for the Frame view

The content to display within a Frame 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 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 Frame view.

The Frame view expects the assigned bitmap being composed of nine equally sized slices arranged in three rows and three columns. You should consider this aspect when designing the bitmap in a graphical editor. The following figure demonstrates the correct composition of such bitmap:

Please note, every new added Bitmap Frame view uses the Resources::DefaultFrame bitmap resource as place holder to display something on the screen. This default bitmap resource contains a simple gray rectangle with rounded corners. If you like it, you can use it as it is.

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 Frame view, you have to specify which color you want the bitmaps to be colorized with when they are shown on the screen otherwise the bitmaps appear with white color.

To specify the color you use the property Color. Alternatively you can configure the bitmaps to be colorized with a color gradient. For this purpose you specify the colors for the four corners of the Frame 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 bitmaps 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 frame 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 Frame 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 bitmaps, so they appear 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 bitmaps 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 Frame view, the view uses always one (per default the first available) frame to fill its area. To use another frame you have to specify its number by using the property FrameNumber. In the following example you see three Frame views, each configured to display another frame from one and the same multi-frame bitmap resource:

Please don't confuse the Frame view with frame of a multi-frame bitmap resource. Both concepts have nothing in common although they sound equally. The Frame view is intended to display scalable borders (like picture frames, thus the name). In turn the frame within a multi-frame bitmap represents a single picture.

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 background 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 background 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 Frame 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 Frame 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 Frame 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.

Show and hide Frame view edges individually

Per default, the Frame view displays all four edges and the interior area of the assigned bitmap. If desired however, you can prevent individual edges and/or the interior area from being shown. For this purpose you specify in the property Edges all the parts of the Frame view you want to display. The following screenshot demonstrates it:

In particular cases when you need to hide one or several edges of the frame you can additionally configure the property NoEdgesLimit. With this property you determine the maximum size of the frame up to which the deactivated edges are not displayed. For example, if you disable the edge Right and you configure the property NoEdgesLimit to the value <200,0>, the right edge will be invisible as long as the frame is narrower than the specified width 200. Starting with 200 pixel width, the view displays again the right edge although it has been deactivated in the Edges property. The following screenshot demonstrates this. Please note how the right edge is clipped when the width of view starts to exceed the specified NoEdgesLimit value:


If the original bitmap resource is designed to represent a frame with an empty (transparent) interior area, it is recommended to disable the mode Interior in the property Edges. This may affect positively the performance.

Control the visibility of the Frame view

The visibility of the Frame view is controlled primarily by the property Visible, the content of the assigned bitmap and the enabled frame edges. Also the specified opacity and eventually the color values may affect the resulting appearance of the Frame 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 images will overwrite the contents in the background. For example:


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.