Share via

Xamarin.Forms common control properties, methods, and events

The Xamarin.Forms VisualElement class is the base class for most of the controls used in a Xamarin.Forms application. The VisualElement class defines many properties, methods, and events that are used in deriving classes.

Properties

The following properties are available on VisualElement objects.

AnchorX

The AnchorX property is a double value that defines the center point on the X axis for transforms such as scale and rotation. The default value is 0.5.

AnchorY

The AnchorY property is a double value that defines the center point on the Y axis for transforms such as scale and rotation. The default value is 0.5.

Background

The Background property is a Brush value that enables brushes to be used as the background in any control. The default value is Brush.Default.

BackgroundColor

The BackgroundColor property is a Color that determines the background color of the control. If unset, the background will be the default Color object, which renders as transparent.

Behaviors

The Behaviors property is a List of Behavior objects. Behaviors enable you to attach reusable functionality to elements by adding them to the Behaviors list. For more information about the Behavior class, see Xamarin.Forms Behaviors.

Bounds

The Bounds property is a read-only Rectangle object that represents the space occupied by the control. The Bounds property value is assigned during the layout cycle. The Rectangle struct contains useful properties and methods for testing intersection and containment of rectangles. For more information, see the Xamarin.Forms Rectangle API.

Clip

The Clip property is a Geometry object that defines the outline of the contents of an element. To define a clip, use a Geometry object such as EllipseGeometry to set the element's Clip property. Only the area that is within the region of the geometry will be visible. For more information, see Clip with a Geometry.

Effects

The Effects property is a List of Effect objects, inherited from the Element class. Effects allow native controls to be customized, and are typically used for small styling changes. For more information about the Effect class, see Xamarin.Forms Effects.

FlowDirection

The FlowDirection property is a FlowDirection enum value. Flow direction can be set to MatchParent, LeftToRight, or RightToLeft and determines the layout order and direction. The FlowDirection property is typically used to support languages that read right-to-left.

Height

The Height property is a read-only double value that describes the rendered height of the control. The Height property is calculated during the layout cycle and can't be directly set. The height of a control can be requested using the HeightRequest property.

HeightRequest

The HeightRequest property is a double value that determines the desired height of the control. The absolute height of the control may not match the requested value. For more information, see Request properties.

InputTransparent

The InputTransparent property is a bool that determines whether the control receives user input. The default value is false, ensuring that the element receives input. This property transfers to child elements when it's set. Setting the InputTransparent property to true on a layout class will result in all elements within the layout not receiving input.

IsEnabled

The IsEnabled property is a bool value that determines whether the control reacts to user input. The default value is true. Setting this property to false will prevent the control from accepting user input.

IsFocused

The IsFocused property is a bool value that describes whether the control is currently the focused object. Calling the Focus method on the control will result in the IsFocused value being set to true. Calling the Unfocus method will set this property to false.

IsTabStop

The IsTabStop property is a bool value that defines whether the control receives focus when the user is advancing through controls with the tab key. If this property is false, the TabIndex property will have no effect.

IsVisible

The IsVisible property is a bool value that determines whether the control is rendered. Controls with the IsVisible property set to false won't be displayed, won't be considered for space calculations during the layout cycle, and can't accept user input.

MinimumHeightRequest

The MinimumHeightRequest property is a double value that determines how overflow is handled when two elements are competing for limited space. Setting the MinimumHeightRequest property allows the layout process to scale the element down to the minimum dimension requested. If no MinimumHeightRequest is specified, the default value is -1 and the layout process will consider the HeightRequest to be the minimum value. This means that elements with no MinimumHeightRequest value will not have scalable height.

For more information, see Minimum request properties.

MinimumWidthRequest

The MinimumWidthRequest property is a double value that determines how overflow is handled when two elements are competing for limited space. Setting the MinimumWidthRequest property allows the layout process to scale the element down to the minimum dimension requested. If no MinimumWidthRequest is specified, the default value is -1 and the layout process will consider the WidthRequest to be the minimum value. This means that elements with no MinimumWidthRequest value will not have scalable width.

