Converters for View Properties

Converters

A converter allows to dynamically map one or more property values to view properties of graph elements. This can be used not only to fine-tune graph views but also all other kinds of views. In a limited form, the same functionality can be achieved with the Mapping Pad or by referencing a node’s attribute. However, converters are much more flexible and allow for full automation.

The easiest way to define a converter is to use the Edit Property dialog in the Properties Pad for a dataset selected in the View Manager, as described in the following. This article explains the use of the converters: String Format Converter, Math Converter, Mapping Converter and RGB Color Converter.

String Format Converter

The String Format converter can be used to create arbitrarily complex string-based view properties. For instance, you can define the label text or tooltip of a series as a combination of different constants and references to data properties. This is best explained in an example based on the ProductPortfolioAnalysis solution presented in our tutorials. Let us assume we want the Label Text of every node of the class Part to state “name costs XXX€”, with name and XXX being dynamically set in reference to the node class data properties name and cost. To create such a combined string property proceed as follows:

  1. Select a data set in the View Manager by clicking on the data series name. The series will be highlighted in blue and the comment “Edit in the Properties pad” will show up.
  2. Go to the Properties pad and click on the … button next to the “Label Text” view property to set the property for all elements of the selected series. This opens the Edit Property Dialog window.
  3. Tick the “Converter” checkbox and then select “String Format Converter” from the drop-down menu, as shown in the image below.
  4. In the Expression field, you can now create the label text consisting of constant and dynamically referenced parts.
    1. Go to the Property drop-down menu and select name from the list. Leave the formatting used to the default option No formatting and click on Insert. This will add {name} to the Expression field, a dynamic reference to the name property of each element in the dataset. Note that you can also manually type {name} in the Expression field.
    2. Next, go to the expression field and manually enter a line break and ” costs ” after {name}. This will add the constant string to the label text. Pay attention to include the empty spaces.
    3. Repeat Step 4.1 with the property cost and for Formatted using select :0.00 e.g. 1.23 . This will add {cost:0.00} to the Expression field, which is a dynamic reference to the cost property of each element in the data set. By setting the formatting the value will be displayed in decimal format. The formatted using drop-down menu offers the most-used options but there are more. If you are looking for a different formatting please see this list by MSDN.
    4. Go to the expression field and manually enter “€” after {cost:0.00}. This will add the constant string to the label text.
  5. The “Edit Property” window should now look like this. By clicking on OK the converter is applied. On the right you can see the resulting label text if this setting is applied to the Part node class of the ProductPortfolioAnalysis solution:
String Format Converter to define the Label Text property of all elements in a data set and an example of the resulting label text for a node series.
Using the String Format Converter to define the Label Text of a node series

Math Converter

The Math converter can be used to define numeric property values based on math operations with referenced numeric properties. This way calculations can be done not only in rules but also in a view, meaning that the resulting value also does not have to be stored anywhere. For instance, the Math converter can be used to set the Height, Width, X, Y, … properties of nodes (numeric properties denoting a number of pixels) dependent on one or more numeric data property values. This is best explained in an example based on the ProductPortfolioAnalysis solution presented in our tutorials. Let us assume we want to define the Height property of every node of the class Part to equal ten times the cost of each specific node. To create such a mathematically calculated property value proceed as follows:

  1. Select a data set in the View Manager by clicking on the data series name. The series will be highlighted in blue and the comment “Edit in the Properties pad” will show up.
  2. Go to the Properties pad and click on the … button next to the Height view property to set the property for all elements of the selected series. This opens the Edit Property Dialog window.
  3. Tick the “Converter” checkbox and then select “Math Converter” from the dropdown menu, as shown in the image below.
  4. In the Expression field you can now define the math operation consisting of constant and dynamically referenced parts:
    1. Go to the Reference dropdown menu, select cost from the list and click on Insert. This will add {cost} to the Expression field, a dynamic reference to the cost property of each element in the data set. Note that you can also manually type {cost} in the Expression field.
    2. Now click on a math operator (+ – * /) to add it to the Expression field. Note that you can also manually type the operator the Expression field.
    3. Go to the Expression field and manually enter a numeric constant, in our case 10. If you want to enter decimal numbers use . as decimal marker.
  5. The “Edit Property” window should now look like this. By clicking on OK the converter is applied. On the right you can see the resulting node height if this setting is applied to the Part node class of the ProductPortfolioAnalysis solution:

    Math Converter to define the Height property of all elements in a data set and an example of the resulting graph view for a node series.
    Using the Math Converter to define the Height of a node series
  6. Idea: Set the Width view property in reference to the Height to achieve a symmetric size scaling of the nodes.

Mapping Converter

