Verwenden von DrawingVisual-ObjektenUsing DrawingVisual Objects

Dieses Thema enthält eine Übersicht über die Verwendung DrawingVisual von Objekten in der WPFWPF visuellen Schicht.This topic provides an overview of how to use DrawingVisual objects in the WPFWPF visual layer.

DrawingVisual-ObjektDrawingVisual Object

DrawingVisual Ist eine vereinfachte Zeichnungs Klasse, die zum Rendering von Formen, Bildern oder Text verwendet wird.The DrawingVisual is a lightweight drawing class that is used to render shapes, images, or text. Diese Klasse wird als einfach angesehen, weil sie weder Layout noch Ereignisbehandlung bereitstellt. Dadurch wird die Leistung gesteigert.This class is considered lightweight because it does not provide layout or event handling, which improves its performance. Aus diesem Grund sind Zeichnungen für Hintergründe und ClipArt ideal.For this reason, drawings are ideal for backgrounds and clip art.

DrawingVisual-HostcontainerDrawingVisual Host Container

Um-Objekte verwenden DrawingVisual zu können, müssen Sie einen Host Container für die-Objekte erstellen.In order to use DrawingVisual objects, you need to create a host container for the objects. Das Host Container Objekt muss von der FrameworkElement -Klasse abgeleitet werden, die die Unterstützung für Layout und Ereignis Behandlung bereitstellt, die der DrawingVisual -Klasse fehlt.The host container object must derive from the FrameworkElement class, which provides the layout and event handling support that the DrawingVisual class lacks. Das Hostcontainerobjekt zeigt keine sichtbaren Eigenschaften, da seine Hauptfunktion die Aufnahme untergeordneter Objekte ist.The host container object does not display any visible properties, since its main purpose is to contain child objects. Allerdings muss Visibility die-Eigenschaft des Host Containers auf Visiblefestgelegt werden. andernfalls ist keines der untergeordneten Elemente sichtbar.However, the Visibility property of the host container must be set to Visible; otherwise, none of its child elements will be visible.

Wenn Sie ein Host Container Objekt für visuelle Objekte erstellen, müssen Sie die visuellen Objekt Verweise in einer VisualCollectionspeichern.When you create a host container object for visual objects, you need to store the visual object references in a VisualCollection. Verwenden Sie Add die-Methode, um dem Host Container ein visuelles Objekt hinzuzufügen.Use the Add method to add a visual object to the host container. Im folgenden Beispiel wird ein Host Container Objekt erstellt, und es VisualCollectionwerden drei visuelle Objekte zu hinzugefügt.In the following example, a host container object is created, and three visual objects are added to its VisualCollection.

// Create a host visual derived from the FrameworkElement class.
// This class provides layout, event handling, and container support for
// the child visual objects.
public class MyVisualHost : FrameworkElement
{
    // Create a collection of child visual objects.
    private VisualCollection _children;

    public MyVisualHost()
    {
        _children = new VisualCollection(this);
        _children.Add(CreateDrawingVisualRectangle());
        _children.Add(CreateDrawingVisualText());
        _children.Add(CreateDrawingVisualEllipses());

        // Add the event handler for MouseLeftButtonUp.
        this.MouseLeftButtonUp += new System.Windows.Input.MouseButtonEventHandler(MyVisualHost_MouseLeftButtonUp);
    }
' Create a host visual derived from the FrameworkElement class.
' This class provides layout, event handling, and container support for
' the child visual objects.
Public Class MyVisualHost
    Inherits FrameworkElement
    ' Create a collection of child visual objects.
    Private _children As VisualCollection

    Public Sub New()
        _children = New VisualCollection(Me)
        _children.Add(CreateDrawingVisualRectangle())
        _children.Add(CreateDrawingVisualText())
        _children.Add(CreateDrawingVisualEllipses())