For more information, see Minimum request properties.

Opacity

The Opacity property is a double value from zero to one that determines the opacity of the control during rendering. The default value for this property is 1.0. Values outside of the range from 0 to 1 will be clamped. The Opacity property is only applied if the IsVisible property is true. Opacity is applied iteratively. Therefore if a parent control has 0.5 opacity and its child has 0.5 opacity, the child will render with an effective 0.25 opacity value. Setting the Opacity property of an input control to 0 has undefined behavior.

Parent

The Parent property is inherited from the Element class. This property is an Element object that is the parent of control. The Parent property is typically set automatically on an element when it's added as a child of another element.

Resources

The Resources property is a ResourceDictionary instance that is populated with key/value pairs that are typically populated at runtime from XAML. This dictionary allows application developers to reuse objects defined in XAML at both compile time and run time. The keys in the dictionary are populated from the x:Key attribute of the XAML tag. The object created from XAML is inserted into the ResourceDictionary for the specified key. once it has been initialized.

For more information, see Resource Dictionaries.

Rotation

The Rotation property is a double value between zero and 360 that defines the rotation about the Z axis in degrees. The default value of this property is 0. Rotation is applied relative to the AnchorX and AnchorY values.

RotationX

The RotationX property is a double value between zero and 360 that defines the rotation about the X axis in degrees. The default value of this property is 0. Rotation is applied relative to the AnchorX and AnchorY values.

RotationY

The RotationY property is a double value between zero and 360 that defines the rotation about the Y axis in degrees. The default value of this property is 0. Rotation is applied relative to the AnchorX and AnchorY values.

Scale

The Scale property is a double value that defines the scale of the control. The default value of this property is 1.0. Scale is applied relative to the AnchorX and AnchorY values.

ScaleX

The ScaleX property is a double value that defines the scale of the control along the X axis. The default value of this property is 1.0. The ScaleX property is applied relative to the AnchorX value.

ScaleY

The ScaleY property is a double value that defines the scale of the control along the Y axis. The default value of this property is 1.0. The ScaleY property is applied relative to the AnchorY value.

Style

The Style property is inherited from the NavigableElement class. This property is an instance of the Style class. The Style class contains triggers, setters, and behaviors that define the appearance and behavior of visual elements. For more information, see Xamarin.Forms XAML Styles.

StyleClass

The StyleClass property is a list of string objects that represent the names of Style classes. This property is inherited from the NavigableElement class. The StyleClass property allows multiple style attributes to be applied to a VisualElement instance. For more information, see Xamarin.Forms Style Classes.

TabIndex

The TabIndex property is an int value that defines the control order when advancing through controls with the tab key. The TabIndex property is the implementation for the property defined on the ITabStopElement interface, which the VisualElement class implements.

TranslationX

The TranslationX property is a double value that defines the delta translation to be applied on the X axis. Translation is applied after layout and is typically used for applying animations. Translating an element outside the bounds of its parent container may prevent inputs from working.

For more information, see Animation in Xamarin.Forms.

TranslationY

The TranslationY property is a double value that defines the delta translation to be applied on the Y axis. Translation is applied after layout and is typically used for applying animations. Translating an element outside the bounds of its parent container may prevent inputs from working.

For more information, see Animation in Xamarin.Forms.

Triggers

The Triggers property is a read-only List of TriggerBase objects. Triggers allow application developers to express actions in XAML that change the visual appearance of controls in response to event or property changes. For more information, see Xamarin.Forms Triggers.

Visual

The Visual property is an IVisual instance that enables renderers to be created and selectively applied to VisualElement instances. The Visual property is set to match its parent so defining a renderer on a component will also apply to any children of that component. If no custom renderer is set on a control or its ancestors, the default Xamarin.Forms renderer will be used. For more information, see Xamarin.Forms Visual.

Width

The Width property is a read-only double value that describes the rendered width of the control. The Width property is calculated during the layout cycle and can't be directly set. The width of a control can be requested using the WidthRequest property.

WidthRequest

The WidthRequest property is a double value that determines the desired width of the control. The absolute width of the control may not match the requested value. For more information, see Request properties.

