WindowChrome Class

.NET Framework 4.5

Represents an object that describes the customizations to the non-client area of a window.

Namespace:  System.Windows.Shell
Assembly:  PresentationFramework (in PresentationFramework.dll)
XMLNS for XAML: Not mapped to an xmlns.

'Declaration
Public Class WindowChrome _
	Inherits Freezable
<WindowChrome .../>

The WindowChrome type exposes the following members.

  NameDescription
Public methodWindowChromeInitializes a new instance of the WindowChrome class.
Top

  NameDescription
Public propertyCanFreezeGets a value that indicates whether the object can be made unmodifiable. (Inherited from Freezable.)
Public propertyCaptionHeightGets or sets the height of the caption area at the top of a window.
Public propertyCornerRadiusGets or sets a value that indicates the amount that the corners of a window are rounded.
Public propertyDependencyObjectTypeGets the DependencyObjectType that wraps the CLR type of this instance.  (Inherited from DependencyObject.)
Public propertyDispatcherGets the Dispatcher this DispatcherObject is associated with. (Inherited from DispatcherObject.)
Public propertyStatic memberGlassFrameCompleteThicknessGets a uniform thickness of -1.
Public propertyGlassFrameThicknessGets or sets a value that indicates the width of the glass border around a window.
Public propertyIsFrozenGets a value that indicates whether the object is currently modifiable. (Inherited from Freezable.)
Public propertyIsSealedGets a value that indicates whether this instance is currently sealed (read-only). (Inherited from DependencyObject.)
Public propertyNonClientFrameEdgesGets or sets a value that indicates which edges of the window frame are not owned by the client.
Public propertyResizeBorderThicknessGets or sets a value that indicates the width of the border that is used to resize a window.
Public propertyUseAeroCaptionButtonsGets or sets a value that indicates whether hit-testing is enabled on the Windows Aero caption buttons.
Top

  NameDescription
Public attached propertyIsHitTestVisibleInChromeGets or sets a value that indicates whether WPF hit-testing is enabled on the part of an element that is in the non-client area of a window.
Public attached propertyResizeGripDirectionGets or sets a value that indicates the direction of the resize grip behavior on an input element.
Public attached propertyWindowChromeGets or sets the instance of WindowChrome that is attached to a window.
Top

  NameDescription
