Stone_Red/docs-desktop
1
0
Fork 0
mirror of https://github.com/Stone-Red-Code/docs-desktop.git synced 2026-09-09 16:06:09 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
live
docs-desktop/dotnet-desktop-guide/framework/wpf/graphics-multimedia/painting-with-images-drawings-and-visuals.md
T
Andy (Steve) De George be103da07e Replace various WPF include files with content (#1335) 
* net-current-v30plus-md.md

* net-current-v40plus-md.md

* tla2sharptla-ui-md.md

* tla2sharptla-uiautomation-md.md

* tla2sharptla-winclient-md.md

* tla2sharptla-xaml-md.md

* tlasharptla-ui-md.md

* tlasharptla-uiautomation-md.md

* tlasharptla-winclient-md.md

* tlasharptla-xaml-md.md

* fix warnings
2022-03-16 12:14:11 -04:00

15 KiB
Raw Permalink Blame History

title, ms.date, dev_langs, helpviewer_keywords, ms.assetid
title ms.date dev_langs helpviewer_keywords ms.assetid
Painting with Images, Drawings, and Visuals 03/30/2017
csharp
vb
brushes [WPF], painting with drawings
painting [WPF], with drawings
painting [WPF], with images
painting with visuals [WPF]
brushes [WPF], painting with images
brushes [WPF], painting with visuals
779aac3f-8d41-49d8-8130-768244aa2240

Painting with Images, Drawings, and Visuals

This topic describes how to use xref:System.Windows.Media.ImageBrush, xref:System.Windows.Media.DrawingBrush, and xref:System.Windows.Media.VisualBrush objects to paint an area with an image, a xref:System.Windows.Media.Drawing, or a xref:System.Windows.Media.Visual.

Prerequisites

To understand this topic, you should be familiar with the different types of brushes Windows Presentation Foundation (WPF) provides and their basic features. For an introduction, see the WPF Brushes Overview.

Paint an Area with an Image

An xref:System.Windows.Media.ImageBrush paints an area with an xref:System.Windows.Media.ImageSource. The most common type of xref:System.Windows.Media.ImageSource to use with an xref:System.Windows.Media.ImageBrush is a xref:System.Windows.Media.Imaging.BitmapImage, which describes a bitmap graphic. You can use a xref:System.Windows.Media.DrawingImage to paint using a xref:System.Windows.Media.Drawing object, but it is simpler to use a xref:System.Windows.Media.DrawingBrush instead. For more information about xref:System.Windows.Media.ImageSource objects, see the Imaging Overview.

To paint with an xref:System.Windows.Media.ImageBrush, create a xref:System.Windows.Media.Imaging.BitmapImage and use it to load the bitmap content. Then, use the xref:System.Windows.Media.Imaging.BitmapImage to set the xref:System.Windows.Media.ImageBrush.ImageSource%2A property of the xref:System.Windows.Media.ImageBrush. Finally, apply the xref:System.Windows.Media.ImageBrush to the object you want to paint. In Extensible Application Markup Language (XAML), you can also just set the xref:System.Windows.Media.ImageBrush.ImageSource%2A property of the xref:System.Windows.Media.ImageBrush with the path of the image to load.

Like all xref:System.Windows.Media.Brush objects, an xref:System.Windows.Media.ImageBrush can be used to paint objects such as shapes, panels, controls, and text. The following illustration shows some effects that can be achieved with an xref:System.Windows.Media.ImageBrush.

ImageBrush output examples
Objects painted by an ImageBrush

By default, an xref:System.Windows.Media.ImageBrush stretches its image to completely fill the area being painted, possibly distorting the image if the painted area has a different aspect ratio than the image. You can change this behavior by changing the xref:System.Windows.Media.TileBrush.Stretch%2A property from its default value of xref:System.Windows.Media.Stretch.Fill to xref:System.Windows.Media.Stretch.None, xref:System.Windows.Media.Stretch.Uniform, or xref:System.Windows.Media.Stretch.UniformToFill. Because xref:System.Windows.Media.ImageBrush is a type of xref:System.Windows.Media.TileBrush, you can specify exactly how an image brush fills the output area and even create patterns. For more information about advanced xref:System.Windows.Media.TileBrush features, see the TileBrush Overview.

Example: Paint an Object with a Bitmap Image

The following example uses an xref:System.Windows.Media.ImageBrush to paint the xref:System.Windows.Controls.Panel.Background%2A of a xref:System.Windows.Controls.Canvas.

[!code-xamlBrushOverviewExamples_snip#GraphicsMMImageBrushAsCanvasBackgroundExampleWholePage]

[!code-csharpBrushOverviewExamples_procedural_snip#GraphicsMMImageBrushAsCanvasBackgroundExampleWholePage] [!code-vbBrushOverviewExamples_procedural_snip#GraphicsMMImageBrushAsCanvasBackgroundExampleWholePage]

Paint an Area with a Drawing

A xref:System.Windows.Media.DrawingBrush enables you to paint an area with shapes, text, images, and video. Shapes inside a drawing brush may themselves be painted with a solid color, gradient, image, or even another xref:System.Windows.Media.DrawingBrush. The following illustration demonstrates some uses of a xref:System.Windows.Media.DrawingBrush.

DrawingBrush output examples
Objects painted by a DrawingBrush

A xref:System.Windows.Media.DrawingBrush paints an area with a xref:System.Windows.Media.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.

For more information about xref:System.Windows.Media.Drawing objects, see the Drawing Objects Overview.

Like an xref:System.Windows.Media.ImageBrush, a xref:System.Windows.Media.DrawingBrush stretches its xref:System.Windows.Media.DrawingBrush.Drawing%2A to fill its output area. You can override this behavior by changing the xref:System.Windows.Media.TileBrush.Stretch%2A property from its default setting of xref:System.Windows.Media.Stretch.Fill. For more information, see the xref:System.Windows.Media.TileBrush.Stretch%2A property.

Example: Paint an Object with a Drawing

The following example shows how to paint an object with a drawing of three ellipses. A xref:System.Windows.Media.GeometryDrawing is used to describe the ellipses.

[!code-xamlBrushOverviewExamples_snip#GraphicsMMDrawingBrushAsButtonBackgroundExample]

[!code-csharpBrushOverviewExamples_procedural_snip#GraphicsMMDrawingBrushAsButtonBackgroundExample1] [!code-vbBrushOverviewExamples_procedural_snip#GraphicsMMDrawingBrushAsButtonBackgroundExample1]

Paint an Area with a Visual

The most versatile and powerful of all the brushes, the xref:System.Windows.Media.VisualBrush paints an area with a xref:System.Windows.Media.Visual. A xref:System.Windows.Media.Visual is a low-level graphical type that serves as the ancestor of many useful graphical components. For example, the xref:System.Windows.Window, xref:System.Windows.FrameworkElement, and xref:System.Windows.Controls.Control classes are all types of xref:System.Windows.Media.Visual objects. Using a xref:System.Windows.Media.VisualBrush, you can paint areas with almost any Windows Presentation Foundation (WPF) graphical object.

Note

Although xref:System.Windows.Media.VisualBrush is a type of xref:System.Windows.Freezable object, it cannot be frozen (made read-only) when its xref:System.Windows.Media.VisualBrush.Visual%2A property is set to a value other than null.

There are two ways to specify the xref:System.Windows.Media.VisualBrush.Visual%2A content of a xref:System.Windows.Media.VisualBrush.

When you define a new xref:System.Windows.Media.VisualBrush.Visual%2A for a xref:System.Windows.Media.VisualBrush and that xref:System.Windows.Media.Visual is a xref:System.Windows.UIElement (such as a panel or control), the layout system runs on the xref:System.Windows.UIElement and its child elements when the xref:System.Windows.Media.VisualBrush.AutoLayoutContent%2A property is set to true. However, the root xref:System.Windows.UIElement is essentially isolated from the rest of the system: styles, and external layout can't permeate this boundary. Therefore, you should explicitly specify the size of the root xref:System.Windows.UIElement, because its only parent is the xref:System.Windows.Media.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.

Like xref:System.Windows.Media.ImageBrush and xref:System.Windows.Media.DrawingBrush, a xref:System.Windows.Media.VisualBrush stretches its content to fill its output area. You can override this behavior by changing the xref:System.Windows.Media.TileBrush.Stretch%2A property from its default setting of xref:System.Windows.Media.Stretch.Fill. For more information, see the xref:System.Windows.Media.TileBrush.Stretch%2A property.

Example: Paint an Object with a Visual

In the following example, several controls and a panel are used to paint a rectangle.

[!code-xamlBrushOverviewExamples_snip#GraphicsMMVisualBrushAsRectangleBackgroundExample]

[!code-csharpBrushOverviewExamples_procedural_snip#GraphicsMMVisualBrushAsRectangleBackgroundExample1] [!code-vbBrushOverviewExamples_procedural_snip#GraphicsMMVisualBrushAsRectangleBackgroundExample1]

Example: Create a Reflection

The preceding example showed how to create a new xref:System.Windows.Media.Visual for use as a background. You can also use a xref:System.Windows.Media.VisualBrush to display an existing visual; this capability enables you to produce interesting visual effects, such as reflections and magnification. The following example uses a xref:System.Windows.Media.VisualBrush to create a reflection of a xref:System.Windows.Controls.Border that contains several elements. The following illustration shows the output that this example produces.

A reflected Visual object
A reflected Visual object

[!code-csharpvisualbrush_markup_snip#GraphicsMMVisualBrushReflectionExampleWholePage] [!code-vbvisualbrush_markup_snip#GraphicsMMVisualBrushReflectionExampleWholePage] [!code-xamlvisualbrush_markup_snip#GraphicsMMVisualBrushReflectionExampleWholePage]

For additional examples that show how to magnify portions of the screen and how to create reflections, see the VisualBrush Sample.

TileBrush Features

xref:System.Windows.Media.ImageBrush, xref:System.Windows.Media.DrawingBrush, and xref:System.Windows.Media.VisualBrush are types of xref:System.Windows.Media.TileBrush objects. xref:System.Windows.Media.TileBrush objects provide you with a great deal of control over how an area is painted with an image, drawing, or visual. For example, instead of just painting an area with a single stretched image, you can paint an area with a series of image tiles that create a pattern.

A xref:System.Windows.Media.TileBrush has three primary components: content, tiles, and the output area.

TileBrush components
Components of a TileBrush with a single tile

Components of a tiled TileBrush
Components of a TileBrush with multiple tiles

For more information about the tiling features of xref:System.Windows.Media.TileBrush objects, see the TileBrush Overview.

See also

Reference in New Issue View Git Blame Copy Permalink