Last modified on 7 August 2019, at 14:18

Converters In Xamarin

Revision as of 14:18, 7 August 2019 by MKR (Talk | contribs)

Converters are used to prepare application data to format a UI defined by a XAML markup. These converters make it possible to show elements only when specific conditions (like data being available) are met. This allows the creation of a good UI with XAML code only, improving code readability while also decreasing code complexity.

This page explains how to properly use converters for customizing the UBIK Xamarin User Interface. Furthermore, all available converters are listed to provide a good reference.

Definition

In Xamarin, before converters can be used, they need to be defined in the page's Resources tag. Make sure to include the UBIK.CPL.Converters namespace in the namespace definitions! The following example shows how the NullToBoolConverter can be defined:

<ContentView x:Class="UBIK.CPL.Resources.UBIKChildArea"
   xmlns="http://xamarin.com/schemas/2014/forms"
   xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
   xmlns:converters="clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL">
    <ContentView.Resources>
        <ResourceDictionary>
            <converters:NullToBoolConverter x:Key="NullToBool" />
        </ResourceDictionary>
    </ContentView.Resources>

    <!-- Cuztomizing -->

</ContentView>

The key NullToBool makes this converter accessible from the customizing in this page.

Definition With Properties

In the following example, which is the same example from above, the StringFormatConverter will be additionally defined. To add more formatting possibilities, it has two extra properties, which need to be prefilled during initialization. Henceforth, these properties can be prefilled with static values or with static references.

<ContentView x:Class="UBIK.CPL.Resources.UBIKChildArea"
   xmlns="http://xamarin.com/schemas/2014/forms"
   xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
   xmlns:converters="clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL">
    <ContentView.Resources>
        <ResourceDictionary>
            <converters:NullToBoolConverter x:Key="NullToBool" />
            <converters:StringFormatConverter x:Key="Formatter" Parameter1="5" Parameter2="{Binding Children.Items.Count}" />
        </ResourceDictionary>
    </ContentView.Resources>

    <!-- Cuztomizing -->

</ContentView>

Whereever this converter is used within the file it was defined in, Formatter will always have its Parameter1 set to 5 and its Parameter2 to the number of children of the currently viewed UBIK object. If this behavior is not intended, consider defining another StringFormatConverter with a different Key in the same way as shown above.
See below to find out how to use this converter!

Usage

A converter can only be used in conjunction with a {Binding}. The following is an easy example, showing how the NullToBool converter, defined above, can be used.

<Label Text="My Text" IsVisible="{Binding MyBindableProperty, Converter={StaticResource NullToBool}}"/>

If MyBindableProperty is null or an empty string, the converter will return true, making the Label visible!

Parameter

Some converters accept a ConverterParameter, that passes additional information. Closely read the description of the available converters to find out which accept or even require a parameter to work properly. In Ubik, some converters accept a string parameter, consisting of multiple individual parameters separated by |.

An example of this behavior is the ContainsToBoolConverter, which checks if the current value is contained within a collection of values (passed as the parameter):

<Label Text="My Text" IsVisible="{Binding MyValue, Converter={StaticResource ContainsToBool}, ConverterParameter=1|2|3|4|5|6|7|8|9}"/>

The label will only be visible if the MyValue property (which is expected to parse as an Integer in this example) is one of the values of the parameter.
Again, to get the converter working, don't forget to define it in the page's resources!

FallbackValue

In some rare cases, a converter might not return anything desired (like null) if some condition doesn't work out as it should (e.g. value is null). To still be able to get a usable return value, it's possible to define a FallbackValue.

Example Usage of StringFormatConverter

This converter can take up to two additional parameters during definition. Please see Definition With Properties for more information!

<Label Text="{Binding MyValue, Converter={StaticResource Formatter}, ConverterParameter=The Value of my value is \{0\}\, compared to \{1\} and \{2\}!}"/>

It's important to note that special characters, like {, } and ,, need to be escaped using a \, else the expression will be wrongly interpreted (and nothing happens)!

The text of the ConverterParameter will be analyzed, and any occurrance (including duplicates) of {0}, {1} and {2} replaced with the binding value, Formatter.Parameter1 and Formatter.Parameter2 respectively!

Make sure to note, that Xamarin Forms has a native StringFormat option as well, that is probably way faster than using a converter for it. Furthermore, it supports formatting options!

Data Source

Although technically not a converter, the SfDataSourceExt control is currently on the way of replacing the SfDataSourceConverter, due to improved performance. The usage is pretty simple: Similar to the converters, it needs to be defined in the Page Resources. Then, a Key and Expression, as well as an ItemsSource have to be defined. Last, but not least, the the converter can be used within the ItemsSource property of a Syncfusion SfListView. See the following example:

<ContentView x:Class="UBIK.CPL.Resources.UBIKChildArea"
   xmlns="http://xamarin.com/schemas/2014/forms"
   xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
   xmlns:converters="clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL">
    <ContentView.Resources>
        <ResourceDictionary>
             <controls:SfDataSourceExt
               x:Key="MyDataSource"
               ItemsSource="{Binding Children.Items}"
               Expression="Item.Content.MetaUID.ToString().ToLower()==&quot;85a50533-3817-4a0b-84cd-615b48b62565&quot; &amp;&amp; Item[&quot;ORGA_STATUS&quot;]!=100" />
        </ResourceDictionary>
    </ContentView.Resources>
    <sync:SfListView
          x:Name="ListView1"
          AllowSwiping="True"
          ItemSize="60"
          ItemTemplate="{StaticResource ChildTemplateSelector}"
          ItemsSource="{Binding DisplayItems, Source={StaticResource MyDataSource}}"
          LeftSwipeTemplate="{StaticResource SwipeLeftTemplateSelector}"
          RightSwipeTemplate="{StaticResource SwipeRightTemplateSelector}"
          SelectionMode="None">
</ContentView>

Thanks to the given expression, filtering is applied once the data source is evaluated. It's important to have special characters correctly escaped, like the example shows.

List of Available Converters

The following list contains all currently available converters for UBIK Xamarin customizing.

Two-way converters can be used with two-way bindings, e.g. a text-box displaying an editable value. If the value updates in the model, the text-box text changes. If the user edits the value, the value in the model behind also gets updated. As a clarificationValue refers to the Binding Value, and parameter to the ConverterParameter!

Converter 2-Way Output Type Input Type Parameter Type Description
BooleanConverter Boolean Boolean

Interprets the boolean value and returns it. If the value cannot be interpreted, false is returned.

BooleanInvertConverter Boolean Boolean

Interprets and converts a boolean into its inverted value. If the value cannot be interpreted, false is returned.

BooleanToFontAttributeConverter FontAttribute Boolean

Converts a boolean into a font attribute value. In detail, if the value is true, the parameter is interpreted (Bold, Italic, None) and returned. The default returned font-attribute is None.

ByteToImageSourceValueConverter ImageSource Byte[ ],
Byte Stream

Converts a byte stream value into an image source.

ChildAreaTemplateConverter ChildAreaTemplate ContentViewModel

Returns a ChildAreaTemplate from a ContentViewModel or null if the ViewModel cannot be interpreted.

ChildItemSelectionModeToSfListViewSelectionModeConverter ListViewSelectionMode ChildItemSelectionMode

Converts a ChildItemSelectionMode to a Syncfusion ListViewSelectionMode. Default is "Single".

ClassificationToBoolConverter Boolean ContentViewModel

Returns a boolean indicating whether the given ContentViewModel is successfully classified.

ContainsToBoolConverter Boolean String,
Guid,
Object

Checks if the delivered value is contained within a collection of values (delivered in the parameter, seperated with |). If the value is contained, true will be returned, else false. The functionality is similar to the ContainsToVisibilityConverter in the WinX project.

ContainsToInvertedBoolConverter Boolean String,
Guid,
Object

Same as the ContainsToBoolConverter, but with inverted output.

ContentAreaTeamplateConverter UBIKContentArea ContentViewModel This converter is not yet finished and just returns the UBIKContentArea if the value is a ContentViewModel.
DateTimeOffsetToDateConverter DateTime DateTimeOffset

Converts a DateTimeOffset to the correct DateTime, applied to the current date and time. If the value cannot be interpreted, a new DateTime, generated from the device's current time (DateTime.Now) is returned.

DateTimeToFromNowStringConverter String DateTime

Returns a DateTime into a human-readable and easily understandable string message (the last applying one will be taken):

  • Less than 5 minutes in the past: Just now
  • Less than 10 minutes in the past: A few minutes ago
  • Less than 1 hour in the past: An hour ago
  • Less than 23 Hours in the past: Some hours ago
  • Less than 1 day in the past: Yesterday
  • More than 1 day in the past: The DateTime value formatted according to the device's localization rules.
  • Not interpretable: ???
DebugConverter Object Object

A converter returning the given value for debug reasons.

DistanceToStringConverter String Double

Returns the given value interpreted as length. Values are returned in kilometers with two comma digits (e.g. 2.84km), values smaller than 1km are returned as meters and NaN will be returned as infinity. If the value cannot be interpreted, an empty string will be returned.

EqualityToBoolConverter Boolean Object,
String
Object,
String

Returns true if the given value and parameter are equal to each other, false otherwise.

EqualityToInvertedBoolConverter Boolean Object,
String
Object,
String

Returns true if the given value and parameter are not equal to each other, false otherwise.

SelectionChangedEventArgsConverter ListSelectionChangedEventArgs ItemSelectionChangedEventArgs

Converts an Syncfusion ItemSelectionChangedEventArgs to a ListSelectionChangedEventArgs.
The use-case of this converter is highly specific.

FilterCriterionToValueConverter String FilterCriterion

Converts a FilterCriterion to its value. The functionality is similar to UWP's FilterCriterionToValueConverter.

GuidPropertyValueConverter String Guid Binding, where source is ContentViewModel

Returns the first item of the parameter's Source-ViewModel that matches the given GUID value. If none is found, null is returned.

IntToColorConverter Color Integer

Converts an ARGB integer value to a color. If the value cannot be interpreted, the converter tries to parse the parameter as a color to return it. If everything fails, transparent is returned.

ItemCountToBoolConverter Boolean Integer Integer

This converter has a property to set the boolean return value, called LesserThanReturnValue. This property-value will be returned if the given value is smaller than or equal to the threshold (parameter, defaults to 0). If the value is bigger than the threshold, the inverted LesserThanReturnValue will be returned.
In any other case (like the value cannot be interpreted), false is returned, so it's a good idea to set the converter's property in a way that the return is only true if you need it.

ItemCountToOverflowConverter String Integer Integer Creates a human-readable text indicating how many items are available. The value will be interpreted as the total item count and the parameter as overflow threshold (defaults to 99).
If there are more items than the overflow, the overflow value with a + sign will be returned (e.g. 99+). If not, the value itself will be returned. If everything fails, null is returned.
NullToBoolConverter Boolean Object,
String

Null or an empty string value get converted to true, and everything else to false.

NullToInvertedBoolConverter Boolean Object,
String

Null or an empty string value get converted to false, and everything else to true.

PathToImageSourceValueConverter Image Source String

Reads the path provided as parameter and creates an image source from it.

PercentageToProgressConverter Double Integer,
Double

The numeric value (int or double), interpreted as percentage from 0 to 100, get converted to a progress level (0 to 1). Values outside this range will be contained.

PropertyNameExistsToBoolConverter Boolean (Nullable) ContentViewModel,
IContent

Converts a property to a boolean based on its existence. If it exists, true will be returned, else false or null (if something couldn't be properly interpreted).

PropertyNameExistsToInvertedBoolConverter Boolean (Nullable) ContentViewModel,
IContent

Converts a property to a boolean based on its existence. If it exists, false will be returned, else true or null (if something couldn't be properly interpreted).

RootAreaTemplateConverter ContentView Object

If the provided value is not null, the UBIKRootArea template will be returned.

SelectiveItemToValueConverter Boolean,
String,
Integer,
Double,
DateTime,
Guid,
FileReferenceData,
GeoData,
Object
Boolean,
String,
Integer,
Double,
DateTime,
Guid,
FileReferenceData,
GeoData,
Object
Binding, where source is ContentViewModel

Converts a item of a selective list to its value. If none is found, the passed value will be returned.

SelectiveListToItemsConverter List of PropertyItems IPropertyItem

Returns all items from a selective list.

SfDataSourceConverter DataSource (for ListView) Double String (Expression)

It's an advanced converter used for loading items and applying filters on it. It replaces to CollectionToViewConverter from the WinX.UWP project. The data source can be directly used with a SfListView.

This converter is obsolete!
Use SfDataSourceExt (see Data Source) instead!

StringContainsToBoolConverter Boolean String String

Returns a boolean indicating whether the parameter string is included in the value string.

StringContainsToInvertedBoolConverter Boolean String String

Same as the StringContainsToBoolConverter but with inverted output.

StringFormatConverter String Object String Allows the creation of a nicely formatted string message, similar to C#'s String.Format method.
The value will be interpreted as the {0} element, and the parameter is the template string (e.g. The total count is: {0}!. Up to two additional parameters, named Parameter1 and Parameter2, can be defined at the converter declaration. Adding formatting options to the {0} notation is not possible.

Attention, using the native StringFormat option is not only faster, but it also offers more customizability of the value!
You might still want to use the StringFormatConverter in rare cases, though!

ToStringFormatConverter String Double,
Float,
Integer,
DateTime,
String
String Converts primitives or DateTime to string and allows the application of formatting options (as parameter).
Adding a . to the end of the format-parameter allows truncation of all decimal places.
ToTypeConverter Object Object String Attempts to convert value to the Type specified in parameter, returning the value.
TypeNameToBoolConverter Boolean Object String Returns true if the type name of the value is present in the parameter-string (seperated by |).
TypeNameToInvertedBoolConverter Boolean Object String Inverted TypeNameToBoolConverter.
DataTemplateItemTemplateSelectorConverter ChildItemTemplateSelector String String Chooses what ChildItemTemplateSelector to return. Having a parameter with the content "Small" returns the small item template selector.
DataTemplateItemsPanelConverter ItemsPanelTemplate QueryDetailsPageViewModel Chooses what ItemPanelTemplate to return. Having a parameter with the content "Small" returns the small item template selector.