The SVG Bitmap object represents a NATIVE off-screen bitmap filled with graphical shapes according to a provided SVG image (scalable vector graphics). The SVG Bitmap object can be used wherever bitmaps are expected in your application. For example, it can be associated to a widget and act there as an icon. When at the runtime the provided SVG image changes, the content of the SVG Bitmap is automatically updated, causing in turn an update in all associated views like the mentioned widgets. The SVG Bitmap object can thus be considered as a bridge between SVG images and views or widgets able to display regular bitmaps only.

A peculiarity of SVG images is that they can be scaled in size and rotated without loss of quality and without presenting any ugly scaling effects as it is the case when using pixel bitmap resources. On the other hand, processing SVG contents require much more CPU power and, depending on the SVG content, also RAM to store intermediate image contents. SVG Bitmaps are therefore not seen as replacement for regular bitmap resources. More than that, they should be considered as a complement for regular images and it's up to you to decide in which application case it is appropriate to use a regular bitmap or an SVG image.

Please note, SVG Bitmap represents the bitmap only. To display its contents on the screen you have to assign the SVG Bitmap object to an image view. If all you want to do is to display the SVG image directly on the screen, it may be more convenient to use the SVG view instead of the here described SVG Bitmap object. The bitmap object is convenient only wherever the bitmap itself is needed (e.g. to display the SVG image as icon in a widget).

The following sections are intended to provide you an introduction and useful tips of how to deal with the SVG Bitmap. For the complete reference please see the documentation of the Graphics::SVGBitmap class.

SVG specification and the feature set are very extensive. The authors of Embedded Wizard have therefore decided to support only a subset of the entire SVG functionality carefully considering which features are useful and practical on less powerful embedded systems. For complete compatibility overview, please see the section SVG versions and compatibility.

To add a new SVG Bitmap just at the design time of a GUI component do following:

As long as the SVG Bitmap object is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property ViewSize in the screenshot below. Please note, for better overview the below screenshot has been made with Inspector window being configured to sort the properties by categories:

The SVG Bitmap stores the rasterized graphical shapes in an internal NATIVE bitmap. In order to display this bitmap on the screen you have to connect the SVG Bitmap object to one of the image views. Accordingly, the view will display the bitmap similarly to how regular static Bitmap resources are displayed.

To connect an SVG Bitmap to a view you have to assign this object to the adequate property of the affected view (e.g. to the Bitmap property). With the Inspector Assistant you can conveniently select the right SVG Bitmap object when you edit the initialization expression for the property. The following example demonstrates how you assign the SVG Bitmap object to the property Icon of a Push Button widget:

As soon as you have connected the both, the information provided in the SVG Bitmap object is used by the view. If desired, you can assign the same object to several views. If during the runtime of the application, the content of the SVG Bitmap object changes, all associated views are updated automatically.

Each SVG Bitmap manages internally an off-screen NATIVE bitmap where the resulting (rasterized) graphical shapes are stored. The size (width x height) of this bitmap is configured by using the property ViewSize. Consequently, if you configure the SVG Bitmap with the size <200,100>, the bitmap will be able to store 200x100 pixel large graphical shapes. Parts of a graphical shape lying beyond this border are simply clipped.

Please note, unlike regular pixel based bitmap images, the displayed size and the aspect-ratio of an SVG image can be affected by attributes width, height and viewBox found in the root <svg> element inside the SVG image itself. In this manner the author of the SVG image can determine few constraints how the image should appear on different screens depending on the available screen area. The SVG image author can, for example, specify a fixed, predetermined image resolution, like width="200px" and height="100px". Such image will then appear with size of 200x100 pixel.

If the author of the SVG image has configured the attributes width and height with percentage values, e.g. 100%, the SVG image will accordingly fill the corresponding area of the SVG Bitmap. Such percentage calculation involves the original width and the height of the SVG Bitmap (determined by its property ViewSize). For example, if the attributes width and height are both 25%, then the resulting SVG image size will assume a quarter of the original SVG Bitmap's width and height.

If the SVG image does contain the attribute viewBox, the above explained size calculations additionally take in account the aspect ratio of the image resulting from the attribute viewBox. When the size of such SVG image is adjusted at the runtime (e.g. the image is resized), the image will retain its original aspect ratio as originally intended by its author.

The content to rasterize within an SVG Bitmap is determined by its property SVG. Usually, you initialize this property with the name of an existing SVG 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 SVG.

From technical point of view, you can initialize the property SVG with any instance of a class descended from the Mosaic class Resources::SVG. In particular, you can use an instance of the Graphics::SVG class if you want to rasterize SVG images, which have been e.g. received just at the runtime or loaded from some external storage.

The SVG specification defines for all color relevant attributes the possibility to specify a value named currentColor. Such configuration indicates that the corresponding color attribute is determined by a variable existing outside of the SVG image. In this manner, the color value can be set dynamically at the runtime of the application, for example, to correspond to the color of some surrounding text, etc.. The following code snippet demonstrates an SVG image composed of two rounded corner rectangles. The outer rectangle is filled with green color. For the inner rectangle the fill color has been configured to correspond to currentColor. This color is thus determined at the runtime:

To specify a concrete color value for all occurrences of currentColor, the SVG Bitmap provides the property CurrentColor. The following figure demonstrates the effect of this property with SVG Bitmaps using the SVG image from the above code snippet. Even if all four SVG Bitmaps instances share the same SVG image, each instance uses a different color to paint the inner rectangle. In the fourth case, the color is semitransparent white (#FFFFFF77) resulting in the outer green rectangle shining through the inner rectangle:

Additional possibility to configure color values at the runtime of an application is available through the properties DefaultFillColor and DefaultStrokeColor. In fact the possibility to configure colors using the both properties goes beyond the SVG specification. According to the specification, fill operation without explicitly specified color (the SVG fill attribute is omitted) are using black color. Stroke operations, in turn, are transparent if the SVG image is missing the appropriate stroke attribute.

With the properties DefaultFillColor and DefaultStrokeColor we add the possibility to specify colors other than the per default foreseen SVG behavior. The following code snippet demonstrates an SVG image composed of a rounded corner rectangle. As you see, this document is missing any color configurations for the attributes fill and stroke. Consequently, such rectangle would appear filled with solid black color:

The following figure demonstrates the effect of the both properties with SVG Bitmaps using the SVG image from the above code snippet. Even if all four SVG Bitmap instances share the same SVG image, each instance uses a different colors to fill and in the last case also to stroke the rectangle:

With the property OnUpdate your implementation can react to any state change during the lifetime of the SVG Bitmap object. In particular, the slot method associated to this property is signaled each time, when the content of the SVG Bitmap object has changed. In practice it is the case after the alternation of its associated SVG image. The following steps describe how to react to the events: