CompositionNineGridBrush
CompositionNineGridBrush
CompositionNineGridBrush
CompositionNineGridBrush
Class
Definition
Paints a SpriteVisual after applying Nine-Grid Stretching to the contents of its Source brush.
public : sealed class CompositionNineGridBrush : CompositionBrush, ICompositionNineGridBrushpublic sealed class CompositionNineGridBrush : CompositionBrush, ICompositionNineGridBrushPublic NotInheritable Class CompositionNineGridBrush Inherits CompositionBrush Implements ICompositionNineGridBrush// This API is not available in Javascript.
- Inheritance
-
CompositionNineGridBrushCompositionNineGridBrushCompositionNineGridBrushCompositionNineGridBrush
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Inherited Members
Inherited methods
Inherited properties
Examples
Apply Nine-Grid Stretching to a button asset (CompositionSurfaceBrush Source)
private SpriteVisual CreateNineGridVisualFromImageSurface(ICompositionSurface imgSurface)
{
CompositionSurfaceBrush sourceBrush = _compositor.CreateSurfaceBrush(imgSurface);
// imgSurface is 50x50 pixels; nine-grid insets, as measured in the asset, are:
// left = 1, top = 5, right = 10, bottom = 20 (in pixels)
// create NineGridBrush to paint onto SpriteVisual
CompositionNineGridBrush ninegridBrush = _compositor.CreateNineGridBrush();
// set SurfaceBrush as Source to NineGridBrush
ninegridBrush.Source = sourceBrush;
// set Nine-Grid Insets
ninegridBrush.SetInsets(1, 5, 10, 20);
// set appropriate Stretch on SurfaceBrush for Center of Nine-Grid
sourceBrush.Stretch = CompositionStretch.Fill;
// create SpriteVisual and paint w/ NineGridBrush
SpriteVisual visual = _compositor.CreateSpriteVisual();
visual.Size = new Vector2(100, 75);
visual.Brush = ninegridBrush;
return visual;
}
Create a solid color border (CompositionColorBrush Source)
private SpriteVisual CreateBorderVisual(SpriteVisual childContent, float borderThickness, Color borderColor)
{
SpriteVisual borderVisual = _compositor.CreateSpriteVisual();
borderVisual.Size = childContent.Size + new Vector2(2 * borderThickness);
// create NineGridBrush w/ ColorBrush Source
CompositionNineGridBrush ninegridBrush = _compositor.CreateNineGridBrush();
ninegridBrush.Source = _compositor.CreateColorBrush(borderColor);
ninegridBrush.SetInsets(borderThickness);
// opt out of drawing Center of Nine-Grid
ninegridBrush.IsCenterHollow = true;
// paint SpriteVisual w/ NineGridBrush
borderVisual.Brush = ninegridBrush;
// set child visual appropriately; manage size/scale changed events separately
childContent.Offset = new Vector3(borderThickness, borderThickness, 0);
borderVisual.Children.InsertAtTop(childContent);
return borderVisual;
}
Using ExpressionAnimation to dynamically update inset scales
private void CounterScaleInsets(SpriteVisual ninegridVisual)
{
CompositionNineGridBrush ninegridBrush = (CompositionNineGridBrush)ninegridVisual.Brush;
// use expressions to counter a scale transformation on visual so as to maintain a constant inset thickness
ExpressionAnimation counterScaleXAnimation = _compositor.CreateExpressionAnimation("1/visual.Scale.X");
counterScaleXAnimation.SetReferenceParameter("visual", ninegridVisual);
ExpressionAnimation counterScaleYAnimation = _compositor.CreateExpressionAnimation("1/visual.Scale.Y");
counterScaleYAnimation.SetReferenceParameter("visual", ninegridVisual);
// start ExpressionAnimation on Nine-Grid InsetScales
ninegridBrush.StartAnimation("LeftInsetScale", counterScaleXAnimation);
ninegridBrush.StartAnimation("RightInsetScale", counterScaleXAnimation);
ninegridBrush.StartAnimation("TopInsetScale", counterScaleYAnimation);
ninegridBrush.StartAnimation("BottomInsetScale", counterScaleYAnimation);
}
Apply an effect to Nine-Grid Stretched content (CompositionNineGridBrush as input to a CompositionEffectBrush )
private void DesaturateNineGridVisual(SpriteVisual ninegridVisual)
{
// get the NineGridBrush that the SpriteVisual is painted with
CompositionNineGridBrush ninegridBrush = (CompositionNineGridBrush)ninegridVisual.Brush;
// get or define IGraphicsEffect
var saturationEffect = new SaturationEffect
{
Saturation = 0f,
Source = new CompositionEffectSourceParameter("source"),
};
// create EffectBrush from EffectFactory
CompositionEffectFactory saturationFactory = _compositor.CreateEffectFactory(saturationEffect);
CompositionEffectBrush saturationBrush = saturationFactory.CreateBrush();
// input NineGridBrush to EffectBrush
saturationBrush.SetSourceParameter("source", ninegridBrush);
// paint SpriteVisual with EffectBrush (w/ NineGridBrush as source parameter)
ninegridVisual.Brush = saturationBrush;
}
Apply Nine-Grid Stretching to an opacity mask (CompositionNineGridBrush as input to a CompositionMaskBrush)
private SpriteVisual CreateMaskedRoundedRectVisual(ICompositionSurface myRoundedRectMaskSurface)
{
// ColorBrush to be set as MaskBrush.Source
CompositionColorBrush colorBrush = _compositor.CreateColorBrush(Colors.Blue);
// SurfaceBrush w/ opacity mask surface
CompositionSurfaceBrush roundedRectBrush = _compositor.CreateSurfaceBrush(myRoundedRectMaskSurface);
roundedRectBrush.Stretch = CompositionStretch.Fill; // stretch for center of nine-grid
// NineGridBrush w/ insets on opacity mask surface
CompositionNineGridBrush ninegridBrush = _compositor.CreateNineGridBrush();
ninegridBrush.Source = roundedRectBrush;
ninegridBrush.SetInsets(_cornerRadius); // the radius, in pixels, of the corner as specified on my opacity mask surface
// Create MaskBrush
CompositionMaskBrush maskBrush = _compositor.CreateMaskBrush();
maskBrush.Source = colorBrush;
maskBrush.Mask = ninegridBrush;
// Paint SpriteVisual with MaskBrush
SpriteVisual sprite = _compositor.CreateSpriteVisual();
sprite.Size = new Vector2(300, 200);
sprite.Brush = maskBrush;
return sprite;
}
Remarks
Nine-Grid stretching refers to the partitioning of visual content (the content of the source brush to be painted onto a SpriteVisual ) into a grid of nine rectangles such that the sizes of the corner rectangles are preserved upon resizing, as shown in the diagram below:

