Gets or sets the width of a FrameworkElement.
Type: System.Double [.NET] | float64 [C++]
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.
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 for UI element layout.
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.
The default value of Height and Width is not 0, it is Double.NaN. Height and Width support the ability to be an unset "Auto" value. Because Height and Width are Double values, Double.NaN is used as a special value to represent this "Auto" behavior. 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. If you want the "Auto" behavior for an object when it is used in layout, leave Height and Width unset at their Double.NaN default value. If you have previously set values and want to reenable the "Auto" behavior with run-time code, set to Double.NaN. In XAML such as templates, you can set attribute values using the string "Auto".
Note Visual C++ component extensions (C++/CX) doesn't have a constant for NaN, it uses a value, which appears as "-1.#IND" followed by zeros.
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. (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";
Minimum supported client
Minimum supported server
|Windows Server 2012|
- Quickstart: Defining layouts
- Alignment, margin, and padding for UI element layout