Public methodCheckAccessDetermines whether the calling thread has access to this DispatcherObject. (Inherited from DispatcherObject.)
Public methodClearValue(DependencyProperty)Clears the local value of a property. The property to be cleared is specified by a DependencyProperty identifier. (Inherited from DependencyObject.)
Public methodClearValue(DependencyPropertyKey)Clears the local value of a read-only property. The property to be cleared is specified by a DependencyPropertyKey. (Inherited from DependencyObject.)
Public methodCloneCreates a modifiable clone of the Freezable, making deep copies of the object's values. When copying the object's dependency properties, this method copies expressions (which might no longer resolve) but not animations or their current values. (Inherited from Freezable.)
Protected methodCloneCoreMakes the instance a clone (deep copy) of the specified Freezable using base (non-animated) property values. (Inherited from Freezable.)
Public methodCloneCurrentValueCreates a modifiable clone (deep copy) of the Freezable using its current values. (Inherited from Freezable.)
Protected methodCloneCurrentValueCoreMakes the instance a modifiable clone (deep copy) of the specified Freezable using current property values. (Inherited from Freezable.)
Public methodCoerceValueCoerces the value of the specified dependency property. This is accomplished by invoking any CoerceValueCallback function specified in property metadata for the dependency property as it exists on the calling DependencyObject. (Inherited from DependencyObject.)
Protected methodCreateInstanceInitializes a new instance of the Freezable class. (Inherited from Freezable.)
Protected methodCreateInstanceCoreCreates a new instance of the WindowChrome class. (Overrides Freezable.CreateInstanceCore.)
Public methodEqualsDetermines whether a provided DependencyObject is equivalent to the current DependencyObject. (Inherited from DependencyObject.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodFreezeMakes the current object unmodifiable and sets its IsFrozen property to true. (Inherited from Freezable.)
Protected methodFreezeCoreMakes the Freezable object unmodifiable or tests whether it can be made unmodifiable. (Inherited from Freezable.)
Public methodGetAsFrozenCreates a frozen copy of the Freezable, using base (non-animated) property values. Because the copy is frozen, any frozen sub-objects are copied by reference. (Inherited from Freezable.)
Protected methodGetAsFrozenCoreMakes the instance a frozen clone of the specified Freezable using base (non-animated) property values. (Inherited from Freezable.)
Public methodGetCurrentValueAsFrozenCreates a frozen copy of the Freezable using current property values. Because the copy is frozen, any frozen sub-objects are copied by reference. (Inherited from Freezable.)
Protected methodGetCurrentValueAsFrozenCoreMakes the current instance a frozen clone of the specified Freezable. If the object has animated dependency properties, their current animated values are copied. (Inherited from Freezable.)
Public methodGetHashCodeGets a hash code for this DependencyObject. (Inherited from DependencyObject.)
Public methodStatic memberGetIsHitTestVisibleInChromeGets the value of the IsHitTestVisibleInChrome attached property from the specified input element.
Public methodGetLocalValueEnumeratorCreates a specialized enumerator for determining which dependency properties have locally set values on this DependencyObject. (Inherited from DependencyObject.)
Public methodStatic memberGetResizeGripDirectionGets the value of the ResizeGripDirection attached property from the specified input element.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodGetValueReturns the current effective value of a dependency property on this instance of a DependencyObject. (Inherited from DependencyObject.)
Public methodStatic memberGetWindowChromeGets the value of the WindowChrome attached property from the specified Window.
Public methodInvalidatePropertyRe-evaluates the effective value for the specified dependency property (Inherited from DependencyObject.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnChangedCalled when the current Freezable object is modified. (Inherited from Freezable.)
Protected methodOnFreezablePropertyChanged(DependencyObject, DependencyObject)Ensures that appropriate context pointers are established for a DependencyObjectType data member that has just been set. (Inherited from Freezable.)
Protected methodOnFreezablePropertyChanged(DependencyObject, DependencyObject, DependencyProperty)This member supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used directly from your code. (Inherited from Freezable.)
Protected methodOnPropertyChangedOverrides the DependencyObject implementation of OnPropertyChanged to also invoke any Changed handlers in response to a changing dependency property of type Freezable. (Inherited from Freezable.)
Public methodReadLocalValueReturns the local value of a dependency property, if it exists. (Inherited from DependencyObject.)
Protected methodReadPreambleEnsures that the Freezable is being accessed from a valid thread. Inheritors of Freezable must call this method at the beginning of any API that reads data members that are not dependency properties. (Inherited from Freezable.)
Public methodSetCurrentValueSets the value of a dependency property without changing its value source. (Inherited from DependencyObject.)
Public methodStatic memberSetIsHitTestVisibleInChromeSets the value of the IsHitTestVisibleInChrome attached property on the specified input element.
Public methodStatic memberSetResizeGripDirectionSets the value of the ResizeGripDirection attached property on the specified input element.
Public methodSetValue(DependencyProperty, Object)Sets the local value of a dependency property, specified by its dependency property identifier. (Inherited from DependencyObject.)
Public methodSetValue(DependencyPropertyKey, Object)Sets the local value of a read-only dependency property, specified by the DependencyPropertyKey identifier of the dependency property. (Inherited from DependencyObject.)
Public methodStatic memberSetWindowChromeSets the value of the WindowChrome attached property on the specified Window.
Protected methodShouldSerializePropertyReturns a value that indicates whether serialization processes should serialize the value for the provided dependency property. (Inherited from DependencyObject.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodVerifyAccessEnforces that the calling thread has access to this DispatcherObject. (Inherited from DispatcherObject.)
Protected methodWritePostscriptRaises the Changed event for the Freezable and invokes its OnChanged method. Classes that derive from Freezable should call this method at the end of any API that modifies class members that are not stored as dependency properties. (Inherited from Freezable.)
Protected methodWritePreambleVerifies that the Freezable is not frozen and that it is being accessed from a valid threading context. Freezable inheritors should call this method at the beginning of any API that writes to data members that are not dependency properties. (Inherited from Freezable.)
Top

  NameDescription
Public eventChangedOccurs when the Freezable or an object it contains is modified. (Inherited from Freezable.)
Top

  NameDescription
Public fieldStatic memberCaptionHeightPropertyIdentifies the CaptionHeight dependency property.
Public fieldStatic memberCornerRadiusPropertyIdentifies the CornerRadius dependency property.
Public fieldStatic memberGlassFrameThicknessPropertyIdentifies the GlassFrameThickness dependency property.
Public fieldStatic memberIsHitTestVisibleInChromePropertyIdentifies the IsHitTestVisibleInChrome dependency property.
Public fieldStatic memberNonClientFrameEdgesPropertyIdentifies the NonClientFrameEdges dependency property.
Public fieldStatic memberResizeBorderThicknessPropertyIdentifies the ResizeBorderThickness dependency property.
Public fieldStatic memberResizeGripDirectionPropertyIdentifies the ResizeGripDirection dependency property.
Public fieldStatic memberUseAeroCaptionButtonsPropertyIdentifies the UseAeroCaptionButtons dependency property.
Public fieldStatic memberWindowChromePropertyIdentifies the WindowChrome dependency property.
Top

The WindowChrome class enables you to extend Windows Presentation Foundation (WPF) content into the non-client area of a window that is typically reserved for the operating system’s window manager.

Standard Windows

Standard windows are composed of two overlapping rectangles. The outer rectangle is the non-client area, which is often referred to as chrome. It is drawn and managed by the operating system’s window manager. Its dimensions are determined by standard operating system settings. The non-client frame provides standard window features and behaviors. These include caption buttons (Minimize, Maximize, and Close), the window border, resize and move behaviors, the application icon and title, and the system menu. The inner rectangle is the client area. It contains the contents of your application, and it is drawn and managed by the application. For more information about windows in WPF applications, see WPF Windows Overview.

The following illustration shows the parts of a standard window.

Window elements

Custom Windows

You can customize a window border by setting the Window.WindowStyle property to None or by using the WindowChrome class.

One way to customize the appearance of a WPF application window is to set the Window.WindowStyle property to None. This removes the non-client frame from the window and leaves only the client area, to which you can apply a custom style. However, when the non-client frame is removed, you also lose the system features and behaviors that it provides, such as caption buttons and window resizing. Another side effect is that the window will cover the Windows taskbar when it is maximized. Setting WindowStyle.None enables you to create a completely custom application, but also requires that you implement custom logic in your application to emulate standard window behavior.

To customize a window while retaining its standard functionality, you can use the WindowChrome class. The WindowChrome class separates the functionality of the window frame from the visuals, and lets you control the boundary between the client and non-client areas of your application window. The WindowChrome class lets you put WPF content in the window frame by extending the client area to cover the non-client area. At the same time, it retains system behaviors through two invisible areas; the resize border and caption areas.

There are two main parts to creating a custom window using the WindowChrome class. First, you customize the non-client part of the window by setting properties exposed on the WindowChrome object. Then you provide a template for the window that defines the part of your application that is extended into the non-client area.The properties exposed on the WindowChrome object are ResizeBorderThickness, CaptionHeight, CornerRadius, and GlassFrameThickness.

The ResizeBorderThickness property specifies an invisible border around the outside of the application window that the user can click-and-drag to resize the window.

The CaptionHeight property specifies an invisible area at the top of the window that enables system behaviors typically associated with the title bar. These behaviors include: click and drag to move the window, double-click to maximize the window, and right-click to show the system menu.

The resize border and caption area do not have any visual elements; they only define areas that respond to input and enable standard system-provided window behaviors.

The CornerRadius property specifies the amount that the corners of the window are rounded. This property does not have any effect if the glass frame is enabled for a window.

The GlassFrameThickness property specifies the width of the glass frame around the window. By default, it uses the system value specified by the WindowNonClientFrameThickness property to emulate the appearance of a standard window. When the glass frame is used, the caption buttons for Minimize, Maximize, and Close are visible and interactive. The application is responsible for displaying the application icon and caption text. You can set the GlassFrameThickness property to make the glass frame wider or narrower than the default.

Caution noteCaution

The size of the caption buttons does not change when the GlassFrameThickness property is changed. If the height of the top of the glass frame is less than the height of the caption buttons, the caption buttons will not be completely visible.

To make a custom window that does not have a glass frame, set the GlassFrameThickness property to a uniform value of 0. This will disable and hide the standard caption buttons.

To extend the glass frame to cover the entire window, set the GlassFrameThickness property to a negative value on any side. When the GlassFrameThickness property is set to a negative value for any side, its coerced value will be equal to GlassFrameCompleteThickness.

NoteNote

Aero is a set of visual enhancements to the look and functionality of the Windows desktop that was introduced in Windows Vista. One of the more visually obvious features of Aero is translucent glass window borders. Windows Aero is enabled by the desktop composition feature of the Desktop Window Manager (DWM).

Windows Aero glass effects are not supported on all operating systems, and can be disabled on supported operating systems. If Windows Aero is not available, the glass frame will not be displayed regardless of the GlassFrameThickness property value. The border area specified by this property will appear black instead.Check the IsGlassEnabled property to verify that Windows Aero glass effects are available. If glass effects are not available, you should provide an alternate window style that does not use the glass frame or use the standard window by setting the window style to null.

You extend your WPF content into the window frame by specifying a ControlTemplate that defines the appearance and behavior of the frame content. You set the TargetType of the ControlTemplate to the type of the window that you are customizing.

<ControlTemplate TargetType="{x:Type local:MainWindow}">

By default, the parts of any visual elements that are within the non-client area of the window are not interactive. To enable interactive elements in the non-client area, attach the WindowsChrome.IsHitTestVisibleInChrome attached property to the element and set it to true.

The following XAML markup shows the main elements needed to customize a window using the WindowChrome class.

<Style x:Key="StandardStyle" TargetType="{x:Type local:MainWindow}">
    <Setter Property="shell:WindowChrome.WindowChrome">
        <Setter.Value>
            <shell:WindowChrome />
        </Setter.Value>
    </Setter>
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="{x:Type local:MainWindow}">
                <Grid>
                    <Border Background="White"
                            Margin="{Binding Source={x:Static shell:SystemParameters2.Current}, Path=WindowNonClientFrameThickness}">
                        <ContentPresenter Content="{TemplateBinding Content}" />
                    </Border>
                    <TextBlock Text="{Binding RelativeSource={RelativeSource TemplatedParent}, Path=Title}" 
                               VerticalAlignment="Top" HorizontalAlignment="Left" 
                               Margin="36,8,0,0"/>
                    <Image Source="{Binding RelativeSource={RelativeSource TemplatedParent}, Path=Icon}"
                           VerticalAlignment="Top" HorizontalAlignment="Left"
                           Margin="{Binding RelativeSource={RelativeSource TemplatedParent}, Path=(shell:WindowChrome.WindowChrome).ResizeBorderThickness}" 
                           Width="{Binding Source={x:Static shell:SystemParameters2.Current}, Path=SmallIconSize.Width}"
                           shell:WindowChrome.IsHitTestVisibleInChrome="True"/>
                </Grid>
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>

The first setter attaches the WindowChrome to the window. It uses all default values for the WindowChrome properties, which makes the window look like a standard window.

<Setter Property="shell:WindowChrome.WindowChrome">
    <Setter.Value>
        <shell:WindowChrome />
    </Setter.Value>
</Setter>

The window template must specify a content presenter to display the contents of the window specified in your application. By default the WindowChrome class extends the client area to cover the non-client border. In order to uncover the glass frame, you need to specify a margin around the ContentPresenter. This markup specifies a border with a white background around the content presenter to emulate the appearance of a standard window. It also specifies a margin that is bound to the WindowNonClientFrameThickness property, which gets the default system width for the frame.

<Border Background="White"
    Margin="{Binding Source={x:Static shell:SystemParameters2.Current}, Path=WindowNonClientFrameThickness}">
    <ContentPresenter Content="{TemplateBinding Content}" />
</Border>

The application icon and title are not displayed by the WindowChrome class; they have to be added to the border as custom content. The following XAML adds an image and a textblock to display the icon and title. Both elements are bound to the corresponding properties on the window. The image width is bound to the SmallIconSize width, which gets the default system size for the icon. The IsHitTestVisibleInChrome attached property is set on the image so that it can receive mouse events.

<Image Source="{Binding RelativeSource={RelativeSource TemplatedParent}, Path=Icon}"
       VerticalAlignment="Top" HorizontalAlignment="Left"
       Margin="{Binding RelativeSource={RelativeSource TemplatedParent}, Path=(shell:WindowChrome.WindowChrome).ResizeBorderThickness}" 
       Width="{Binding Source={x:Static shell:SystemParameters2.Current}, Path=SmallIconSize.Width}"
       shell:WindowChrome.IsHitTestVisibleInChrome="True"/>


<TextBlock Text="{Binding RelativeSource={RelativeSource TemplatedParent}, Path=Title}" 
           VerticalAlignment="Top" HorizontalAlignment="Left" 
           Margin="36,8,0,0"/>

.NET Framework

Supported in: 4.6, 4.5

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft