The Mosaic class Views::SVG implements a graphical object specialized to display a single SVG image (scalable vector graphics). This so-called SVG 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 SVG views appear in the canvas area of Composer (and accordingly on the screen in your target device):

Diverse SVG images displayed in Embedded Wizard. The orange icon in the upper-right corner is a variant of the official logo for SVG (Scalable Vector Graphics) file format standard and is subject to W3C Document license conditions.

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. Usually, SVG images also occupy less memory compared with pixel bitmap resources. The larger the bitmap, the bigger the expected benefit of the SVG file. 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 views are therefore not seen as replacement for regular (bitmap based) Image views. 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 or SVG image.

The following sections are intended to provide you an introduction and useful tips of how to work with the SVG view. For the complete reference please see the documentation of the Views::SVG 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 view just at the design time of a GUI component do following:

As long as the SVG 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. Please note, for better overview the below screenshot has been made with Inspector window being configured to sort the properties by categories:

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

The content to display within an SVG view 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 display SVG images, which have been e.g. received just at the runtime or loaded from some external storage.

Per default, the SVG view displays the image centered within the area determined by the property Bounds. If the SVG image 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 SVG view should react when its size and the size of the displayed SVG image are different. In particular, you can align the image at the edges of the SVG view or you can instruct the view to proportionally scale or even stretch the SVG image 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, 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 unless you have configured the property Alignment to explicitly scale or stretch the image.

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 view even if no scaling has been enabled in the property Alignment. Such percentage calculation involves the original width and the height of the view itself (determined by its property Bounds). 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 view's width and height. By properly configuring the property Alignment such small image can then be aligned within the SVG view's area.

In use cases where the resulting size of the displayed SVG image should not depend on the size of the SVG view, the property ViewSize can be used. The size calculation ignores in such case the property Bounds using instead the size specified in the property ViewSize. For example, if ViewSize is configured with value <200,100> and the SVG image attributes width and height are both 100%, then the SVG image will appear with 100% * 200 pixel width and 100% * 100 pixel 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. However, the aspect ratio is ignored if the property Alignment has been configured to stretch the image (e.g. StretchToFill).

With the property RotationAngle you can determine the rotation of the displayed SVG image as angle in degrees. The rotation is performed clockwise around the position specified in the properties RotationCenterX and RotationCenterY relative to the top-left corner of the SVG image. Per default, the RotationCenterX and RotationCenterY are 0.0 which has the effect of the SVG image being rotated around its own top-left corner as demonstrated in the following figure (the gray borders indicate the view areas):

To rotate the SVG image around other position than the top-left corner, ensure that the properties RotationCenterX and RotationCenterY address the corresponding position within the SVG image. In this case it is essential to know which size the image will have on the display. The aspects affecting size calculation are explained in the section Align, scale or stretch the SVG content within the SVG view. In the following figure, the SVG image has the size of 100 x 100 pixel and the both properties RotationCenterX and RotationCenterY have been configured with the value 50.0 addressing so the center of the image:

Besides the possibility to align the image within an SVG 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 image is scrolled right/down. With negative values left/up. For example (the gray borders visualize the view areas):

Using the property Opacity you can modulate the original opacity of the displayed SVG image, 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 SVG image being modulated by an opacity gradient. For this purpose modify the corresponding properties OpacityTL, OpacityTR, OpacityBR and OpacityBL. For example:

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 view provides the property CurrentColor. The following figure demonstrates the effect of this property with SVG views displaying the SVG image from the above code snippet. Even if all four SVG view 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 views displaying the SVG image from the above code snippet. Even if all four SVG view instances share the same SVG image, each instance uses a different colors to fill and in the last case also to stroke the rectangle:

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

Per default, the SVG view rasters the SVG image every time the screen update is performed and the view lies within the affected screen area. This is true even if the associated SVG image does not change. Depending on the size of the SVG view and the complexity of the SVG image, the rasterization may impact the performance of your application.

With the property Buffered you can instruct the SVG view to raster the shape into an internal bitmap and use this bitmap during the screen update instead of rasterizing the vector graphics again and again. For this purpose, initialize the property Buffered with the value true. Please note, this optimization makes sense only when the SVG image itself does not change. When the SVG image changes with every screen update, activating the buffered mode will not improve the performance since with every alternation of the SVG data, the image needs to be rasterized again.

The visibility of the SVG view is controlled primarily by the property Visible and the content of the assigned SVG image. Also the specified opacity may affect the resulting appearance of the SVG 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: