Cmdlet

Find-OfficePowerPointShape

Module PSWriteOffice

Inputs

OfficeIMO.PowerPoint.PowerPointPresentation OfficeIMO.PowerPoint.PowerPointSlide

Outputs

PSWriteOffice.Services.PowerPoint.PowerPointShapeInfo

Source

FindOfficePowerPointShapeCommand.cs:39 Edit on GitHub

Finds PowerPoint shapes by text, name, kind, or slide.

Syntax

Find-OfficePowerPointShape [-CaseSensitive] [-Index <Int32>] [-Kind <OfficePowerPointShapeKind[]>] [-Name <String[]>] -Presentation <PowerPointPresentation> [-ShapeIndex <Int32[]>] [[-Text] <String>] [<CommonParameters>]

Parameter set: PresentationText

Find-OfficePowerPointShape [-CaseSensitive] [-Index <Int32>] [-Kind <OfficePowerPointShapeKind[]>] [-Name <String[]>] [-Pattern] <String> -Presentation <PowerPointPresentation> [-ShapeIndex <Int32[]>] [<CommonParameters>]

Parameter set: PresentationRegex

Find-OfficePowerPointShape [-CaseSensitive] [-Kind <OfficePowerPointShapeKind[]>] [-Name <String[]>] [-ShapeIndex <Int32[]>] -Slide <PowerPointSlide> [[-Text] <String>] [<CommonParameters>]

Parameter set: SlideText

Find-OfficePowerPointShape [-CaseSensitive] [-Kind <OfficePowerPointShapeKind[]>] [-Name <String[]>] [-Pattern] <String> [-ShapeIndex <Int32[]>] -Slide <PowerPointSlide> [<CommonParameters>]

Parameter set: SlideRegex

Description

Searches an open presentation or a single slide and returns PowerPointShapeInfo records that include the slide index, shape index, shape kind, extracted text, shape name, and the underlying OfficeIMO shape object. Text matching includes normal text boxes and table cell text, so this command can locate the right object before piping it into modification commands.

Use -Text for literal contains matching or -Pattern for regular expressions, or omit both text parameters when -Kind, -Name, -Index, and -ShapeIndex identify the target shape without reading text content.

Examples

Authored help example

Find and update a text box.

Find-OfficePowerPointShape -Presentation $ppt -Text 'FY24' -Kind TextBox |
                Set-OfficePowerPointShapeText -Text 'FY25'

Finds matching text shapes and updates them without using the PowerPoint DSL.

Find a table by cell text and append a new status row.

$ppt = Get-OfficePowerPoint -Path .\Readiness.pptx
$table = Find-OfficePowerPointShape -Presentation $ppt -Text 'Risk' -Kind Table | Select-Object -First 1
$table | Add-OfficePowerPointTableRow -Values 'Latency', 'Investigating'
$ppt | Close-OfficePowerPoint -Save

Uses table-cell text as the locator, then pipes the table shape metadata into a table-row edit.

Parameters

-CaseSensitive SwitchParameter optional: Use case-sensitive matching for text and name filters.
-Index Int32 optionalsets: PresentationText, PresentationRegex: Optional zero-based slide index when reading from a presentation.
-Kind OfficePowerPointShapeKind[] optional: Optional shape kind filter such as TextBox or Table.; Possible values: TextBox, Picture, Table, Chart, AutoShape, GroupShape
-Name String[] optional: Optional wildcard filter for shape names.
-Presentation PowerPointPresentation requiredpipeline: True (ByValue)sets: PresentationText, PresentationRegex: Open presentation whose slides should be searched.
-ShapeIndex Int32[] optional: Optional zero-based shape index filter, useful when several shapes contain the same text.
-Text String optionalposition: 0sets: PresentationText, SlideText: Literal text to find in text boxes and table cells.
-Pattern String requiredposition: 0sets: PresentationRegex, SlideRegex: Regular expression to find in text boxes and table cells.
-Slide PowerPointSlide requiredpipeline: True (ByValue)sets: SlideText, SlideRegex: Single slide to search when the caller has already resolved the slide.

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.

Outputs

PSWriteOffice.Services.PowerPoint.PowerPointShapeInfo: PowerShell-friendly description of a PowerPoint shape.