When a SpriteVisual painted with a CompositionNineGridBrush is resized or scaled, the left and right margins (rectangles 4 and 6) stretch along the vertical axis, the top and bottom margins rectangles (rectangles 2 and 8) stretch along the horizontal axis, and the center (rectangle 5) is stretched along both axes while the corners (rectangles 1,3,7, and 9) do not stretch.
The Source property of CompositionNineGridBrush accepts brushes of one of two types:
- CompositionSurfaceBrush: apply Nine-Grid Stretching to a textured image surface.
- CompositionColorBrush: create solid color borders.
Notes on CompositionSurfaceBrush Source
Insets are specified as pixel values that are measured in the coordinate space of the ICompositionSurface that is associated with the CompositionSurfaceBrush. The relationship between an inset specified in the coordinate space of a surface and the inset as it appears when painted on a SpriteVisual is as follows:
Inset_Surface*InsetScale=Inset_SpriteVisual
The CompositionSurfaceBrush.Stretch property specifies how the content of the center of the Nine-Grid is stretched.

NineGridBrush Insets specified on a rounded rectangle asset with CompositionStretch.Fill; the Insets are specified in pixels (measured in the coordinate space of the ICompositionSurface that contains the asset)
CompositionNineGridBrush is not designed to apply Nine-Grid Scaling to a CompositionSurfaceBrush source that has a transformation applied through one of the following properties:
- CompositionSurfaceBrush.AnchorPoint
- CompositionSurfaceBrush.CenterPoint
- CompositionSurfaceBrush.Offset
- CompositionSurfaceBrush.RotationAngle
- CompositionSurfaceBrush.RotationAngleInDegrees
- CompositionSurfaceBrush.Scale
- CompositionSurfaceBrush.TransformMatrix No pixel content will be drawn if there is a transformation operation applied to the CompositionSurfaceBrush source to a CompositionNineGridBrush.
Applying Nine-Grid Stretching to an Opacity Mask
The contents of the CompositionSurfaceBrush source may also be an opacity mask surface. The resulting CompositionNineGridBrush may then be set as Mask to a CompositionMaskBrush. This would allow the content being masked to scale as desired while the opacity mask is subject to Nine-Grid Stretching.
Similarly, the Source to a CompositionMaskBrush may also be of type CompositionNineGridBrush.
Applying an Effect to CompositionNineGridBrush
A CompositionNineGridBrush may be set as source to a CompositionEffectBrush to apply an IGraphics or Windows.UI.Composition.Effect to its Nine-Grid Stretched contents.
Notes on CompositionColorBrush Source
In conjunction with the IsCenterHollow property, a CompositionColorBrush Source allows for the creation of solid color borders. Note that insets for a CompositionColorBrush Source are measured in the coordinate space of the SpriteVisual itself.
Notes on Inset Thickness and Inset Scale
The inset thickness of a CompositionNineGridBrush does not change if the Size property of the associated SpriteVisual is changed.
The inset scale properties provide a mechanism to scale Nine-Grid Insets from the brush’s coordinate space (such as pixel space for an image) to that of the SpriteVisual. For instance, the inset scale properties may be used to control inset thickness in response to scale transformation inherited from the SpriteVisual that the NineGridBrush is painted onto or an arbitrary ancestor in its Visual tree (such as in cases of DPI scale, etc.). In this case, ExpressionAnimation s provide a means to dynamically update values of inset scale.
Properties
BottomInset BottomInset BottomInset BottomInset
Inset from the bottom edge of the source content that specifies the thickness of the bottom row. Defaults to 0.0f.
public : float BottomInset { get; set; }public float BottomInset { get; set; }Public ReadWrite Property BottomInset As float// This API is not available in Javascript.
- Value
- float float float float
Inset from the bottom edge of the source content that specifies the thickness of the bottom row. Defaults to 0.0f.
BottomInsetScale BottomInsetScale BottomInsetScale BottomInsetScale
Scale to be applied to BottomInset. Defaults to 1.0f.
public : float BottomInsetScale { get; set; }public float BottomInsetScale { get; set; }Public ReadWrite Property BottomInsetScale As float// This API is not available in Javascript.
- Value
- float float float float
Scale to be applied to BottomInset. Defaults to 1.0f.
IsCenterHollow IsCenterHollow IsCenterHollow IsCenterHollow
Indicates whether the center of the Nine-Grid is drawn.
public : PlatForm::Boolean IsCenterHollow { get; set; }public bool IsCenterHollow { get; set; }Public ReadWrite Property IsCenterHollow As bool// This API is not available in Javascript.
- Value
- PlatForm::Boolean bool bool bool
Indicates whether the center of the Nine-Grid is drawn.
LeftInset LeftInset LeftInset LeftInset
Inset from the left edge of the source content that specifies the thickness of the left column. Defaults to 0.0f.
public : float LeftInset { get; set; }public float LeftInset { get; set; }Public ReadWrite Property LeftInset As float// This API is not available in Javascript.
- Value
- float float float float
Inset from the left edge of the source content that specifies the thickness of the left column. Defaults to 0.0f.
LeftInsetScale LeftInsetScale LeftInsetScale LeftInsetScale
Scale to be applied to LeftInset. Defaults to 1.0f.
public : float LeftInsetScale { get; set; }public float LeftInsetScale { get; set; }Public ReadWrite Property LeftInsetScale As float// This API is not available in Javascript.
- Value
- float float float float
Scale to be applied to LeftInset. Defaults to 1.0f.
RightInset RightInset RightInset RightInset
Inset from the right edge of the source content that specifies the thickness of the right column. Defaults to 0.0f.
public : float RightInset { get; set; }public float RightInset { get; set; }Public ReadWrite Property RightInset As float// This API is not available in Javascript.
- Value
- float float float float
Inset from the right edge of the source content that specifies the thickness of the right column. Defaults to 0.0f.
RightInsetScale RightInsetScale RightInsetScale RightInsetScale
Scale to be applied to RightInset. Defaults to 1.0f.
public : float RightInsetScale { get; set; }public float RightInsetScale { get; set; }Public ReadWrite Property RightInsetScale As float// This API is not available in Javascript.
- Value
- float float float float
Scale to be applied to RightInset. Defaults to 1.0f.
Source Source Source Source
The brush whose content is to be Nine-Grid stretched. Can be of type CompositionSurfaceBrush or CompositionColorBrush.
public : CompositionBrush Source { get; set; }public CompositionBrush Source { get; set; }Public ReadWrite Property Source As CompositionBrush// This API is not available in Javascript.
The brush whose content is to be scaled using Nine-Grid Scaling. Can be of type CompositionSurfaceBrush or CompositionColorBrush.
TopInset TopInset TopInset TopInset
Inset from the top edge of the source content that specifies the thickness of the top row. Defaults to 0.0f.
public : float TopInset { get; set; }public float TopInset { get; set; }Public ReadWrite Property TopInset As float// This API is not available in Javascript.
- Value
- float float float float
Inset from the top edge of the source content that specifies the thickness of the top row. Defaults to 0.0f.
TopInsetScale TopInsetScale TopInsetScale TopInsetScale
Scale to be applied to TopInset. Defaults to 1.0f.
public : float TopInsetScale { get; set; }public float TopInsetScale { get; set; }Public ReadWrite Property TopInsetScale As float// This API is not available in Javascript.
- Value
- float float float float
Scale to be applied to TopInset. Defaults to 1.0f.
Methods
SetInsets(Single) SetInsets(Single) SetInsets(Single) SetInsets(Single)
Sets the insets of a CompositionNineGridBrush using the same value for the top, bottom, left, and right. Defaults to 0.0f.
public : void SetInsets(float inset)public void SetInsets(Single inset)Public Function SetInsets(inset As Single) As void// This API is not available in Javascript.
- inset
- float Single Single Single
The inset value to use for the top, bottom, left, and right.
- See Also
SetInsets(Single, Single, Single, Single) SetInsets(Single, Single, Single, Single) SetInsets(Single, Single, Single, Single) SetInsets(Single, Single, Single, Single)
Sets the insets of a CompositionNineGridBrush using the specified values for the top, bottom, left, and right. Defaults to 0.0f.
public : void SetInsets(float left, float top, float right, float bottom)public void SetInsets(Single left, Single top, Single right, Single bottom)Public Function SetInsets(left As Single, top As Single, right As Single, bottom As Single) As void// This API is not available in Javascript.
- left
- float Single Single Single
The inset from the left of the image.
- top
- float Single Single Single
The inset from the top of the image.
- right
- float Single Single Single
The inset from the right of the image.
- bottom
- float Single Single Single
The inset from the bottom of the image.
- See Also
SetInsetScales(Single) SetInsetScales(Single) SetInsetScales(Single) SetInsetScales(Single)
Sets the (same) scale to be applied to the left, top, right, and bottom insets. Defaults to 1.0f.
public : void SetInsetScales(float scale)public void SetInsetScales(Single scale)Public Function SetInsetScales(scale As Single) As void// This API is not available in Javascript.
- scale
- float Single Single Single
The scale for all of the insets.
- See Also
SetInsetScales(Single, Single, Single, Single) SetInsetScales(Single, Single, Single, Single) SetInsetScales(Single, Single, Single, Single) SetInsetScales(Single, Single, Single, Single)
Sets the scale to be applied to the left, top, right, and bottom insets respectively. Defaults to 1.0f.
public : void SetInsetScales(float left, float top, float right, float bottom)public void SetInsetScales(Single left, Single top, Single right, Single bottom)Public Function SetInsetScales(left As Single, top As Single, right As Single, bottom As Single) As void// This API is not available in Javascript.
- left
- float Single Single Single
The scale of the left inset.
- top
- float Single Single Single
The scale of the top inset.
- right
- float Single Single Single
The scale of the right inset.
- bottom
- float Single Single Single
The scale of the bottom inset.
- See Also