CompositionNineGridBrush Class

Definition

Paints a SpriteVisual with a CompositionBrush after applying Nine-Grid Stretching to the contents of the Source brush. The source of the nine-grid stretch can by any CompositionBrush of type CompositionColorBrush, CompositionSurfaceBrush or a CompositionEffectBrush.

Equivalent WinUI class: Microsoft.UI.Composition.CompositionNineGridBrush.

public ref class CompositionNineGridBrush sealed : CompositionBrush
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 196608)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class CompositionNineGridBrush final : CompositionBrush
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 196608)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class CompositionNineGridBrush : CompositionBrush
Public NotInheritable Class CompositionNineGridBrush
Inherits CompositionBrush
Inheritance
CompositionNineGridBrush
Attributes

Windows 10 requirements

Device family
Windows 10 Anniversary Edition (introduced in 10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v3.0)

Examples

Apply Nine-Grid Stretching to a button asset (@"Windows.UI.Composition.CompositionSurfaceBrush?text=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 (@"Windows.UI.Composition.CompositionColorBrush?text=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:

Stretching of nine-grid sections

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:

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.

Stretching of the nine-grid center

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

Inset from the bottom edge of the source content that specifies the thickness of the bottom row. Defaults to 0.0f.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.BottomInset.

BottomInsetScale

Scale to be applied to BottomInset. Defaults to 1.0f.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.BottomInsetScale.

Comment

A string to associate with the CompositionObject.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.Comment.

(Inherited from CompositionObject)
Compositor

The Compositor used to create this CompositionObject.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.Compositor.

(Inherited from CompositionObject)
Dispatcher

The dispatcher for the CompositionObject.

(Inherited from CompositionObject)
DispatcherQueue

Gets the DispatcherQueue for the CompostionObject.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.DispatcherQueue.

(Inherited from CompositionObject)
ImplicitAnimations

The collection of implicit animations attached to this object.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.ImplicitAnimations.

(Inherited from CompositionObject)
IsCenterHollow

Indicates whether the center of the Nine-Grid is drawn.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.IsCenterHollow.

LeftInset

Inset from the left edge of the source content that specifies the thickness of the left column. Defaults to 0.0f.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.LeftInset.

LeftInsetScale

Scale to be applied to LeftInset. Defaults to 1.0f.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.LeftInsetScale.

Properties

The collection of properties associated with the CompositionObject.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.Properties.

(Inherited from CompositionObject)
RightInset

Inset from the right edge of the source content that specifies the thickness of the right column. Defaults to 0.0f.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.RightInset.

RightInsetScale

Scale to be applied to RightInset. Defaults to 1.0f.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.RightInsetScale.

Source

The brush whose content is to be Nine-Grid stretched. Can be of type CompositionSurfaceBrush or CompositionColorBrush.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.Source.

TopInset

Inset from the top edge of the source content that specifies the thickness of the top row. Defaults to 0.0f.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.TopInset.

TopInsetScale

Scale to be applied to TopInset. Defaults to 1.0f.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionNineGridBrush.TopInsetScale.

Methods

Close()

Closes the CompositionObject and releases system resources.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.Close.

(Inherited from CompositionObject)
ConnectAnimation(String, CompositionAnimation)

Connects and animation.

(Inherited from CompositionObject)
DisconnectAnimation(String)

Disconnects an animation.

(Inherited from CompositionObject)
Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

(Inherited from CompositionObject)
PopulatePropertyInfo(String, AnimationPropertyInfo)

Defines a property that can be animated.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.PopulatePropertyInfo.

(Inherited from CompositionObject)
SetInsets(Single)

Sets the insets of a CompositionNineGridBrush using the same value for the top, bottom, left, and right. Defaults to 0.0f.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionNineGridBrush.SetInsets.

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.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionNineGridBrush.SetInsets.

SetInsetScales(Single)

Sets the (same) scale to be applied to the left, top, right, and bottom insets. Defaults to 1.0f.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionNineGridBrush.SetInsetScales.

SetInsetScales(Single, Single, Single, Single)

Sets the scale to be applied to the left, top, right, and bottom insets respectively. Defaults to 1.0f.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionNineGridBrush.SetInsetScales.

StartAnimation(String, CompositionAnimation)

Connects an animation with the specified property of the object and starts the animation.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.StartAnimation.

(Inherited from CompositionObject)
StartAnimationGroup(ICompositionAnimationBase)

Starts an animation group.

The StartAnimationGroup method on CompositionObject lets you start CompositionAnimationGroup. All the animations in the group will be started at the same time on the object.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.StartAnimationGroup.

(Inherited from CompositionObject)
StopAnimation(String)

Disconnects an animation from the specified property and stops the animation.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.StopAnimation.

(Inherited from CompositionObject)
StopAnimationGroup(ICompositionAnimationBase)

Stops an animation group.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.StopAnimationGroup.

(Inherited from CompositionObject)
TryGetAnimationController(String)

Returns an AnimationController for the animation running on the specified property.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.TryGetAnimationController.

(Inherited from CompositionObject)

Applies to

See also