---

Purpose

Formats a shape in PowerPoint or Word. In Word, you cannot currently set a shape's position.

---

Macro Compatibility

---

Usage

To use in PowerPoint, insert the macro into the notes (the id parameter then MUST be used), or the shape's text (no id required) or its Alt Text (no id required). To use in Word, insert the macro into the document or the shape - the shape ID (any text) must be set in its Alt Text and the id parameter in the macro must refer to it. NOTE: not supported in Report Studio or HTML input documents. For more information on using macros in PowerPoint, see: PowerPoint help. The help below refers mainly to PowerPoint. Word support will be expanded over time.

---

What's New

(2025-06-04)

For picture fills, if only one of heightCm or widthCm is specified, the other dimension will be automatically calculated based on the image's aspect ratio.

---

Parameter	Type	Deprecation Message	Preferred Parameter	Presence	Purpose	Options	Default
pictureFilename	String			Conditional	The filename (or path relative to the input folder) of the picture to insert into the shape. When set, 'fillType' is automatically set to 'Picture'. When set, do not specify 'fillColor' or pictureVariableSupported file extensions are: '.bmp', '.gif', '.jpg', '.jpeg', '.png', '.svg' or '.emfplus'. Works in PowerPoint and Word.	N/A	N/A
pictureTransparencyPercent	Double			Conditional	The shape's picture transparency. Only has an effect when 'fillType' is set to 'Picture'. Works in PowerPoint and Word.	From 0 to 100	N/A
pictureVariable	String			Conditional	The name of the variable that holds the picture to insert into the shape. Macros that produce graphs can store the data using the 'storeAsHidden' parameter. When set, 'fillType' is automatically set to 'Picture'. When set, do not specify 'fillColor' or pictureFilename. Works in PowerPoint and Word.	N/A	N/A
comment	String			Optional	Add a comment to make your document template more readable. The comment is discarded in the output document.	N/A	N/A
errorOnOverflow	Boolean			Optional	Should NCalc expression evaluation throw error on Overflow	true false	true
failureText	String			Optional	The text to display should the macro fail to execute. Note that a poorly-specified macro (e.g. omitting mandatory parameters) will still result in an error message.	N/A	N/A
fillColor	Color			Optional	The shape's fill color. Can be specified as hex e.g. #FF0000 (with or without the #), or as a known color such as red. You can also use alpha values such as #00FF0000 (full transparent) or #FFFF0000 (fully opaque).When used, 'fillType' is automatically set to 'Solid'. When set, do not specify 'pictureFilename'. Works in PowerPoint and Word.	A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.	N/A
fillType	PowerPointFillType			Optional	The shape's fill type. When using 'Picture', the picture will always be stretched to fit the shape. Works in PowerPoint and Word.	None Pattern Picture Solid	N/A
fontColor	Color			Optional	The shape's font color. Can be specified as hex e.g. #FF0000 (with or without the #), or as a known color such as red. Affects all text in the shape. Works in PowerPoint and Word.	A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.	N/A
fontSizePts	Double			Optional	The shape's font size in points. Affects all text in the shape. Works in PowerPoint and Word.	N/A	N/A
heightCm	Double			Optional	The shape's height in centimetres (CM). Works in PowerPoint and Word. When not set, the height of the shape is not altered. For picture fills (fillType=Picture), when set and 'widthCm' is not set, the width is automatically calculated based on the image's aspect ratio.	N/A	N/A
id	List<String>	Deprecated	ids		Specify the ID or IDs of the shapes to format. POWERPOINT: affects shapes on the current slide by default, but you can change the 'Scope' parameter). If not provided, the macro must be in the main text or Alt Text of the shapes to be formatted, otherwise it can be anywhere (Notes, shape text, or Alt Text of a shape). Special case: lines - to format a line, you MUST set an ID in its Alt Text, and use the macro in any other non-line shape's text / Alt Text, or Notes. To edit a shape's Alt Text, right-click on the shape then choose View Alt Text to open the edit panel. NOTE: shape IDs do not need to be unique, i.e. you could set the same ID on multiple shapes, such as SHAPES_TO_FORMAT. WORD: all the above applies, ignoring anything related to slides.	N/A	N/A
ids	List<String>	Use instead of: id		Optional	Specify the ID or IDs of the shapes to format. POWERPOINT: affects shapes on the current slide by default, but you can change the 'Scope' parameter). If not provided, the macro must be in the main text or Alt Text of the shapes to be formatted, otherwise it can be anywhere (Notes, shape text, or Alt Text of a shape). Special case: lines - to format a line, you MUST set an ID in its Alt Text, and use the macro in any other non-line shape's text / Alt Text, or Notes. To edit a shape's Alt Text, right-click on the shape then choose View Alt Text to open the edit panel. NOTE: shape IDs do not need to be unique, i.e. you could set the same ID on multiple shapes, such as SHAPES_TO_FORMAT. WORD: all the above applies, ignoring anything related to slides.	N/A	N/A
if	String			Optional	The condition that must be true in order for the macro to be executed/evaluated. Must either evaluate to true or false, for example: "3+5=8" or "contains('abcd', 'z').	N/A	true
mode	MacroMode			Optional	The mode in which variables are stored. In the legacy mode (default for Schedules), the variable created is a string and formatted. In the normal mode (default for Report Studio), the output variable is stored as a strongly-typed object, e.g. an Int32 or a List etc., rather than a formatted string.	Legacy Normal	Legacy
obfuscation	ObfuscationType			Optional	Obfuscation type. Use obfuscation to write reports where sensitive data is hidden. When used, ReportMagic guarantees that the same input string will map to the same output string for the whole of the report (but the next time the report runs, it will most likely map to a different value). If you use obfuscation, the property in your macro will not show up and instead, you will see a fake item of the obfuscation type chosen.	None UkTown DeviceName Company IpAddress PrivateIpAddress	None
outlineColor	Color			Optional	The shape's outline color. Can be specified as hex e.g. #FF0000 (with or without the #), or as a known color such as red. Works in PowerPoint and Word.	A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.	N/A
outlineDashType	PowerPointOutlineDashType			Optional	The shape's outline dash type. Works in PowerPoint and Word.	Dash DashDot LongDash LongDashDot LongDashDotDot RoundDot Solid SquareDot	N/A
outlineWidthPts	Double			Optional	The shape's outline width in points. Works in PowerPoint and Word.	N/A	N/A
patternFillBackgroundColor	Color			Optional	The shape's pattern fill background color. Can be specified as hex e.g. #FF0000 (with or without the #), or as a known color such as red. Affects all text in the shape. Ignored unless 'fillType' is set to 'Pattern'. When set, you must also set the 'patternType' parameter. Works in PowerPoint and Word.	A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.	N/A
patternFillForegroundColor	Color			Optional	The shape's pattern fill foreground color. Can be specified as hex e.g. #FF0000 (with or without the #), or as a known color such as red. Affects all text in the shape. Ignored unless 'fillType' is set to 'Pattern'. When set, you must also set the 'patternType' parameter. Works in PowerPoint and Word.	A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.	N/A
patternType	DocumentFormat.OpenXml.PresetPatternValues			Optional	The shape's pattern fill type.Ignored unless 'fillType' is set to 'Pattern'. Works in PowerPoint and Word.	Cross DarkDownwardDiagonal DarkHorizontal DarkUpwardDiagonal DarkVertical DashedDownwardDiagonal DashedHorizontal DashedUpwardDiagonal DashedVertical DiagonalBrick DiagonalCross Divot DotGrid DottedDiamond DownwardDiagonal Horizontal HorizontalBrick LargeCheck LargeConfetti LargeGrid LightDownwardDiagonal LightHorizontal LightUpwardDiagonal LightVertical NarrowHorizontal NarrowVertical OpenDiamond Percent10 Percent20 Percent25 Percent30 Percent40 Percent5 Percent50 Percent60 Percent70 Percent75 Percent80 Percent90 Plaid Shingle SmallCheck SmallConfetti SmallGrid SolidDiamond Sphere Trellis UpwardDiagonal Vertical Wave Weave WideDownwardDiagonal WideUpwardDiagonal ZigZag	N/A
positionRelativeTo	PowerPointRelativePositionType			Optional	When setting a shape's position (with 'xAxisPositionCm' and 'yAxisPositionCm', it is relative to the shape's top left, or its centre. Not currently supported in Word.	TopLeft Centre	TopLeft
rotationDegrees	Int32			Optional	The shape's rotation in degrees. Works in PowerPoint and Word.	N/A	N/A
scope	PowerPointScopeType			Optional	Whether to format shapes found on the current slide only, or those anywhere the presentation. Only has an effect when the 'ids' parameter is used, as otherwise the containing shape is formatted. Works in PowerPoint only.	Slide Presentation	Slide
screenTip	String			Optional	The ScreenTip (tooltip) to be used on shape hyperlinks (only has an effect when the 'url' parameter is set). Works in PowerPoint only.	N/A	N/A
url	String			Optional	The website URL to set on a shape. When used, CTRL-click on the shape takes you to the website in the default browser. Works in PowerPoint and Word.	N/A	N/A
warning	String			Optional	If specified, adds a warning message for this macro. This is processed as an NCalc, and the warning message will ALWAYS be present and will be the value of the evaluated NCalc expression.	N/A	N/A
widthCm	Double			Optional	The shape's width in centimetres (CM). Works in PowerPoint and Word. When not set, the width of the shape is not altered. For picture fills (fillType=Picture), when set and 'heightCm' is not set, the height is automatically calculated based on the image's aspect ratio.	N/A	N/A
xAxisPositionCm	Double			Optional	The shape's x-axis position in centimetres (CM), relative to the shape's top left (unless you change the 'positionRelativeTo' parameter). Inspect the PowerPoint document manually to determine the actual width in CM. Not currently supported in Word.	N/A	N/A
yAxisPositionCm	Double			Optional	The shape's y-axis position in centimetres (CM), relative to the shape's top left (unless you change the 'positionRelativeTo' parameter). Inspect the PowerPoint document manually to determine the actual width in CM. Not currently supported in Word.	N/A	N/A

