FrameworkElement.Height Property
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Gets or sets the suggested height of a FrameworkElement.
Namespace: System.Windows
Assembly: System.Windows (in System.Windows.dll)
Syntax
'Declaration
Public Property Height As Double
public double Height { get; set; }
<frameworkElement Height="double"/>
-or-
<frameworkElement Height="Auto"/>
Property Value
Type: System.Double
The height, in pixels, of the object. The default is Double.NaN. Except for the special Double.NaN value, this value must be equal to or greater than 0. See Remarks for upper-bound information.
Remarks
Dependency property identifier field: HeightProperty
Height is one of three writable properties on FrameworkElement that specify height information. The other two are MinHeight and MaxHeight. If there is a conflict between these values, the order of application for actual height determination is that first MinHeight must be honored, then MaxHeight, and finally, if it is within bounds, Height.
Several of the FrameworkElement derived objects are also derived from Shape. Not all of the Shape classes typically 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. See Shapes and Drawing.
Custom classes might have similar considerations where the class might have properties that are more meaningful for specifying dimensions than are Height or Width. In this case Height or Width are both still available as members and are settable, even though the desirable behavior might be to not enable the Height or Width setting. In critical cases, it might be useful to shadow the Height and Width properties to prevent them from being set directly by consumers of the class.
If the object where the Height or Width properties are set is a child object in another parent's child collection, setting Height or Width to a value is only a suggested value for Silverlight layout. 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. In practical terms, a FrameworkElement is almost always the child object of something else; even when you set the Height on the page root. (For the page root, that value is used when the underlying application model establishes the basic rendering assumptions that create the Silverlight content area in the hosting browser application.)
The return value of this property is always the same as any value that was set to it. In contrast, the value of the ActualHeight 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 Height, and the layout system might not have processed that particular sizing property change yet.
Negative values for Height are not permitted. Non-integral values for Height are technically permitted, but should generally be avoided and are normally rounded by the default layout rounding behavior. For more information, see Layout Rounding.
In addition to the validation check, there is a nondeterministic upper value bound for Height that is enforced by the layout system (this is a very large number, larger than Single.MaxValue but smaller than Double.MaxValue). If you exceed this bound, the object does not render, and no exception is thrown. Do not set Height to a value that is significantly larger than the maximum size of any possible visual display, or you might exceed this nondeterministic upper bound.
"Auto" Layout and Double.NaN
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, set Height and Width specifically to Double.NaN.
Although not a common practice except for perhaps in visual state templates, you can also explicitly set Height and Width attributes in XAML to be the string Auto instead of a Double value. Setting Auto in Silverlight XAML is a special behavior of the Silverlight 5 XAML parser, not a TypeConverter behavior.
Version Information
Silverlight
Supported in: 5, 4, 3
Silverlight for Windows Phone
Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0
Platforms
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.
See Also