Export (0) Print
Expand All

VisualBrush.Visual Property

Gets or sets the brush's content.

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

'Declaration
Public Property Visual As Visual
<object>
  <object.Visual>
    singleVisualRoot
  </object.Visual>
</object>
<object Visual="{bindingExpression}"/>- or - <object Visual="{resourceExpression}"/>

XAML Values

singleVisualRoot

A single object element that defines a new visual element for the brush. This must be an object that derives from Visual. See Remarks.

bindingExpression

A Binding that evaluates to an existing Visual instance.

resourceExpression

A StaticResource or DynamicResource that evaluates to an existing Visual instance. See XAML Resources

Property Value

Type: System.Windows.Media.Visual
The brush's content. The default is Nothing.

Identifier field

VisualProperty

Metadata properties set to true

None

There are two ways to specify the Visual content of a VisualBrush.

  • Create a new Visual and use it to set the Visual property of the VisualBrush.

  • Use an existing Visual, which creates a duplicate image of the target Visual. You can then use the VisualBrush to create interesting effects, such as reflection and magnification.

Visual is quite high in the overall WPF class hierarchy, so a very large number of objects could possibly serve as the visual that you use for a VisualBrush; the entire list cannot be shown here. See Visual; refer to the "Inheritance Hierarchy" section, which will show the immediately derived classes. You can then click on the immediately derived classes and traverse the hierarchies to get a sense of the full range of possibilities. At a top level, the two most common categories of objects you might use for a VisualBrush are UIElement or ContainerVisual. UIElement encompasses basically any UI element that can otherwise participate in the UI for a WPF application. ContainerVisual contains a DrawingGroup that includes one or more Drawing-derived objects.

When you define a new Visual for a VisualBrush and that Visual is a UIElement (such as a panel or control), the layout system runs on the UIElement and its child elements when the AutoLayoutContent property is set to true. However, the root UIElement is essentially isolated from the rest of the system; styles, storyboards, and external layout dictated by the parent where the brush is applied cannot permeate this boundary. Therefore, you should explicitly specify the size of the root UIElement, because its only parent is the VisualBrush and therefore it cannot automatically size itself to the area being painted. For more information about layout in Windows Presentation Foundation (WPF), see the Layout.

Updates to the visual tree of a VisualBrush will not propagate if a BitmapEffect is in the brush's parent chain. You can workaround this limitation by forcing an update of the scene on the object above the effect. You can call InvalidateVisual or include an animation to force a scene update.

NoteNote

A VisualBrush cannot be made read-only (frozen) when its Visual property is set to any value other than null.

This example shows how to use the VisualBrush class to paint an area with a Visual.

In the following example, several controls and a panel are used as the background of a rectangle.

<Rectangle Width="150" Height="150" Stroke="Black" Margin="5,0,5,0">
  <Rectangle.Fill>
    <VisualBrush>
      <VisualBrush.Visual>
        <StackPanel Background="White">
          <Rectangle Width="25" Height="25" Fill="Red" Margin="2" />
          <TextBlock FontSize="10pt" Margin="2">Hello, World!</TextBlock>
          <Button Margin="2">A Button</Button>
        </StackPanel>
      </VisualBrush.Visual>
    </VisualBrush>
  </Rectangle.Fill>
</Rectangle>
			Dim myVisualBrush As New VisualBrush()

			' Create the visual brush's contents.
			Dim myStackPanel As New StackPanel()
			myStackPanel.Background = Brushes.White

            Dim redRectangle As New Rectangle()
            With redRectangle
                .Width = 25
                .Height = 25
                .Fill = Brushes.Red
                .Margin = New Thickness(2)
            End With
            myStackPanel.Children.Add(redRectangle)

            Dim someText As New TextBlock()
            Dim myFontSizeConverter As New FontSizeConverter()
            someText.FontSize = CDbl(myFontSizeConverter.ConvertFrom("10pt"))
            someText.Text = "Hello, World!"
            someText.Margin = New Thickness(2)
            myStackPanel.Children.Add(someText)

            Dim aButton As New Button()
            aButton.Content = "A Button"
            aButton.Margin = New Thickness(2)
            myStackPanel.Children.Add(aButton)

            ' Use myStackPanel as myVisualBrush's content.
            myVisualBrush.Visual = myStackPanel

            ' Create a rectangle to paint.
            Dim myRectangle As New Rectangle()
            With myRectangle
                .Width = 150
                .Height = 150
                .Stroke = Brushes.Black
                .Margin = New Thickness(5, 0, 5, 0)
            End With

            ' Use myVisualBrush to paint myRectangle.
            myRectangle.Fill = myVisualBrush

For more information about VisualBrush and additional examples, see the Painting with Images, Drawings, and Visuals overview.

This code example is part of a larger example provided for the VisualBrush class. For the complete sample, see the VisualBrush Sample.

.NET Framework

Supported in: 4.6, 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