        ' Add the event handler for MouseLeftButtonUp.
        AddHandler MouseLeftButtonUp, AddressOf MyVisualHost_MouseLeftButtonUp
    End Sub

Hinweis

Informationen über das vollständige Codebeispiel, aus dem das vorherige Codebeispiel extrahiert wurde, finden Sie unter Beispiel für Treffertests mit DrawingVisuals.For the complete code sample from which the preceding code example was extracted, see Hit Test Using DrawingVisuals Sample.

Erstellen von DrawingVisual-ObjektenCreating DrawingVisual Objects

Wenn Sie ein DrawingVisual -Objekt erstellen, hat es keinen Zeichnungs Inhalt.When you create a DrawingVisual object, it has no drawing content. Sie können Text, Grafiken oder Bildinhalte hinzufügen, indem Sie das Objekt DrawingContext abrufen und darin zeichnen.You can add text, graphics, or image content by retrieving the object's DrawingContext and drawing into it. Eine DrawingContext wird durch Aufrufen der RenderOpen -Methode eines DrawingVisual -Objekts zurückgegeben.A DrawingContext is returned by calling the RenderOpen method of a DrawingVisual object.

Um ein Rechteck in die DrawingContextzu zeichnen, verwenden Sie die DrawRectangle - DrawingContext Methode des-Objekts.To draw a rectangle into the DrawingContext, use the DrawRectangle method of the DrawingContext object. Ähnliche Methoden sind für andere Arten von Inhalten verfügbar.Similar methods exist for drawing other types of content. Wenn Sie mit dem Zeichnen von Inhalt in DrawingContextdas fertig sind Close , müssen Sie die DrawingContext -Methode zum Schließen der und zum Speichern des Inhalts abrufen.When you are finished drawing content into the DrawingContext, call the Close method to close the DrawingContext and persist the content.

Im folgenden Beispiel wird ein DrawingVisual -Objekt erstellt, und ein Rechteck wird in seinen DrawingContextgezeichnet.In the following example, a DrawingVisual object is created, and a rectangle is drawn into its DrawingContext.

// Create a DrawingVisual that contains a rectangle.
private DrawingVisual CreateDrawingVisualRectangle()
{
    DrawingVisual drawingVisual = new DrawingVisual();

    // Retrieve the DrawingContext in order to create new drawing content.
    DrawingContext drawingContext = drawingVisual.RenderOpen();

    // Create a rectangle and draw it in the DrawingContext.
    Rect rect = new Rect(new System.Windows.Point(160, 100), new System.Windows.Size(320, 80));
    drawingContext.DrawRectangle(System.Windows.Media.Brushes.LightBlue, (System.Windows.Media.Pen)null, rect);

    // Persist the drawing content.
    drawingContext.Close();

    return drawingVisual;
}
' Create a DrawingVisual that contains a rectangle.
Private Function CreateDrawingVisualRectangle() As DrawingVisual
    Dim drawingVisual As New DrawingVisual()

    ' Retrieve the DrawingContext in order to create new drawing content.
    Dim drawingContext As DrawingContext = drawingVisual.RenderOpen()

    ' Create a rectangle and draw it in the DrawingContext.
    Dim rect As New Rect(New Point(160, 100), New Size(320, 80))
    drawingContext.DrawRectangle(Brushes.LightBlue, CType(Nothing, Pen), rect)

    ' Persist the drawing content.
    drawingContext.Close()

    Return drawingVisual
End Function

Erstellen von Überschreibungen für Elemente von FrameworkElementCreating Overrides for FrameworkElement Members

Der Hostcontainerobjekt ist für die Verwaltung seiner Auflistung von visuellen Objekten zuständig.The host container object is responsible for managing its collection of visual objects. Dies erfordert, dass der Host Container Member-über Schreibungen für die FrameworkElement abgeleitete Klasse implementiert.This requires that the host container implement member overrides for the derived FrameworkElement class.

Die folgende Liste beschreibt die zwei Elemente, die Sie überschreiben müssen:The following list describes the two members you must override:

  • GetVisualChild: Gibt ein untergeordnetes Element am angegebenen Index aus der Auflistung der untergeordneten Elemente zurück.GetVisualChild: Returns a child at the specified index from the collection of child elements.

  • VisualChildrenCount: Ruft die Anzahl der sichtbaren untergeordneten Elemente innerhalb dieses Elements ab.VisualChildrenCount: Gets the number of visual child elements within this element.

Im folgenden Beispiel werden außer Kraft setzungen für die beiden FrameworkElement Member implementiert.In the following example, overrides for the two FrameworkElement members are implemented.


// Provide a required override for the VisualChildrenCount property.
protected override int VisualChildrenCount
{
    get { return _children.Count; }
}

// Provide a required override for the GetVisualChild method.
protected override Visual GetVisualChild(int index)
{
    if (index < 0 || index >= _children.Count)
    {
        throw new ArgumentOutOfRangeException();
    }

    return _children[index];
}


' Provide a required override for the VisualChildrenCount property.
Protected Overrides ReadOnly Property VisualChildrenCount() As Integer
    Get
        Return _children.Count
    End Get
End Property

' Provide a required override for the GetVisualChild method.
Protected Overrides Function GetVisualChild(ByVal index As Integer) As Visual
    If index < 0 OrElse index >= _children.Count Then
        Throw New ArgumentOutOfRangeException()
    End If

