Visual Class

Definition

Provides rendering support in WPF, which includes hit testing, coordinate transformation, and bounding box calculations.

public abstract class Visual : System.Windows.DependencyObject
Inheritance
Derived

Remarks

The Visual class is the basic abstraction from which every FrameworkElement object derives. It also serves as the entry point for writing new controls in WPF, and in many ways can be thought of as an equivalent of a window handle (HWND) in the Win32 application model.

The Visual object is a core WPF object, whose primary role is to provide rendering support. User interface controls, such as Button and TextBox, derive from the Visual class, and use the Visual defined properties for persisting their rendering data. The Visual object provides support for the following:

  • Output display: Rendering the persisted, serialized drawing content of a visual.

  • Transformations: Performing transformations on a visual.

  • Clipping: Providing clipping region support for a visual.

  • Hit testing: Determining whether a specified coordinate (point) or geometry is contained within the bounds of a visual.

  • Bounding box calculations: Determining the bounding rectangle of a visual.

Architecturally, the Visual object does not include support for other application development requirements / WPF features that are not immediately related to its rendering, such as the following:

  • Event handling

  • Layout

  • Styles

  • Data binding

  • Globalization

Visual is provided as a public abstract class from which further classes can be derived. The following illustration shows the hierarchy of the existing visual objects that are defined in the WPF architecture.

Diagram of classes derived from the Visual object
Visual class hierarchy

In some cases, members that are defined as protected in Visual are exposed as more readily accessible members with similar names in the derived UIElement class.

For more information, see WPF Graphics Rendering Overview.

A Visual has a limited number of levels. In previous versions of the .NET Framework, this maximum depth was 255. This limit is inadequate for some layouts that have many levels in the visual tree.

In .NET Framework 4, the maximum depth of a Visual is 2047, which enables much deeper visual trees. In most applications, there is not enough stack space to traverse so many levels, and the result is a StackOverflowException during layout. For the default stack size, this exception is usually thrown when the tree depth is approximately 800, which corresponds to about 190 nested TreeViewItem objects.

If this exception is thrown by your application and you need to have a deeper visual tree, you can increase the application's stack size. You can increase the size of the stack by using the /STACK option at compile time or by using the EDITBIN utility. Increasing the stack size may affect your application's performance. For more information, see Stack Allocations and EDITBIN Options.

Constructors

Visual()

Provides the base initialization for objects derived from the Visual class.

Properties

VisualBitmapEffect

Gets or sets the BitmapEffect value for the Visual.

VisualBitmapEffectInput

Gets or sets the BitmapEffectInput value for the Visual.

VisualBitmapScalingMode

Gets or sets the BitmapScalingMode for the Visual.

VisualCacheMode

Gets or sets a cached representation of the Visual.

VisualChildrenCount

Gets the number of child elements for the Visual.

VisualClearTypeHint

Gets or sets the ClearTypeHint that determines how ClearType is rendered in the Visual.

VisualClip

Gets or sets the clip region of the Visual as a Geometry value.

VisualEdgeMode

Gets or sets the edge mode of the Visual as an EdgeMode value.

VisualEffect

Gets or sets the bitmap effect to apply to the Visual.

VisualOffset

Gets or sets the offset value of the visual object.

VisualOpacity

Gets or sets the opacity of the Visual.

VisualOpacityMask

Gets or sets the Brush value that represents the opacity mask of the Visual.

VisualParent

Gets the visual tree parent of the visual object.

VisualScrollableAreaClip

Gets or sets a clipped scrollable area for the Visual.

VisualTextHintingMode

Gets or sets the TextHintingMode of the Visual.

VisualTextRenderingMode

Gets or sets the TextRenderingMode of the Visual.

VisualTransform

Gets or sets the Transform value for the Visual.

VisualXSnappingGuidelines

Gets or sets the x-coordinate (vertical) guideline collection.

VisualYSnappingGuidelines

Gets or sets the y-coordinate (horizontal) guideline collection.

Methods

AddVisualChild(Visual)

Defines the parent-child relationship between two visuals.

FindCommonVisualAncestor(DependencyObject)

Returns the common ancestor of two visual objects.

GetVisualChild(Int32)

Returns the specified Visual in the parent VisualCollection.

HitTestCore(GeometryHitTestParameters)

Determines whether a geometry value is within the bounds of the visual object.

HitTestCore(PointHitTestParameters)

Determines whether a point coordinate value is within the bounds of the visual object.

IsAncestorOf(DependencyObject)

Determines whether the visual object is an ancestor of the descendant visual object.

IsDescendantOf(DependencyObject)

Determines whether the visual object is a descendant of the ancestor visual object.

OnDpiChanged(DpiScale, DpiScale)

Called when the DPI at which this View is rendered changes.

OnVisualChildrenChanged(DependencyObject, DependencyObject)

Called when the VisualCollection of the visual object is modified.

OnVisualParentChanged(DependencyObject)

Called when the parent of the visual object is changed.

PointFromScreen(Point)

Converts a Point in screen coordinates into a Point that represents the current coordinate system of the Visual.

PointToScreen(Point)

Converts a Point that represents the current coordinate system of the Visual into a Point in screen coordinates.

RemoveVisualChild(Visual)

Removes the parent-child relationship between two visuals.

TransformToAncestor(Visual3D)

Returns a transform that can be used to transform coordinates from the Visual to the specified Visual3D ancestor of the visual object.

TransformToAncestor(Visual)

Returns a transform that can be used to transform coordinates from the Visual to the specified Visual ancestor of the visual object.

TransformToDescendant(Visual)

Returns a transform that can be used to transform coordinates from the Visual to the specified visual object descendant.

TransformToVisual(Visual)

Returns a transform that can be used to transform coordinates from the Visual to the specified visual object.

Equals(Object, Object) Inherited from Object
GetType() Inherited from Object
MemberwiseClone() Inherited from Object
ReferenceEquals(Object, Object) Inherited from Object
ToString() Inherited from Object
ClearValue(DependencyProperty) Inherited from DependencyObject
ClearValue(DependencyPropertyKey) Inherited from DependencyObject
CoerceValue(DependencyProperty) Inherited from DependencyObject
DependencyObjectType Inherited from DependencyObject
Equals(Object) Inherited from DependencyObject
GetHashCode() Inherited from DependencyObject
GetLocalValueEnumerator() Inherited from DependencyObject
GetValue(DependencyProperty) Inherited from DependencyObject
InvalidateProperty(DependencyProperty) Inherited from DependencyObject
IsSealed Inherited from DependencyObject
OnPropertyChanged(DependencyPropertyChangedEventArgs) Inherited from DependencyObject
ReadLocalValue(DependencyProperty) Inherited from DependencyObject
SetCurrentValue(DependencyProperty, Object) Inherited from DependencyObject
SetValue(DependencyProperty, Object) Inherited from DependencyObject
SetValue(DependencyPropertyKey, Object) Inherited from DependencyObject
ShouldSerializeProperty(DependencyProperty) Inherited from DependencyObject
CheckAccess() Inherited from DispatcherObject
Dispatcher Inherited from DispatcherObject
VerifyAccess() Inherited from DispatcherObject

Applies to