Export (0) Print
Expand All

FrameworkElement.FocusVisualStyle Property

Gets or sets a property that enables customization of appearance, effects, or other style characteristics that will apply to this element when it captures keyboard focus.

Namespace:  System.Windows
Assembly:  PresentationFramework (in PresentationFramework.dll)
XMLNS for XAML: http://schemas.microsoft.com/winfx/2006/xaml/presentation, http://schemas.microsoft.com/netfx/2007/xaml/presentation

public Style FocusVisualStyle { get; set; }
<object FocusVisualStyle="{resourceExtension styleResourceKey}"/>

XAML Values

resourceExtension

One of the following: StaticResource, or DynamicResource. See XAML Resources.

styleResourceKey

The key that identifies the style being requested. The key refers to an existing resource in a ResourceDictionary.

NoteNote

Property element syntax is technically possible, but not recommended. See Inline Styles and Templates. A binding reference using TemplateBinding or Binding is also possible, but uncommon.

Property Value

Type: System.Windows.Style
The desired style to apply on focus. The default value as declared in the dependency property is an empty static Style. However, the effective value at run time is often (but not always) a style as supplied by theme support for controls.

Identifier field

FocusVisualStyleProperty

Metadata properties set to true

None

This property affects visual appearance but does not report AffectsRender in metadata. This is because the visual appearance change is event-driven and may not apply at all times, and therefore should not generally report any visual or layout information in metadata.

Conceptually, the visual behavior of focus applied to a control should be coherent from control to control. The most sensible way to enforce coherence is to only change the focus visual style if you are composing an entire theme. Setting this property on individual control styles and not as part of a theme is not the intended usage of this property, because it may lead to a confusing user experience regarding keyboard focus. If you are intending control-specific behavior that is deliberately not coherent across a theme, a much better approach is to use triggers in styles for individual input state properties, such as IsFocused or IsKeyboardFocusWithin, and to do so in a way that does not visually interfere with any existing focus visual style. For more information on the design intention of FocusVisualStyle and alternative focus properties, see Styling for Focus in Controls, and FocusVisualStyle.

This example shows you how to create a focus visual style in resources and apply the style to a control, using the FocusVisualStyle property.

The following example defines a style that creates additional control compositing that only applies when that control is keyboard focused in the user interface (UI). This is accomplished by defining a style with a ControlTemplate, then referencing that style as a resource when setting the FocusVisualStyle property.

An external rectangle resembling a border is placed outside of the rectangular area. Unless otherwise modified, the sizing of the style uses the ActualHeight and ActualWidth of the rectangular control where the focus visual style is applied. This example sets negative values for the Margin to make the border appear slightly outside the focused control.

<Page
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
>
  <Page.Resources>
    <Style x:Key="MyFocusVisual">
      <Setter Property="Control.Template">
        <Setter.Value>
          <ControlTemplate>
            <Rectangle Margin="-2" StrokeThickness="1" Stroke="Red" StrokeDashArray="1 2"/>
          </ControlTemplate>
        </Setter.Value>
      </Setter>
    </Style>
  </Page.Resources>
  <StackPanel Background="Ivory" Orientation="Horizontal">
    <Canvas Width="10"/>
    <Button Width="100" Height="30" FocusVisualStyle="{DynamicResource MyFocusVisual}">
      Focus Here</Button>
    <Canvas Width="100"/>
    <Button Width="100" Height="30" FocusVisualStyle="{DynamicResource MyFocusVisual}">
      Focus Here</Button>
  </StackPanel>
</Page>

A FocusVisualStyle is additive to any control template style that comes either from an explicit style or a theme style; the primary style for a control can still be created by using a ControlTemplate and setting that style to the Style property.

Focus visual styles should be used consistently across a theme or a UI, rather than using a different one for each focusable element. For details, see Styling for Focus in Controls, and FocusVisualStyle.

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

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.

Show:
© 2014 Microsoft