    Return _children(index)
End Function

Bereitstellen von Unterstützung für den TreffertestProviding Hit Testing Support

Das Host Container Objekt kann die Ereignis Behandlung auch dann bereitstellen, wenn es keine sichtbaren Eigenschaften anzeigt – Visibility seine-Eigenschaft muss jedoch Visibleauf festgelegt werden.The host container object can provide event handling even if it does not display any visible properties—however, its Visibility property must be set to Visible. Dadurch können Sie eine Ereignisbehandlungsroutine für den Hostcontainer erstellen, die Mausereignisse, z.B. das Loslassen der linken Maustaste, auffangen kann.This allows you to create an event handling routine for the host container that can trap mouse events, such as the release of the left mouse button. Die Ereignis Behandlungs Routine kann dann durch Aufrufen der HitTest -Methode Treffer Tests implementieren.The event handling routine can then implement hit testing by invoking the HitTest method. Der- HitTestResultCallback Parameter der Methode verweist auf eine benutzerdefinierte Prozedur, mit der Sie die resultierende Aktion eines Treffer Tests ermitteln können.The method's HitTestResultCallback parameter refers to a user-defined procedure that you can use to determine the resulting action of a hit test.

Im folgenden Beispiel wird die Unterstützung für Treffertests für das Hostcontainerobjekt und seine untergeordneten Elemente implementiert.In the following example, hit testing support is implemented for the host container object and its children.

// Capture the mouse event and hit test the coordinate point value against
// the child visual objects.
void MyVisualHost_MouseLeftButtonUp(object sender, System.Windows.Input.MouseButtonEventArgs e)
{
    // Retrieve the coordinates of the mouse button event.
    System.Windows.Point pt = e.GetPosition((UIElement)sender);

    // Initiate the hit test by setting up a hit test result callback method.
    VisualTreeHelper.HitTest(this, null, new HitTestResultCallback(myCallback), new PointHitTestParameters(pt));
}

// If a child visual object is hit, toggle its opacity to visually indicate a hit.
public HitTestResultBehavior myCallback(HitTestResult result)
{
    if (result.VisualHit.GetType() == typeof(DrawingVisual))
    {
        if (((DrawingVisual)result.VisualHit).Opacity == 1.0)
        {
            ((DrawingVisual)result.VisualHit).Opacity = 0.4;
        }
        else
        {
            ((DrawingVisual)result.VisualHit).Opacity = 1.0;
        }
    }

    // Stop the hit test enumeration of objects in the visual tree.
    return HitTestResultBehavior.Stop;
}
' Capture the mouse event and hit test the coordinate point value against
' the child visual objects.
Private Sub MyVisualHost_MouseLeftButtonUp(ByVal sender As Object, ByVal e As MouseButtonEventArgs)
    ' Retrieve the coordinates of the mouse button event.
    Dim pt As Point = e.GetPosition(CType(sender, UIElement))

    ' Initiate the hit test by setting up a hit test result callback method.
    VisualTreeHelper.HitTest(Me, Nothing, New HitTestResultCallback(AddressOf myCallback), New PointHitTestParameters(pt))
End Sub

' If a child visual object is hit, toggle its opacity to visually indicate a hit.
Public Function myCallback(ByVal result As HitTestResult) As HitTestResultBehavior
    If result.VisualHit.GetType() Is GetType(DrawingVisual) Then
        If (CType(result.VisualHit, DrawingVisual)).Opacity = 1.0 Then
            CType(result.VisualHit, DrawingVisual).Opacity = 0.4
        Else
            CType(result.VisualHit, DrawingVisual).Opacity = 1.0
        End If
    End If

    ' Stop the hit test enumeration of objects in the visual tree.
    Return HitTestResultBehavior.Stop
End Function

Siehe auchSee also