The Mapping converter can be used to create arbitrarily complex mappings from one property value to another value, from a range to a value or a range to a range. For instance, the Mapping converter can be used to set a numeric or string type property of elements dependent on the exact value or range of another property value. This is best explained in an example based on the ProductPortfolioAnalysis solution presented in our tutorials. Let us assume we want to define different Fill Color settings for every node of the class Part depending on the numeric data property nbInstalledInProducts. If the nbInstalledInProducts value equals 1 the color should be blue, if the value is between 2 and 4 we want a linear color grading from pale green to dark green and if the value is greater than 4 the nodes shall be red. To create such a mapping proceed as follows:

  1. Select a data set in the View Manager by clicking on the data series name Part. The series will be highlighted in blue and the comment “Edit in the Properties pad” will show up.
  2. Go to the Properties pad and click on the … button next to the Fill Color view property to set the property for all elements of the selected series. This opens the Edit Property Dialog window.
  3. Tick the “Converter” checkbox and then select “Mapping Converter” from the drop-down menu, as shown in the image below.
  4. Next, select the Reference property nbInstalledInProducts from the drop-down menu. The value of this property will dynamically control the Fill Color property as defined in the mappings.
  5. You can now define the mappings in the Mappings field:
    1. Click on Add Mapping to add a mapping to the field. Select Equals from the first drop-down menu and set the value to 1. Map this value to a constant Fill Color by selecting value in the second drop-down menu. Then pick the color blue with the color picker. This will set the Fill Color of all Part nodes with nbInstalledInProducts equals 1 to blue.
    2. Click on Add Mapping again to add another mapping. Select In range from the first drop-down menu and set the range from 2 to 5. The range is defined as greater than or equal to the first value and smaller than the second value. Map this value to a Fill Color range by selecting range in the second drop-down menu. Then pick the start light green and end color dark green with the color picker. This will set the Fill Color of all Part nodes with nbInstalledInProducts greater than or equal to 2 and smaller than 5 in a linear variation of green, depending on the actual nbInstalledInProducts value.
    3. Click on Add Mapping again to add another mapping. Select In range from the first drop-down menu and set the range from 5 to 100. Map this value to a constant Fill Color by selecting value in the second drop-down menu. Then pick the color red with the color picker. This will set the Fill Color of all Part nodes with nbInstalledInProducts greater than or equal to 5 and smaller than 100 to red.
  6. The “Edit Property” window should now look like this. By clicking on OK the converter is applied. On the right you can see the resulting node fill colors if this setting is applied to the Part node class of the ProductPortfolioAnalysis solution:
Mapping Converter setting to define the Fill Color property of all elements in a data set and an example of the resulting graph view for a node series.
Using the Mapping Converter to define the Fill Color of a node series

Note that one thing that is so far not possible with the mapping converter is the automatic detection of minimum and maximum values. For example, imagine you would like to do a color grading from red to green with reference to nbInstalledInProducts. The minimum value occurring in the graph should be red, the maximum should be green and everything in between should be linearly mapped. This can currently not be done with the Mapping Converter. Try using the interactive Mapping Tool instead.

RGB Converter

The RGB converter can be used to set color view attributes, such as the Fill Color or the Outline Color of graph elements. In comparison to using the Mapping converter, the RGB converter allows for highly customized color gradients. This is done by independently setting the transparency (A), red (R), green (G) and blue (B) values based on constants or in reference to integer-type property values. However, we find that it is normally sufficient and easier to use the Mapping converter. The use of the RGB converter is best explained in an example based on the ProductPortfolioAnalysis solution presented in our tutorials. Let us assume we want to define different Fill Color settings for every node of the node class Part depending on the numeric data properties red and green. To create such an ARGB color calculation proceed as follows:

  1. Select a data set in the View Manager by clicking on the data series name Part. The series will be highlighted in blue and the comment “Edit in the Properties pad” will show up.
  2. Go to the Properties pad and click on the … button next to the Fill Color view property to set the property for all elements of the selected series. This opens the Edit Property Dialog window.
  3. Tick the “Converter” checkbox and then select “RGB Converter” from the drop-down menu, as shown in the image below.
  4. Next select either Constant or Reference for the A, R, G and B settings. The ARGB values need to be integers between 0 and 255, as defined by the RGB standard. Thus, if you set any value in reference to another numeric data value, this data value must be an integer within the range of 0 to 255. To cause a visible effect, the normalization of the numeric property values to that range in a rule or sequence is often required. For example, if we choose to reference the nbInstalledInProducts property with a minimum value of 1 and a maximum value of 8, we will hardly see any difference in the color. We would first need to map the minimum value to 0 and the maximum value to 255 to really make the difference visible. This is what makes the use of the RGB converter complicated. You can find an online RGB color editor here (external link).

ColorDo you have any questions about this article? Then leave a comment below and we will come back to you!

Did not find the answer to your question related to Converters in this article? Then please go to the Community Forums and ask your question there or use the “Submit Ticket” button on the top right.

Was this article helpful?

Related Articles