ReportMagic

[Shape.Format:]

Formats a shape in PowerPoint or Word.

Purpose

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

Compatibility

The macro can be used in the highlighted input document types only. A greyed-out icon indicates not supported.

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.

Parameters (35)

Grouped View

Behaviour (5)

Parameter	Type	Presence	Purpose	Options	Default
errorOnOverflow	Boolean	Optional	Should NCalc expression evaluation throw error on Overflow	true false	true
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 theObject, 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
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

Colours (5)

Parameter	Type	Presence	Purpose	Options	Default
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
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
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
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

Formatting (10)

Parameter	Type	Presence	Purpose	Options	Default
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
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
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
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
patternType	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
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

Chart (2)

Parameter	Type	Presence	Purpose	Options	Default
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

Output (2)

Parameter	Type	Presence	Purpose	Options	Default
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
failureVariable	String	Optional	The name of a variable to create should the macro fail to execute. The variable will be a text variable, and will contain either the failure text (only if the failureText parameter is set), otherwise it will contain the exception / failure message.	N/A	N/A

General (10)

Parameter	Type	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
pictureVariable	String	Conditional	The name of the variable that holds the picture to insert into the shape, or the resolved variable content itself. Macros that produce graphs can store the data using the 'storeAsHidden' parameter. You can specify the variable name directly (e.g. pictureVariable=ABC) for a dictionary lookup, use late variable replacement (e.g. pictureVariable={=VarName}) which resolves the variable during macro parameter processing, or use backtick-protected replacement (e.g. pictureVariable=`{VarName}`) to prevent the macro parser from interpreting quotes in the JSON content. 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
desiredExecutionResult	List<ExecutionResult>	Optional	If specified, asserts the expected execution result of the macro. Accepts a single value or a semicolon-separated list of acceptable values (e.g. 'Success;Warning'). The macro executes normally; if the actual result matches any of the desired values, the result is converted to Success. If the actual result does not match, the result is converted to MacroError with a descriptive message. This is primarily used for testing and diagnostic purposes. Valid values are: Unknown, Success, MacroError, WorkerStopped, Running, Warning, NeverRun, Cancelled, Pending, Paused, SystemError, Deferred, Stopped.	Cancelled Deferred MacroError NeverRun Paused Pending Running Stopped Success SystemError Warning WorkerStopped	N/A
expectedType	String	Optional	If specified, asserts the expected output type of the macro result. The macro executes normally; if the actual type does not match, a macro error is generated. Requires 'storeAs', 'storeAsHidden', or 'storeFormattedValueAs' to be set for typed validation. Valid types include CLR names (e.g. Int32, Int64, Single, Double, Boolean, String, JArray, JObject) and C# keyword aliases (e.g. int, long, float, double, bool, string, uint, ulong, short, ushort, byte, sbyte, decimal, char, object). The special value 'Number' matches any numeric type.	N/A	N/A
expectedValue	String	Optional	If specified, asserts the expected output value of the macro result. The macro executes normally; if the actual value does not match, a macro error is generated. When 'storeAs' or 'storeAsHidden' is set, the stored variable value is compared. Otherwise, the document output text is compared.	N/A	N/A
ids	List<String>	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
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

Deprecated (1)

Parameter	Type	Preferred Parameter	Purpose	Options	Default
id	List<String>	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

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]

Purpose

Compatibility

Usage

Examples (11)

Example 1

Example 2

Example 3

Example 4

Example 5

Example 6

Example 7

Example 8

Example 9

Example 10

Example 11

Search

Reconnection

Reconnection

Reconnection