WindowChrome Class

Article
02/04/2013

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

Inheritance Hierarchy

System.Object
  System.Windows.Threading.DispatcherObject
    System.Windows.DependencyObject
      System.Windows.Freezable
        Microsoft.Windows.Shell.WindowChrome

Namespace: Microsoft.Windows.Shell
Assembly: Microsoft.Windows.Shell (in Microsoft.Windows.Shell.dll)

Syntax

'Declaration
Public Class WindowChrome _
    Inherits Freezable

public class WindowChrome : Freezable

public ref class WindowChrome : public Freezable

type WindowChrome =  
    class
        inherit Freezable
    end

public class WindowChrome extends Freezable

The WindowChrome type exposes the following members.

Constructors

	Name	Description
	WindowChrome	Initializes a new instance of the WindowChrome class.

Top

Properties

	Name	Description
	CanFreeze	Gets a value that indicates whether the object can be made unmodifiable. (Inherited from Freezable.)
	CaptionHeight	Gets or sets the height of the caption area at the top of a window.
	CornerRadius	Gets or sets a value that indicates the amount that the corners of a window are rounded.
	DependencyObjectType	Gets the DependencyObjectType that wraps the CLR type of this instance. (Inherited from DependencyObject.)
	Dispatcher	Gets the Dispatcher this DispatcherObject is associated with. (Inherited from DispatcherObject.)
	GlassFrameCompleteThickness	Gets a uniform thickness of -1.
	GlassFrameThickness	Gets or sets a value that indicates the width of the glass border around a window.
	IsFrozen	Gets a value that indicates whether the object is currently modifiable. (Inherited from Freezable.)
	IsSealed	Gets a value that indicates whether this instance is currently sealed (read-only). (Inherited from DependencyObject.)
	NonClientFrameEdges	Gets or sets a value that indicates which edges of the window frame are not owned by the client.
	ResizeBorderThickness	Gets or sets a value that indicates the width of the border that is used to resize a window.
	UseAeroCaptionButtons	Gets or sets a value that indicates whether hit-testing is enabled on the Windows Aero caption buttons.

Top

Attached Properties

	Name	Description
	IsHitTestVisibleInChrome	Gets 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.
	ResizeGripDirection	Gets or sets a value that indicates the direction of the resize grip behavior on an input element.
	WindowChrome	Gets or sets the instance of WindowChrome that is attached to a window.

Top

