Passing Arguments in XAML

PDF for offline use
Sample Code:
Related Articles:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2016-10

This article demonstrates using the XAML attributes that can be used to pass arguments to non-default constructors, to call factory methods, and to specify the type of a generic argument.

Overview

It's often necessary to instantiate objects with constructors that require arguments, or by calling a static creation method. This can be achieved in XAML by using the x:Argument and x:FactoryMethod attributes:

  • The x:Argument attribute is used to specify constructor arguments for a non-default constructor, or for a factory method object declaration. For more information, see Passing Constructor Arguments.
  • The x:FactoryMethod attribute is used to specify a factory method that can be used to initialize an object. For more information, see Calling Factory Methods.

In addition, the x:TypeArguments attribute can be used to specify the generic type arguments to the constructor of a generic type. For more information, see Specifying a Generic Type Argument.

Passing Constructor Arguments

Arguments can be passed to a non-default constructor using the x:Argument attribute. Each constructor argument must be delimited within an XML element that represents the type of the argument. Xamarin.Forms supports the following elements for basic types:

  • x:Object
  • x:Boolean
  • x:Byte
  • x:Int16
  • x:Int32
  • x:Int64
  • x:Single
  • x:Double
  • x:Decimal
  • x:Char
  • x:String
  • x:TimeSpan
  • x:Array
  • x:DateTime

The following code example demonstrates using the x:Arguments attribute with three Color constructors:

<BoxView HeightRequest="150" WidthRequest="150" HorizontalOptions="Center">
  <BoxView.Color>
    <Color>
      <x:Arguments>
        <x:Double>0.9</x:Double>
      </x:Arguments>
    </Color>
  </BoxView.Color>
</BoxView>
<BoxView HeightRequest="150" WidthRequest="150" HorizontalOptions="Center">
  <BoxView.Color>
    <Color>
      <x:Arguments>
        <x:Double>0.25</x:Double>
        <x:Double>0.5</x:Double>
        <x:Double>0.75</x:Double>
      </x:Arguments>
    </Color>
  </BoxView.Color>
</BoxView>
<BoxView HeightRequest="150" WidthRequest="150" HorizontalOptions="Center">
  <BoxView.Color>
    <Color>
      <x:Arguments>
        <x:Double>0.8</x:Double>
        <x:Double>0.5</x:Double>
        <x:Double>0.2</x:Double>
        <x:Double>0.5</x:Double>
      </x:Arguments>
    </Color>
  </BoxView.Color>
</BoxView>

The number of elements within the x:Arguments tag, and the types of these elements, must match one of the Color constructors. The Color constructor with a single parameter requires a grayscale value from 0 (black) to 1 (white). The Color constructor with three parameters requires a red, green, and blue value ranging from 0 to 1. The Color constructor with four parameters adds an alpha channel as the fourth parameter.

The following screenshots show the result of calling each Color constructor with the specified argument values:

Calling Factory Methods

Factory methods can be called in XAML by specifying the method's name using the x:FactoryMethod attribute, and its arguments using the x:Arguments attribute. A factory method is a public static method that returns objects or values of the same type as the class or structure that defines the methods.

The Color structure defines a number of factory methods, and the following code example demonstrates calling three of them:

<BoxView HeightRequest="150" WidthRequest="150" HorizontalOptions="Center">
  <BoxView.Color>
    <Color x:FactoryMethod="FromRgba">
      <x:Arguments>
        <x:Int32>192</x:Int32>
        <x:Int32>75</x:Int32>
        <x:Int32>150</x:Int32>                      
        <x:Int32>128</x:Int32>
      </x:Arguments>
    </Color>
  </BoxView.Color>
</BoxView>
<BoxView HeightRequest="150" WidthRequest="150" HorizontalOptions="Center">
  <BoxView.Color>
    <Color x:FactoryMethod="FromHsla">
      <x:Arguments>
        <x:Double>0.23</x:Double>
        <x:Double>0.42</x:Double>
        <x:Double>0.69</x:Double>
        <x:Double>0.7</x:Double>
      </x:Arguments>
    </Color>
  </BoxView.Color>
</BoxView>
<BoxView HeightRequest="150" WidthRequest="150" HorizontalOptions="Center">
  <BoxView.Color>
    <Color x:FactoryMethod="FromHex">
      <x:Arguments>
        <x:String>#FF048B9A</x:String>
      </x:Arguments>
    </Color>
  </BoxView.Color>
</BoxView>

The number of elements within the x:Arguments tag, and the types of these elements, must match the arguments of the factory method being called. The FromRgba factory method requires four Int32 parameters, which represent the red, green, blue, and alpha values, ranging from 0 to 255 respectively. The FromHsla factory method requires four Double parameters, which represent the hue, saturation, luminosity, and alpha values, ranging from 0 to 1 respectively. The FromHex factory method requires a String that represents the hexadecimal (A)RGB color.

The following screenshots show the result of calling each Color factory method with the specified argument values:

Specifying a Generic Type Argument

Generic type arguments for the constructor of a generic type can be specified using the x:TypeArguments attribute, as demonstrated in the following code example:

<ContentPage ...>
  <StackLayout>
    <StackLayout.Margin>
      <OnPlatform x:TypeArguments="Thickness"
                  iOS="0, 20, 0, 0"
                  Android="5, 10"
                  WinPhone="10" />
    </StackLayout.Margin>
  </StackLayout>
</ContentPage>

The OnPlatform<T> class is a generic class that provides a platform-specific implementation of T for the current value of the Device.OS property. In this example, OnPlatform<T> is used to set the StackLayout.Margin property to a platform-specific Thickness.

Summary

This article demonstrated using the XAML attributes that can be used to pass arguments to non-default constructors, to call factory methods, and to specify the type of a generic argument.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.