X

The X property is a read-only double value that describes the current X position of the control.

Y

The Y property is a read-only double value that describes the current Y position of the control.

Methods

The following methods are available on the VisualElement class. For a complete list, see VisualElement API Methods.

FindByName

The FindByName method is inherited from the Element class and has the following signature:

public object FindByName (string name)

This method searches all child elements for the provided name argument and returns the element that has the specified name. If no match is found, null is returned.

Focus

The Focus method attempts to set focus on the element. This method has the following signature:

public bool Focus ()

The Focus method returns true if keyboard focus was successfully set and false if the method call did not result in a focus change. The element must be able to receive focus for this method to work. Calling the Focus method on elements that are offscreen or unrealized has undefined behavior.

Unfocus

The Unfocus method attempts to remove focus on the element. This method has the following signature:

public void Unfocus ()

The element must already have focus for this method to work.

Events

The following events are available on the VisualElement class. For a complete list, see Xamarin.Forms VisualElement Events.

Focused

The Focused event is raised whenever the VisualElement instance receives focus. This event is not bubbled through the Xamarin.Forms stack, it's received directly from the native control. This event is emitted by the IsFocused property setter.

SizeChanged

The SizeChanged event is raised whenever the VisualElement instance Height or Width properties change. If developers wish to respond directly to the size change, instead of responding to the post-change event, they should implement the OnSizeAllocated virtual method instead.

Unfocused

The Unfocused event is raised whenever the VisualElement instance loses focus. This event is not bubbled through the Xamarin.Forms stack, it's received directly from the native control. This event is emitted by the IsFocused property setter.

Units of Measurement

Android, iOS, and UWP platforms all have different measurement units that can vary across devices. Xamarin.Forms uses a platform-independent unit of measurement that normalizes units across devices and platforms. There are 160 units per inch, or 64 units per centimeter, in Xamarin.Forms.

Request properties

Properties whose names contain "request" define a desired value, which may not match the actual rendered value. For example, HeightRequest might be set to 150 but if the layout only allows room for 100 units, the rendered Height of the control will only be 100. Rendered size is affected by available space and contained components.

Minimum request properties

Minimum request properties include MinimumHeightRequest and MinimumWidthRequest, and are intended to enable more precise control over how elements handle overflow relative to each other. However, layout behavior related to these properties has some important considerations.

Unspecified minimum property values

If a minimum value is not set, the minimum property defaults to -1. The layout process ignores this value and considers the absolute value to be the minimum. The practical consequence of this behavior is that an element with no minimum value specified will not shrink. An element with a minimum value specified will shrink.

The following XAML shows two BoxView elements in a horizontal StackLayout:

<StackLayout Orientation="Horizontal">
    <BoxView HeightRequest="100" BackgroundColor="Purple" WidthRequest="500"></BoxView>
    <BoxView HeightRequest="100" BackgroundColor="Green" WidthRequest="500" MinimumWidthRequest="250"></BoxView>
</StackLayout>

The first BoxView instance requests a width of 500 and does not specify a minimum width. The second BoxView instance requests a width of 500 and a minimum width of 250. If the parent StackLayout element is not wide enough to contain both components at their requested width, the first BoxView instance will be considered by the layout process to have a minimum width of 500 because no other valid minimum is specified. The second BoxView instance is allowed to scale down to 250 and it will shrink to fit until its width hits 250 units.

If the desired behavior is for the first BoxView instance to scale down with no minimum width, the MinimumWidthRequest must be set to a valid value, such as 0.

Minimum and absolute property values

The behavior is undefined when the minimum value is greater than the absolute value. For example, if WidthRequest is set to 100, the MinimumWidthRequest property should never exceed 100. When specifying a minimum property value, you should always specify an absolute value to ensure the absolute value is greater than the minimum value.

Minimum properties within a Grid

Grid layouts have their own system for relative sizing of rows and columns. Using MinimumWidthRequest or MinimumHeightRequest within a Grid layout will not have an effect. For more information, see Xamarin.Forms Grid.