FrameworkElement.Width Property

Definition

Gets or sets the width of a FrameworkElement.

Equivalent WinUI property: Microsoft.UI.Xaml.FrameworkElement.Width.

public:
 property double Width { double get(); void set(double value); };
double Width();

void Width(double value);
public double Width { get; set; }
var double = frameworkElement.width;
frameworkElement.width = double;
Public Property Width As Double
<frameworkElement Width="double"/>
-or-
<frameworkElement Width="Auto"/>

Property Value

Double

The width of the object, in pixels. The default is NaN. Except for the special NaN value, this value must be equal to or greater than 0.

Examples

This example shows a simple property set of a UI element that is created at run time and needs initialization of its content and basic display properties such as Height and Width and Background. (@"Windows.UI.Xaml.Controls.Control.Background?text=Background" is actually a Control property, not defined by FrameworkElement.)

Button button2 = new Button();
button2.Height = 50;
button2.Width = 100;
button2.Background = new SolidColorBrush(Colors.Blue);
button2.Content = "Click Me";
Dim button2 As Button = New Button
button2.Height = 50
button2.Width = 100
button2.Background = New SolidColorBrush(Colors.Blue)
button2.Content = "Click Me"

Remarks

Width is one of three writable properties on FrameworkElement that specify width information. The other two are MinWidth and MaxWidth. If there is a conflict between these values, the order of application for actual width determination is that first MinWidth must be honored, then MaxWidth, and finally, if it is within bounds, Width.

Several of the FrameworkElement derived types are also derived from Shape. Not all of the Shape classes use Height or Width to specify their appearance, and instead use specific properties that might define a set of points. In this case a Height or Width is calculated, but is not typically set directly.

Custom classes might have similar considerations where the class might have properties that are more meaningful for specifying dimensions than are Height or Width. Height or Width are both still available as members and are settable.

The object where the Height or Width properties are set is almost always a child object in another parent's child collection, and setting Height or Width to a value is only a suggested value for the layout process. The layout system as well as the particular layout logic of the parent's class will use the value as a nonbinding input during the layout process, and might have to clip, resize the object, resize the container, or some combination of these behaviors that spans multiple participating objects in layout. Margin and padding also influences the available size. For more info, see Alignment, margin, and padding.

The return value of this property is always the same as any value that was set to it. In contrast, the value of the ActualWidth property may vary. The variance can occur either statically, because the layout rejected the suggested size, or momentarily. The layout system itself works asynchronously relative to the property system's set of Width, and the layout system might not have processed that sizing property change yet.

Negative values for Width are not permitted.

Also, do not set Width to a value that is significantly larger than the maximum size of any possible visual display.

"Auto" and NaN

The default value of Height and Width is "Auto", represented by NaN. In XAML markup, you can use the string "Auto" to set the value to NaN.

Note

In C#, you can obtain NaN from Double.NaN.

In C++, you can obtain NaN by using the NAN macro or std::numeric_limits<double>::quiet_NaN().

Do not use the == operator to test for NaN.

In C#, use Double.IsNaN() to test for NaN.

In C++, use isnan() to test for NaN.

The layout system interprets the "Auto" value to generally mean that the object should be sized to the available size in layout, instead of to a specific pixel value.

Applies to

See also