Methods

	Name	Description
	CheckAccess	Determines whether the calling thread has access to this DispatcherObject. (Inherited from DispatcherObject.)
	ClearValue(DependencyProperty)	Clears the local value of a property. The property to be cleared is specified by a DependencyProperty identifier. (Inherited from DependencyObject.)
	ClearValue(DependencyPropertyKey)	Clears the local value of a read-only property. The property to be cleared is specified by a DependencyPropertyKey. (Inherited from DependencyObject.)
	Clone	Creates 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.)
	CloneCore	Makes the instance a clone (deep copy) of the specified Freezable using base (non-animated) property values. (Inherited from Freezable.)
	CloneCurrentValue	Creates a modifiable clone (deep copy) of the Freezable using its current values. (Inherited from Freezable.)
	CloneCurrentValueCore	Makes the instance a modifiable clone (deep copy) of the specified Freezable using current property values. (Inherited from Freezable.)
	CoerceValue	Coerces 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.)
	CreateInstance	Initializes a new instance of the Freezable class. (Inherited from Freezable.)
	CreateInstanceCore	Creates a new instance of the WindowChrome class. (Overrides Freezable.CreateInstanceCore().)
	Equals	Determines whether a provided DependencyObject is equivalent to the current DependencyObject. (Inherited from DependencyObject.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	Freeze	Makes the current object unmodifiable and sets its IsFrozen property to true. (Inherited from Freezable.)
	FreezeCore	Makes the Freezable object unmodifiable or tests whether it can be made unmodifiable. (Inherited from Freezable.)
	GetAsFrozen	Creates 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.)
	GetAsFrozenCore	Makes the instance a frozen clone of the specified Freezable using base (non-animated) property values. (Inherited from Freezable.)
	GetCurrentValueAsFrozen	Creates 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.)
	GetCurrentValueAsFrozenCore	Makes 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.)
	GetHashCode	Gets a hash code for this DependencyObject. (Inherited from DependencyObject.)
	GetIsHitTestVisibleInChrome	Gets the value of the IsHitTestVisibleInChrome attached property from the specified input element.
	GetLocalValueEnumerator	Creates a specialized enumerator for determining which dependency properties have locally set values on this DependencyObject. (Inherited from DependencyObject.)
	GetResizeGripDirection	Gets the value of the ResizeGripDirection attached property from the specified input element.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	GetValue	Returns the current effective value of a dependency property on this instance of a DependencyObject. (Inherited from DependencyObject.)
	GetWindowChrome	Gets the value of the WindowChrome attached property from the specified Window.
	InvalidateProperty	Re-evaluates the effective value for the specified dependency property (Inherited from DependencyObject.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	OnChanged	Called when the current Freezable object is modified. (Inherited from Freezable.)
	OnFreezablePropertyChanged(DependencyObject, DependencyObject)	Ensures that appropriate context pointers are established for a DependencyObjectType data member that has just been set. (Inherited from Freezable.)
	OnFreezablePropertyChanged(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.)
	OnPropertyChanged	Overrides the DependencyObject implementation of OnPropertyChanged to also invoke any Changed handlers in response to a changing dependency property of type Freezable. (Inherited from Freezable.)
	ReadLocalValue	Returns the local value of a dependency property, if it exists. (Inherited from DependencyObject.)
	ReadPreamble	Ensures 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.)
	SetIsHitTestVisibleInChrome	Sets the value of the IsHitTestVisibleInChrome attached property on the specified input element.
	SetResizeGripDirection	Sets the value of the ResizeGripDirection attached property on the specified input element.
	SetValue(DependencyProperty, Object)	Sets the local value of a dependency property, specified by its dependency property identifier. (Inherited from DependencyObject.)
	SetValue(DependencyPropertyKey, Object)	Sets the local value of a read-only dependency property, specified by the DependencyPropertyKey identifier of the dependency property. (Inherited from DependencyObject.)
	SetWindowChrome	Sets the value of the WindowChrome attached property on the specified Window.
	ShouldSerializeProperty	Returns a value that indicates whether serialization processes should serialize the value for the provided dependency property. (Inherited from DependencyObject.)
	ToString	Returns a string that represents the current object. (Inherited from Object.)
	VerifyAccess	Enforces that the calling thread has access to this DispatcherObject. (Inherited from DispatcherObject.)
	WritePostscript	Raises 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.)
	WritePreamble	Verifies 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

Events

	Name	Description
	Changed	Occurs when the Freezable or an object it contains is modified. (Inherited from Freezable.)

Top

Fields

	Name	Description
	CaptionHeightProperty	Identifies the CaptionHeight dependency property.
	CornerRadiusProperty	Identifies the CornerRadius dependency property.
	GlassFrameThicknessProperty	Identifies the GlassFrameThickness dependency property.
	IsHitTestVisibleInChromeProperty	Identifies the IsHitTestVisibleInChrome dependency property.
	NonClientFrameEdgesProperty	Identifies the NonClientFrameEdges dependency property.
	ResizeBorderThicknessProperty	Identifies the ResizeBorderThickness dependency property.
	ResizeGripDirectionProperty	Identifies the ResizeGripDirection dependency property.
	UseAeroCaptionButtonsProperty	Identifies the UseAeroCaptionButtons dependency property.
	WindowChromeProperty	Identifies the WindowChrome dependency property.

Top

Remarks

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.

WindowStyle.None

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.

WindowChrome

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
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.

Note

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"/>

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.