WindowChrome Class

Definition

public ref class WindowChrome : System::Windows::Freezable

public class WindowChrome : System.Windows.Freezable

type WindowChrome = class
    inherit Freezable

Public Class WindowChrome
Inherits Freezable

Inheritance

Object

DispatcherObject

DependencyObject

Freezable

WindowChrome

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.

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.

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.

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

Constructors

Fields

Properties

Attached Properties

Methods

Events

Applies to