---

Examples (11)

Example 1:

Set the shape's fill color to red using the hex code #FF0000:

[Shape.Format:fillType=Solid, fillColor=#FF0000]

---

Example 2:

Set the shape's fill color to red and its font size to 30 points:

[Shape.Format:fillColor=#FF0000, fillType=Solid, fontSizePts=30]

---

Example 3:

Format all shapes on the current slide that have an ID of 'SHAPES_TO_FORMAT' (set in their Alt Text). In this case set the fill color to red:

[Shape.Format:ids=SHAPES_TO_FORMAT, fillType=Solid, fillColor=#FF0000]

---

Example 4:

Format all shapes anywhere in the presentation that have an ID of 'SHAPES_TO_FORMAT' (set in their Alt Text). In this case set the fill color to blue:

[Shape.Format:ids=SHAPES_TO_FORMAT, fillType=Solid, fillColor=#FF0000, scope=Presentation]

---

Example 5:

Set a combination of properties on the shape (with transparency for the fill):

[Shape.Format:fillColor=#88FF0000, fillType=Solid, fontColor=white, outlineColor=#00FF00, outlineWidthPts=5, outlineDashType=LongDash]

---

Example 6:

Insert a .png image into a shape (stretched to fit is the only available option):

[Shape.Format:fillType=Picture, pictureFilename=images/spiderman.png]

---

Example 7:

Insert a .png image into a shape and specify its width and height in centimetres (the shape will be stretched to fit):

[Shape.Format:fillType=Picture, pictureFilename=images/spiderman.png, widthCm=4, heightCm=3]

---

Example 8:

Insert a .png image into a shape and specify only the width in centimetres. The height will be automatically calculated based on the image's aspect ratio, and so the image will not appear stretched:

[Shape.Format:fillType=Picture, pictureFilename=images/spiderman.png, widthCm=20]

---

Example 9:

Insert a .png image into a shape and specify only the height in centimetres. The width will be automatically calculated based on the image's aspect ratio, and so the image will not appear stretched:

[Shape.Format:fillType=Picture, pictureFilename=images/spiderman.png, heightCm=10]

---

Example 10:

Set a shape's fill to one of the built-in patterns (along with the pattern's background and foreground colours):

[Shape.Format:fillType=Pattern, patternFillBackgroundColor=red, patternFillForegroundColor=black, patternType=SmallCheck]

---

Example 11:

Set a shape's position, size, and rotation:

[Shape.Format:xAxisPositionCm=5, yAxisPositionCm=10, heightCm=10, widthCm15, rotationDegrees=45]