David CoulterandAndy De George
674b773578
* Links: .NET Desktop - framework\wpf * Apply suggestions from code review Co-authored-by: Andy De George <[email protected]>
25 KiB
title, description, ms.date, helpviewer_keywords, ms.assetid
| title | description | ms.date | helpviewer_keywords | ms.assetid | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Drawing Objects Overview | Get acquainted with objects and how to use them to efficiently draw shapes, bitmaps, text, and media in Windows Presentation Foundation (WPF). | 03/30/2017 |
|
9b5ce5c0-e204-4320-a7a8-0b2210d62f88 |
Drawing Objects Overview
This topic introduces xref:System.Windows.Media.Drawing objects and describes how to use them to efficiently draw shapes, bitmaps, text, and media. Use xref:System.Windows.Media.Drawing objects when you create clip art, paint with a xref:System.Windows.Media.DrawingBrush, or use xref:System.Windows.Media.Visual objects.
What Is a Drawing Object
A xref:System.Windows.Media.Drawing object describes visible content, such as a shape, bitmap, video, or a line of text. Different types of drawings describe different types of content. The following is a list of the different types of drawing objects.
-
xref:System.Windows.Media.GeometryDrawing – Draws a shape.
-
xref:System.Windows.Media.ImageDrawing – Draws an image.
-
xref:System.Windows.Media.GlyphRunDrawing – Draws text.
-
xref:System.Windows.Media.VideoDrawing – Plays an audio or video file.
-
xref:System.Windows.Media.DrawingGroup – Draws other drawings. Use a drawing group to combine other drawings into a single composite drawing.
xref:System.Windows.Media.Drawing objects are versatile; there are many ways you can use a xref:System.Windows.Media.Drawing object.
-
You can display it as an image by using a xref:System.Windows.Media.DrawingImage and an xref:System.Windows.Controls.Image control.
-
You can use it with a xref:System.Windows.Media.DrawingBrush to paint an object, such as the xref:System.Windows.Controls.Page.Background%2A of a xref:System.Windows.Controls.Page.
-
You can use it to describe the appearance of a xref:System.Windows.Media.DrawingVisual.
-
You can use it to enumerate the contents of a xref:System.Windows.Media.Visual.
WPF provides other types of objects that are capable of drawing shapes, bitmaps, text, and media. For example, you can also use xref:System.Windows.Shapes.Shape objects to draw shapes, and the xref:System.Windows.Controls.MediaElement control provides another way to add video to your application. So when should you use xref:System.Windows.Media.Drawing objects? When you can sacrifice framework level features to gain performance benefits or when you need xref:System.Windows.Freezable features. Because xref:System.Windows.Media.Drawing objects lack support for Layout, input, and focus, they provide performance benefits that make them ideal for describing backgrounds, clip art, and for low-level drawing with xref:System.Windows.Media.Visual objects.
Because they are a type xref:System.Windows.Freezable object, xref:System.Windows.Media.Drawing objects gain several special features, which include the following: they can be declared as resources, shared among multiple objects, made read-only to improve performance, cloned, and made thread-safe. For more information about the different features provided by xref:System.Windows.Freezable objects, see the Freezable Objects Overview.
Draw a Shape
To draw a shape, you use a xref:System.Windows.Media.GeometryDrawing. A geometry drawing's xref:System.Windows.Media.GeometryDrawing.Geometry%2A property describes the shape to draw, its xref:System.Windows.Media.GeometryDrawing.Brush%2A property describes how the interior of the shape should be painted, and its xref:System.Windows.Media.GeometryDrawing.Pen%2A property describes how its outline should be drawn.
The following example uses a xref:System.Windows.Media.GeometryDrawing to draw a shape. The shape is described by a xref:System.Windows.Media.GeometryGroup and two xref:System.Windows.Media.EllipseGeometry objects. The shape's interior is painted with a xref:System.Windows.Media.LinearGradientBrush and its outline is drawn with a xref:System.Windows.Media.Brushes.Black%2A xref:System.Windows.Media.Pen.
This example creates the following xref:System.Windows.Media.GeometryDrawing.
A GeometryDrawing
[!code-csharpDrawingMiscSnippets_snip#GeometryDrawingExampleInline] [!code-xamlDrawingMiscSnippets_snip#GeometryDrawingExampleInline]
For the complete example, see Create a GeometryDrawing.
Other xref:System.Windows.Media.Geometry classes, such as xref:System.Windows.Media.PathGeometry enable you to create more complex shapes by creating curves and arcs. For more information about xref:System.Windows.Media.Geometry objects, see the Geometry Overview.
For more information about other ways to draw shapes that don't use xref:System.Windows.Media.Drawing objects, see Shapes and Basic Drawing in WPF Overview.
Draw an Image
To draw an image, you use an xref:System.Windows.Media.ImageDrawing. An xref:System.Windows.Media.ImageDrawing object's xref:System.Windows.Media.ImageDrawing.ImageSource%2A property describes the image to draw, and its xref:System.Windows.Media.ImageDrawing.Rect%2A property defines the region where the image is drawn.
The following example draws an image into a rectangle located at (75,75) that is 100 by 100 pixel. The following illustration shows the xref:System.Windows.Media.ImageDrawing created by the example. A gray border was added to show the bounds of the xref:System.Windows.Media.ImageDrawing.
A 100 by 100 ImageDrawing
[!code-csharpDrawingMiscSnippets_snip#ImageDrawing100by100Inline] [!code-xamlDrawingMiscSnippets_snip#ImageDrawing100by100Inline]
For more information about images, see the Imaging Overview.
Play Media (Code Only)
Note
Although you can declare a xref:System.Windows.Media.VideoDrawing in [!INCLUDETLA#tla_xaml], you can only load and play its media using code. To play video in [!INCLUDETLA#tla_xaml], use a xref:System.Windows.Controls.MediaElement instead.
To play an audio or video file, you use a xref:System.Windows.Media.VideoDrawing and a xref:System.Windows.Media.MediaPlayer. There are two ways to load and play media. The first is to use a xref:System.Windows.Media.MediaPlayer and a xref:System.Windows.Media.VideoDrawing by themselves, and the second way is to create your own xref:System.Windows.Media.MediaTimeline to use with the xref:System.Windows.Media.MediaPlayer and xref:System.Windows.Media.VideoDrawing.
Note
When distributing media with your application, you cannot use a media file as a project resource, like you would an image. In your project file, you must instead set the media type to
Contentand setCopyToOutputDirectorytoPreserveNewestorAlways.
To play media without creating your own xref:System.Windows.Media.MediaTimeline, you perform the following steps.
-
Create a xref:System.Windows.Media.MediaPlayer object.
[!code-csharpDrawingMiscSnippets_snip#VideoDrawingExampleInline1]
-
Use the xref:System.Windows.Media.MediaPlayer.Open%2A method to load the media file.
[!code-csharpDrawingMiscSnippets_snip#VideoDrawingExampleInline2]
-
Create a xref:System.Windows.Media.VideoDrawing.
[!code-csharpDrawingMiscSnippets_snip#VideoDrawingExampleInline3]
-
Specify the size and location to draw the media by setting the xref:System.Windows.Media.VideoDrawing.Rect%2A property of the xref:System.Windows.Media.VideoDrawing.
[!code-csharpDrawingMiscSnippets_snip#VideoDrawingExampleInline4]
-
Set the xref:System.Windows.Media.VideoDrawing.Player%2A property of the xref:System.Windows.Media.VideoDrawing with the xref:System.Windows.Media.MediaPlayer you created.
[!code-csharpDrawingMiscSnippets_snip#VideoDrawingExampleInline5]
-
Use the xref:System.Windows.Media.MediaPlayer.Play%2A method of the xref:System.Windows.Media.MediaPlayer to start playing the media.
[!code-csharpDrawingMiscSnippets_snip#VideoDrawingExampleInline6]
The following example uses a xref:System.Windows.Media.VideoDrawing and a xref:System.Windows.Media.MediaPlayer to play a video file once.
[!code-csharpDrawingMiscSnippets_snip#VideoDrawingExampleInline]
To gain additional timing control over the media, use a xref:System.Windows.Media.MediaTimeline with the xref:System.Windows.Media.MediaPlayer and xref:System.Windows.Media.VideoDrawing objects. The xref:System.Windows.Media.MediaTimeline enables you to specify whether the video should repeat. To use a xref:System.Windows.Media.MediaTimeline with a xref:System.Windows.Media.VideoDrawing, you perform the following steps:
-
Declare the xref:System.Windows.Media.MediaTimeline and set its timing behaviors.
[!code-csharpDrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline1]
-
Create a xref:System.Windows.Media.MediaClock from the xref:System.Windows.Media.MediaTimeline.
[!code-csharpDrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline2]
-
Create a xref:System.Windows.Media.MediaPlayer and use the xref:System.Windows.Media.MediaClock to set its xref:System.Windows.Media.MediaPlayer.Clock%2A property.
[!code-csharpDrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline3]
-
Create a xref:System.Windows.Media.VideoDrawing and assign the xref:System.Windows.Media.MediaPlayer to the xref:System.Windows.Media.VideoDrawing.Player%2A property of the xref:System.Windows.Media.VideoDrawing.
[!code-csharpDrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline4]
The following example uses a xref:System.Windows.Media.MediaTimeline with a xref:System.Windows.Media.MediaPlayer and a xref:System.Windows.Media.VideoDrawing to play a video repeatedly.
[!code-csharpDrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline]
Note that, when you use a xref:System.Windows.Media.MediaTimeline, you use the interactive xref:System.Windows.Media.Animation.ClockController returned from the xref:System.Windows.Media.Animation.Clock.Controller%2A property of the xref:System.Windows.Media.MediaClock to control media playback instead of the interactive methods of xref:System.Windows.Media.MediaPlayer.
Draw Text
To draw text, you use a xref:System.Windows.Media.GlyphRunDrawing and a xref:System.Windows.Media.GlyphRun. The following example uses a xref:System.Windows.Media.GlyphRunDrawing to draw the text "Hello World".
[!code-csharpDrawingMiscSnippets_snip#GlyphRunDrawingExampleInline] [!code-xamlDrawingMiscSnippets_snip#GlyphRunDrawingExampleInline]
A xref:System.Windows.Media.GlyphRun is a low-level object intended for use with fixed-format document presentation and print scenarios. A simpler way to draw text to the screen is to use a xref:System.Windows.Controls.Label or a xref:System.Windows.Controls.TextBlock. For more information about xref:System.Windows.Media.GlyphRun, see the Introduction to the GlyphRun Object and Glyphs Element overview.
Composite Drawings
A xref:System.Windows.Media.DrawingGroup enables you to combine multiple drawings into a single composite drawing. By using a xref:System.Windows.Media.DrawingGroup, you can combine shapes, images, and text into a single xref:System.Windows.Media.Drawing object.
The following example uses a xref:System.Windows.Media.DrawingGroup to combine two xref:System.Windows.Media.GeometryDrawing objects and an xref:System.Windows.Media.ImageDrawing object. This example produces the following output.
A composite drawing
[!code-csharpDrawingMiscSnippets_snip#GraphicsMMSimpleDrawingGroupExample] [!code-xamlDrawingMiscSnippets_snip#GraphicsMMSimpleDrawingGroupExample]
A xref:System.Windows.Media.DrawingGroup also enables you to apply opacity masks, transforms, bitmap effects, and other operations to its contents. xref:System.Windows.Media.DrawingGroup operations are applied in the following order: xref:System.Windows.Media.DrawingGroup.OpacityMask%2A, xref:System.Windows.Media.DrawingGroup.Opacity%2A, xref:System.Windows.Media.DrawingGroup.BitmapEffect%2A, xref:System.Windows.Media.DrawingGroup.ClipGeometry%2A, xref:System.Windows.Media.DrawingGroup.GuidelineSet%2A, and then xref:System.Windows.Media.DrawingGroup.Transform%2A.
The following illustration shows the order in which xref:System.Windows.Media.DrawingGroup operations are applied.
Order of DrawingGroup operations
The following table describes the properties you can use to manipulate a xref:System.Windows.Media.DrawingGroup object's contents.
Display a Drawing as an Image
To display a xref:System.Windows.Media.Drawing with an xref:System.Windows.Controls.Image control, use a xref:System.Windows.Media.DrawingImage as the xref:System.Windows.Controls.Image control's xref:System.Windows.Controls.Image.Source%2A and set the xref:System.Windows.Media.DrawingImage object's xref:System.Windows.Media.DrawingImage.Drawing%2A?displayProperty=nameWithType property to the drawing you want to display.
The following example uses a xref:System.Windows.Media.DrawingImage and an xref:System.Windows.Controls.Image control to display a xref:System.Windows.Media.GeometryDrawing. This example produces the following output.
A DrawingImage
[!code-csharpDrawingMiscSnippets_snip#DrawingImageExampleWholePage] [!code-xamlDrawingMiscSnippets_snip#DrawingImageExampleWholePage]
Paint an Object with a Drawing
A xref:System.Windows.Media.DrawingBrush is a type of brush that paints an area with a drawing object. You can use it to paint just about any graphical object with a drawing. The xref:System.Windows.Media.Drawing property of a xref:System.Windows.Media.DrawingBrush describes its xref:System.Windows.Media.DrawingBrush.Drawing%2A. To render a xref:System.Windows.Media.Drawing with a xref:System.Windows.Media.DrawingBrush, add it to the brush using the brush's xref:System.Windows.Media.Drawing property and use the brush to paint a graphical object, such as a control or panel.
The following examples uses a xref:System.Windows.Media.DrawingBrush to paint the xref:System.Windows.Shapes.Shape.Fill%2A of a xref:System.Windows.Shapes.Rectangle with a pattern created from a xref:System.Windows.Media.GeometryDrawing. This example produces the following output.
A GeometryDrawing used with a DrawingBrush
[!code-csharpDrawingMiscSnippets_snip#DrawingBrushExampleWholePage] [!code-xamlDrawingMiscSnippets_snip#DrawingBrushExampleWholePage]
The xref:System.Windows.Media.DrawingBrush class provides a variety of options for stretching and tiling its content. For more information about xref:System.Windows.Media.DrawingBrush, see the Painting with Images, Drawings, and Visuals overview.
Render a Drawing with a Visual
A xref:System.Windows.Media.DrawingVisual is a type of visual object designed to render a drawing. Working directly at the visual layer is an option for developers who want to build a highly customized graphical environment, and is not described in this overview. For more information, see the Using DrawingVisual Objects overview.
DrawingContext Objects
The xref:System.Windows.Media.DrawingContext class enables you to populate a xref:System.Windows.Media.Visual or a xref:System.Windows.Media.Drawing with visual content. Many such lower-level graphics objects use a xref:System.Windows.Media.DrawingContext because it describes graphical content very efficiently.
Although the xref:System.Windows.Media.DrawingContext draw methods appear similar to the draw methods of the xref:System.Drawing.Graphics?displayProperty=nameWithType type, they are actually very different. xref:System.Windows.Media.DrawingContext is used with a retained mode graphics system, while the xref:System.Drawing.Graphics?displayProperty=nameWithType type is used with an immediate mode graphics system. When you use a xref:System.Windows.Media.DrawingContext object's draw commands, you are actually storing a set of rendering instructions (although the exact storage mechanism depends on the type of object that supplies the xref:System.Windows.Media.DrawingContext) that will later be used by the graphics system; you are not drawing to the screen in real-time. For more information about how the Windows Presentation Foundation (WPF) graphics system works, see the WPF Graphics Rendering Overview.
You never directly instantiate a xref:System.Windows.Media.DrawingContext; you can, however, acquire a drawing context from certain methods, such as xref:System.Windows.Media.DrawingGroup.Open%2A?displayProperty=nameWithType and xref:System.Windows.Media.DrawingVisual.RenderOpen%2A?displayProperty=nameWithType.
Enumerate the Contents of a Visual
In addition to their other uses, xref:System.Windows.Media.Drawing objects also provide an object model for enumerating the contents of a xref:System.Windows.Media.Visual.
The following example uses the xref:System.Windows.Media.VisualTreeHelper.GetDrawing%2A method to retrieve the xref:System.Windows.Media.DrawingGroup value of a xref:System.Windows.Media.Visual and enumerate it.
[!code-csharpDrawingMiscSnippets_snip#GraphicsMMRetrieveDrawings]