Utilizzo degli oggetti DrawingVisualUsing DrawingVisual Objects

In questo argomento viene fornita una panoramica su come DrawingVisual utilizzare gli oggetti a livello di oggetto visivo.WPFWPFThis topic provides an overview of how to use DrawingVisual objects in the WPFWPF visual layer.

Oggetto DrawingVisualDrawingVisual Object

DrawingVisual È una classe di disegno semplificata utilizzata per il rendering di forme, immagini o testo.The DrawingVisual is a lightweight drawing class that is used to render shapes, images, or text. Questa classe è considerata semplice perché non offre la gestione di layout o eventi, con un conseguente aumento delle prestazioni.This class is considered lightweight because it does not provide layout or event handling, which improves its performance. Per questo motivo, i disegni sono ideali per sfondi e ClipArt.For this reason, drawings are ideal for backgrounds and clip art.

Contenitore host di DrawingVisualDrawingVisual Host Container

Per usare DrawingVisual gli oggetti, è necessario creare un contenitore host per gli oggetti.In order to use DrawingVisual objects, you need to create a host container for the objects. L'oggetto contenitore host deve derivare dalla FrameworkElement classe, che fornisce il layout e il supporto per la gestione DrawingVisual degli eventi che la classe non dispone di.The host container object must derive from the FrameworkElement class, which provides the layout and event handling support that the DrawingVisual class lacks. Tramite l'oggetto contenitore host non vengono visualizzate proprietà visibili, poiché lo scopo principale di questo oggetto è quello di contenere oggetti figlio.The host container object does not display any visible properties, since its main purpose is to contain child objects. Tuttavia, la Visibility proprietà del contenitore host deve essere impostata su Visible; in caso contrario, nessuno degli elementi figlio sarà visibile.However, the Visibility property of the host container must be set to Visible; otherwise, none of its child elements will be visible.

Quando si crea un oggetto contenitore host per oggetti visivi, è necessario archiviare i riferimenti agli oggetti visivi VisualCollectionin un oggetto.When you create a host container object for visual objects, you need to store the visual object references in a VisualCollection. Usare il Add metodo per aggiungere un oggetto visivo al contenitore host.Use the Add method to add a visual object to the host container. Nell'esempio seguente viene creato un oggetto contenitore host e tre oggetti visivi vengono aggiunti a VisualCollection.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

Nota

Per l'esempio di codice completo dal quale è stato estratto l'esempio di codice precedente, vedere Hit Test Using DrawingVisuals Sample (Esempio di Hit Test mediante DrawingVisual).For the complete code sample from which the preceding code example was extracted, see Hit Test Using DrawingVisuals Sample.

Creazione di oggetti DrawingVisualCreating DrawingVisual Objects

Quando si crea un DrawingVisual oggetto, il contenuto non viene disegnato.When you create a DrawingVisual object, it has no drawing content. È possibile aggiungere contenuto di testo, grafica o immagine recuperando l'oggetto DrawingContext e creandone il contenuto.You can add text, graphics, or image content by retrieving the object's DrawingContext and drawing into it. Una DrawingContext viene restituita chiamando il RenderOpen metodo di un DrawingVisual oggetto.A DrawingContext is returned by calling the RenderOpen method of a DrawingVisual object.

Per creare un rettangolo in DrawingContext, utilizzare il DrawRectangle metodo dell' DrawingContext oggetto.To draw a rectangle into the DrawingContext, use the DrawRectangle method of the DrawingContext object. Sono disponibili metodi simili per disegnare altri tipi di contenuto.Similar methods exist for drawing other types of content. Al termine della creazione del contenuto in DrawingContext, chiamare il Close metodo per chiudere DrawingContext e salvare in modo permanente il contenuto.When you are finished drawing content into the DrawingContext, call the Close method to close the DrawingContext and persist the content.

Nell'esempio seguente viene creato un DrawingVisual oggetto e viene disegnato un rettangolo nel relativo. DrawingContextIn 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

Creazione di override per i membri FrameworkElementCreating Overrides for FrameworkElement Members

L'oggetto contenitore host è responsabile della gestione della raccolta di oggetti visivi.The host container object is responsible for managing its collection of visual objects. A tale scopo, è necessario che il contenitore host implementi FrameworkElement gli override del membro per la classe derivata.This requires that the host container implement member overrides for the derived FrameworkElement class.

L'elenco seguente descrive due membri per i quali è necessario eseguire l'override:The following list describes the two members you must override:

  • GetVisualChild: Restituisce un elemento figlio in corrispondenza dell'indice specificato dalla raccolta di elementi figlio.GetVisualChild: Returns a child at the specified index from the collection of child elements.

  • VisualChildrenCount: Ottiene il numero di elementi figlio visivi in questo elemento.VisualChildrenCount: Gets the number of visual child elements within this element.

Nell'esempio seguente vengono implementate le sostituzioni FrameworkElement per i due membri.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

Supporto per l'hit testingProviding Hit Testing Support

L'oggetto contenitore host può fornire la gestione degli eventi anche se non visualizza alcuna proprietà visibile, ma la relativa Visibility proprietà deve essere impostata su Visible.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. Ciò consente di creare una routine di gestione degli eventi per il contenitore host in grado di intercettare eventi del mouse, ad esempio il rilascio del pulsante sinistro del mouse.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. La routine di gestione degli eventi può quindi implementare l'hit test richiamando il HitTest metodo.The event handling routine can then implement hit testing by invoking the HitTest method. Il HitTestResultCallback parametro del metodo fa riferimento a una procedura definita dall'utente che è possibile usare per determinare l'azione risultante di un hit test.The method's HitTestResultCallback parameter refers to a user-defined procedure that you can use to determine the resulting action of a hit test.

Nell'esempio seguente il supporto per l'hit testing viene implementato per l'oggetto contenitore host e i relativi elementi figlio.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

Vedere ancheSee also